Moves prettier config into web/, adds @chakra-ui/cli for typegen and the fontsource font packages needed for self-hosted Jost and Marcellus, and brings in the chakra-ui-* skill docs.
288 lines
12 KiB
Markdown
288 lines
12 KiB
Markdown
# Chakra UI Component Decision Tree
|
||
|
||
When the user hasn't specified a component, choose the most appropriate one
|
||
based on the guidelines below. Prefer an existing Chakra component over a custom
|
||
implementation. Match the interaction model first, then the visual treatment.
|
||
Prefer the narrowest component that fits — don't reach for `Box` when a more
|
||
specific primitive exists.
|
||
|
||
---
|
||
|
||
## Layout and structure
|
||
|
||
- Use `Stack` (or `VStack`) for a vertical sequence of elements with consistent
|
||
spacing.
|
||
- Use `HStack` for a horizontal sequence of elements with consistent spacing.
|
||
- Use `Flex` when you need explicit control over flexbox properties (direction,
|
||
wrap, alignment).
|
||
- Use `Grid` + `GridItem` for two-dimensional layouts (rows and columns).
|
||
- Use `SimpleGrid` for equal-width columns that wrap automatically — good for
|
||
card grids and dashboards.
|
||
- Use `Container` to constrain page content to a max-width with horizontal
|
||
centering.
|
||
- Use `Center` to center content both horizontally and vertically without manual
|
||
flex setup.
|
||
- Use `AbsoluteCenter` when centering with `position: absolute` — useful for
|
||
overlays and loaders.
|
||
- Use `Card` when content is a self-contained unit that needs visual separation
|
||
(border, shadow, padding). Use `Box` only when no built-in container semantics
|
||
apply.
|
||
- Use `Wrap` for tag clouds, badge sets, or button groups that should flow and
|
||
wrap automatically.
|
||
- Use `Spacer` inside `Flex` to push elements to opposite ends.
|
||
- Use `Group` to visually merge related elements (buttons, inputs) into a single
|
||
bordered unit.
|
||
- Use `Bleed` to extend a background or image beyond the padding of its parent
|
||
container.
|
||
- Use `Splitter` when the user should be able to resize two adjacent panels.
|
||
- Use `ScrollArea` for a container that needs custom cross-browser styled
|
||
scrollbars.
|
||
- Use `AspectRatio` to lock a child element (video, image, map) to a fixed
|
||
aspect ratio.
|
||
|
||
### Stack vs Flex vs Grid
|
||
|
||
- Choose `Stack` or `HStack`/`VStack` for uniform spacing along one axis — it's
|
||
the most common case.
|
||
- Choose `Flex` when you need `flexWrap`, `justifyContent`, `alignItems`, or
|
||
other flex properties beyond spacing.
|
||
- Choose `Grid` when you need to position elements across both rows and columns
|
||
at the same time.
|
||
- Choose `SimpleGrid` when you only need responsive equal-width columns and
|
||
nothing more.
|
||
|
||
---
|
||
|
||
## Typography
|
||
|
||
- Use `Heading` for page and section titles (`h1`–`h6`). Don't use `Text` as a
|
||
heading shortcut.
|
||
- Use `Text` for body copy, labels, and descriptive text.
|
||
- Use `Span` for inline styled text inside a paragraph.
|
||
- Use `Em` and `Strong` for semantically emphasized or important text.
|
||
- Use `Mark` for highlighted text (e.g. search result matches).
|
||
- Use `Code` for short inline code snippets.
|
||
- Use `CodeBlock` for multi-line code with copy button and optional collapse —
|
||
not for single-line snippets.
|
||
- Use `Kbd` to display keyboard shortcuts.
|
||
- Use `Blockquote` for pull quotes with attribution.
|
||
- Use `Highlight` to highlight matching substrings dynamically in text.
|
||
|
||
---
|
||
|
||
## Actions and links
|
||
|
||
- Use `Button` for primary and secondary actions (form submissions,
|
||
confirmations, key page actions).
|
||
- Use `IconButton` for icon-only actions — always provide `aria-label`.
|
||
- Use `CloseButton` for dismiss/close actions in dialogs, drawers, and toasts.
|
||
- Use `ButtonGroup` to group related actions (e.g. Save / Cancel) with
|
||
consistent sizing and variant.
|
||
- Use `Link` for text navigation — inline within a sentence or standalone. Use
|
||
`asChild` with Next.js `<Link>` in App Router projects.
|
||
- Use `LinkBox` + `LinkOverlay` to make an entire card or row clickable while
|
||
preserving accessible markup.
|
||
- Use `Toggle` when a button should visually represent an on/off pressed state.
|
||
- Use `Switch` (not `Toggle`) when the interaction is a persistent on/off
|
||
setting (e.g. enable notifications).
|
||
- Use `DownloadTrigger` for file download buttons.
|
||
|
||
---
|
||
|
||
## Choosing from options
|
||
|
||
- Use `Switch` for turning a single setting on or off.
|
||
- Use `Checkbox` for a single independent yes/no option. Use `CheckboxGroup` for
|
||
a set of independent options where many can be selected.
|
||
- Use `CheckboxCard` over `Checkbox` when the option needs a title, description,
|
||
or more visual emphasis.
|
||
- Use `RadioGroup` for mutually exclusive options when 2–4 options should always
|
||
be visible.
|
||
- Use `RadioCard` over `RadioGroup` when each option benefits from a
|
||
description, icon, or richer presentation.
|
||
- Use `SegmentGroup` for a compact mutually exclusive mode/view switch
|
||
(iOS-style segmented control) — typically 2–4 options.
|
||
- Use `NativeSelect` for mobile-first dropdowns where the platform picker is
|
||
preferred.
|
||
- Use `Select` for styled dropdowns with full design control — prefer over
|
||
`NativeSelect` on desktop.
|
||
- Use `Combobox` when the user should type to filter a long list or search
|
||
options — prefer over `Select` for lists longer than ~15 items.
|
||
- Use `Listbox` when options must always be visible and scrollable without a
|
||
dropdown trigger.
|
||
- Use `TagsInput` for entering multiple free-form or autocompleted values
|
||
(skills, labels, emails).
|
||
- Use `RatingGroup` for star or point ratings.
|
||
|
||
### Select vs Combobox vs NativeSelect
|
||
|
||
- Choose `NativeSelect` for mobile-first or form-heavy interfaces where native
|
||
picker behavior is expected.
|
||
- Choose `Select` for styled dropdowns on desktop with a known, bounded list.
|
||
- Choose `Combobox` when filtering/searching is important or the list is long.
|
||
|
||
---
|
||
|
||
## Text and value input
|
||
|
||
- Use `Input` for single-line plain text.
|
||
- Use `Textarea` for multi-line text.
|
||
- Use `NumberInput` for numeric entry with increment/decrement controls.
|
||
- Use `Slider` for adjusting a value when direct manipulation is preferred over
|
||
exact entry. Use a range slider (dual thumbs) for min/max ranges.
|
||
- Use `PinInput` for fixed-length codes — OTP verification, PIN entry. It
|
||
auto-advances focus between fields.
|
||
- Use `Editable` for click-to-edit inline text — useful for titles,
|
||
descriptions, and table cells.
|
||
- Use `DatePicker` when a calendar popover should assist with date selection.
|
||
- Use `ColorPicker` for full color selection with RGB/HSL/hex modes and
|
||
eyedropper.
|
||
- Use `FileUpload` for file selection with drag-and-drop and preview.
|
||
- Use `Clipboard` for copy-to-clipboard functionality with visual feedback.
|
||
- Use `Field.Root` to wrap every form input — it wires up the label, helper
|
||
text, error text, and required indicator correctly.
|
||
- Use `InputGroup` to attach prefix/suffix addons (icons, currency symbols,
|
||
units) to an `Input`.
|
||
- Use `Fieldset` to group semantically related form fields under a shared
|
||
legend.
|
||
|
||
---
|
||
|
||
## Overlays and pop-ups
|
||
|
||
- Use `Tooltip` for a short text description of a focusable element. Don't put
|
||
interactive content in a tooltip.
|
||
- Use `HoverCard` for richer preview content on hover (user profiles, link
|
||
previews) — more than a tooltip, less than a popover.
|
||
- Use `Popover` for interactive contextual content anchored to a trigger —
|
||
forms, filters, settings panels.
|
||
- Use `Dialog` for modal tasks that require user attention before continuing.
|
||
- Use `Drawer` for off-canvas panels — navigation, detail views, settings — when
|
||
modal behavior is needed but the content is beside rather than over the page.
|
||
- Use `Toast` for brief transient feedback after an action (saved, error,
|
||
copied). Use the `Toaster` component to render stacked toasts.
|
||
- Use `ActionBar` for mobile-style bulk action bars that appear after selection.
|
||
- Use `Menu` for action menus triggered by a button — "more options",
|
||
right-click menus. Use `Menu.CheckboxItem` and `Menu.RadioItem` for
|
||
toggle/selection actions within a menu.
|
||
|
||
### Tooltip vs HoverCard vs Popover
|
||
|
||
- Choose `Tooltip` for a single line of non-interactive help text.
|
||
- Choose `HoverCard` for hover-triggered preview cards with structured content.
|
||
- Choose `Popover` when the floating content needs to be interactive (has
|
||
buttons, inputs, or links).
|
||
|
||
### Dialog vs Drawer
|
||
|
||
- Choose `Dialog` when the overlay should be centered, blocking, and focus
|
||
attention on a specific task or confirmation.
|
||
- Choose `Drawer` when the content slides in from an edge and relates to what's
|
||
already on screen (details, navigation, filters).
|
||
|
||
---
|
||
|
||
## Disclosure and navigation
|
||
|
||
- Use `Accordion` for a set of related collapsible sections where only one (or a
|
||
few) should be open at a time — FAQs, grouped settings.
|
||
- Use `Collapsible` for a single expandable section — don't use `Accordion` with
|
||
one item.
|
||
- Use `Tabs` for peer content panels where switching shows one panel at a time —
|
||
prefer for horizontal layouts.
|
||
- Use `SegmentGroup` instead of `Tabs` when switching modes or views rather than
|
||
showing different full content panels.
|
||
- Use `Steps` for multi-step wizards and onboarding flows — shows progress and
|
||
allows back/next navigation.
|
||
- Use `Breadcrumb` to show the user's location in a hierarchy.
|
||
- Use `Pagination` for navigating paged datasets.
|
||
- Use `Menu` for dropdown navigation menus.
|
||
- Use `TreeView` when a file-system-style hierarchy must stay visible and
|
||
expandable in place.
|
||
|
||
### Accordion vs Tabs vs Collapsible
|
||
|
||
- Choose `Accordion` for vertically stacked collapsible sections (FAQs, settings
|
||
groups).
|
||
- Choose `Tabs` for horizontal peer sections where all tabs are always visible.
|
||
- Choose `Collapsible` for a single show/hide section — not a group.
|
||
|
||
---
|
||
|
||
## Data display
|
||
|
||
- Use `Table` for structured tabular data with rows and columns — sortable
|
||
headers, dense comparison.
|
||
- Use `DataList` for key-value pairs (user profile details, metadata) — not true
|
||
tabular data.
|
||
- Use `Stat` + `StatGroup` for KPI metrics and dashboard numbers with up/down
|
||
indicators.
|
||
- Use `Timeline` for chronological events, changelogs, or process steps.
|
||
- Use `Badge` for compact non-removable status labels (Active, Beta, New).
|
||
- Use `Tag` over `Badge` when the label should be removable or interactive.
|
||
- Use `Avatar` + `AvatarGroup` for user profile pictures with fallback initials
|
||
or icon.
|
||
- Use `Carousel` for image galleries, feature showcases, or content sliders.
|
||
- Use `QrCode` to render a QR code from a string value.
|
||
- Use `ColorSwatch` to display a color value visually.
|
||
|
||
### Table vs DataList
|
||
|
||
- Choose `Table` when data has multiple comparable columns and rows.
|
||
- Choose `DataList` for a single record's attributes displayed as label/value
|
||
pairs.
|
||
|
||
---
|
||
|
||
## Feedback and status
|
||
|
||
- Use `Alert` for persistent in-page messages (warnings, info, errors) that are
|
||
part of the page layout.
|
||
- Use `Toast` for transient post-action feedback — it disappears automatically.
|
||
- Use `EmptyState` for no-data and no-results states — provides structured
|
||
layout for illustration, title, description, and actions.
|
||
- Use `Spinner` for indeterminate loading — content is fetching, duration
|
||
unknown.
|
||
- Use `Skeleton` for loading placeholders that approximate the shape of incoming
|
||
content.
|
||
- Use `Progress` for a linear progress bar on an operation with a known
|
||
completion percentage.
|
||
- Use `ProgressCircle` for the same use case when a circular indicator fits the
|
||
layout better.
|
||
- Use `Loader` as an alternative to `Spinner` for a different visual style of
|
||
indeterminate loading.
|
||
|
||
### Alert vs Toast vs EmptyState
|
||
|
||
- Choose `Alert` when the message is persistent and tied to content on the
|
||
current view.
|
||
- Choose `Toast` when the message is temporary and triggered by a user action.
|
||
- Choose `EmptyState` when there is no content to display and you want to
|
||
explain why and offer a next action.
|
||
|
||
### Spinner vs Skeleton vs Progress
|
||
|
||
- Choose `Spinner` when loading is happening and the layout isn't known yet.
|
||
- Choose `Skeleton` when the layout is known — show placeholder shapes that
|
||
match the expected content.
|
||
- Choose `Progress` when the operation has a measurable percentage.
|
||
|
||
---
|
||
|
||
## Utilities
|
||
|
||
- Use `VisuallyHidden` for screen-reader-only text — skip links, icon button
|
||
labels added outside the button.
|
||
- Use `SkipNav` to add a skip-to-main-content accessibility link.
|
||
- Use `Portal` when a component must render outside its DOM parent to avoid
|
||
z-index or overflow clipping issues.
|
||
- Use `FocusTrap` to constrain keyboard focus within a region (custom modals,
|
||
custom drawers).
|
||
- Use `Presence` to animate components on mount and unmount.
|
||
- Use `Show` / `Hide` for responsive conditional rendering based on breakpoints.
|
||
- Use `For` as a typed loop utility when rendering lists of components.
|
||
- Use `ClientOnly` to prevent SSR hydration mismatches for browser-only content.
|
||
- Use `FormatNumber` / `FormatByte` for locale-aware number and file-size
|
||
formatting.
|
||
- Use `Marquee` for scrolling announcement banners or news tickers.
|