Files
Sluijsens e59c3ba4ef Adds Chakra UI CLI, self-hosted fonts, and prettier config
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.
2026-10-02 00:17:39 +02:00

12 KiB
Raw Permalink Blame History

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.

  • 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.