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.
12 KiB
12 KiB
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(orVStack) for a vertical sequence of elements with consistent spacing. - Use
HStackfor a horizontal sequence of elements with consistent spacing. - Use
Flexwhen you need explicit control over flexbox properties (direction, wrap, alignment). - Use
Grid+GridItemfor two-dimensional layouts (rows and columns). - Use
SimpleGridfor equal-width columns that wrap automatically — good for card grids and dashboards. - Use
Containerto constrain page content to a max-width with horizontal centering. - Use
Centerto center content both horizontally and vertically without manual flex setup. - Use
AbsoluteCenterwhen centering withposition: absolute— useful for overlays and loaders. - Use
Cardwhen content is a self-contained unit that needs visual separation (border, shadow, padding). UseBoxonly when no built-in container semantics apply. - Use
Wrapfor tag clouds, badge sets, or button groups that should flow and wrap automatically. - Use
SpacerinsideFlexto push elements to opposite ends. - Use
Groupto visually merge related elements (buttons, inputs) into a single bordered unit. - Use
Bleedto extend a background or image beyond the padding of its parent container. - Use
Splitterwhen the user should be able to resize two adjacent panels. - Use
ScrollAreafor a container that needs custom cross-browser styled scrollbars. - Use
AspectRatioto lock a child element (video, image, map) to a fixed aspect ratio.
Stack vs Flex vs Grid
- Choose
StackorHStack/VStackfor uniform spacing along one axis — it's the most common case. - Choose
Flexwhen you needflexWrap,justifyContent,alignItems, or other flex properties beyond spacing. - Choose
Gridwhen you need to position elements across both rows and columns at the same time. - Choose
SimpleGridwhen you only need responsive equal-width columns and nothing more.
Typography
- Use
Headingfor page and section titles (h1–h6). Don't useTextas a heading shortcut. - Use
Textfor body copy, labels, and descriptive text. - Use
Spanfor inline styled text inside a paragraph. - Use
EmandStrongfor semantically emphasized or important text. - Use
Markfor highlighted text (e.g. search result matches). - Use
Codefor short inline code snippets. - Use
CodeBlockfor multi-line code with copy button and optional collapse — not for single-line snippets. - Use
Kbdto display keyboard shortcuts. - Use
Blockquotefor pull quotes with attribution. - Use
Highlightto highlight matching substrings dynamically in text.
Actions and links
- Use
Buttonfor primary and secondary actions (form submissions, confirmations, key page actions). - Use
IconButtonfor icon-only actions — always providearia-label. - Use
CloseButtonfor dismiss/close actions in dialogs, drawers, and toasts. - Use
ButtonGroupto group related actions (e.g. Save / Cancel) with consistent sizing and variant. - Use
Linkfor text navigation — inline within a sentence or standalone. UseasChildwith Next.js<Link>in App Router projects. - Use
LinkBox+LinkOverlayto make an entire card or row clickable while preserving accessible markup. - Use
Togglewhen a button should visually represent an on/off pressed state. - Use
Switch(notToggle) when the interaction is a persistent on/off setting (e.g. enable notifications). - Use
DownloadTriggerfor file download buttons.
Choosing from options
- Use
Switchfor turning a single setting on or off. - Use
Checkboxfor a single independent yes/no option. UseCheckboxGroupfor a set of independent options where many can be selected. - Use
CheckboxCardoverCheckboxwhen the option needs a title, description, or more visual emphasis. - Use
RadioGroupfor mutually exclusive options when 2–4 options should always be visible. - Use
RadioCardoverRadioGroupwhen each option benefits from a description, icon, or richer presentation. - Use
SegmentGroupfor a compact mutually exclusive mode/view switch (iOS-style segmented control) — typically 2–4 options. - Use
NativeSelectfor mobile-first dropdowns where the platform picker is preferred. - Use
Selectfor styled dropdowns with full design control — prefer overNativeSelecton desktop. - Use
Comboboxwhen the user should type to filter a long list or search options — prefer overSelectfor lists longer than ~15 items. - Use
Listboxwhen options must always be visible and scrollable without a dropdown trigger. - Use
TagsInputfor entering multiple free-form or autocompleted values (skills, labels, emails). - Use
RatingGroupfor star or point ratings.
Select vs Combobox vs NativeSelect
- Choose
NativeSelectfor mobile-first or form-heavy interfaces where native picker behavior is expected. - Choose
Selectfor styled dropdowns on desktop with a known, bounded list. - Choose
Comboboxwhen filtering/searching is important or the list is long.
Text and value input
- Use
Inputfor single-line plain text. - Use
Textareafor multi-line text. - Use
NumberInputfor numeric entry with increment/decrement controls. - Use
Sliderfor adjusting a value when direct manipulation is preferred over exact entry. Use a range slider (dual thumbs) for min/max ranges. - Use
PinInputfor fixed-length codes — OTP verification, PIN entry. It auto-advances focus between fields. - Use
Editablefor click-to-edit inline text — useful for titles, descriptions, and table cells. - Use
DatePickerwhen a calendar popover should assist with date selection. - Use
ColorPickerfor full color selection with RGB/HSL/hex modes and eyedropper. - Use
FileUploadfor file selection with drag-and-drop and preview. - Use
Clipboardfor copy-to-clipboard functionality with visual feedback. - Use
Field.Rootto wrap every form input — it wires up the label, helper text, error text, and required indicator correctly. - Use
InputGroupto attach prefix/suffix addons (icons, currency symbols, units) to anInput. - Use
Fieldsetto group semantically related form fields under a shared legend.
Overlays and pop-ups
- Use
Tooltipfor a short text description of a focusable element. Don't put interactive content in a tooltip. - Use
HoverCardfor richer preview content on hover (user profiles, link previews) — more than a tooltip, less than a popover. - Use
Popoverfor interactive contextual content anchored to a trigger — forms, filters, settings panels. - Use
Dialogfor modal tasks that require user attention before continuing. - Use
Drawerfor off-canvas panels — navigation, detail views, settings — when modal behavior is needed but the content is beside rather than over the page. - Use
Toastfor brief transient feedback after an action (saved, error, copied). Use theToastercomponent to render stacked toasts. - Use
ActionBarfor mobile-style bulk action bars that appear after selection. - Use
Menufor action menus triggered by a button — "more options", right-click menus. UseMenu.CheckboxItemandMenu.RadioItemfor toggle/selection actions within a menu.
Tooltip vs HoverCard vs Popover
- Choose
Tooltipfor a single line of non-interactive help text. - Choose
HoverCardfor hover-triggered preview cards with structured content. - Choose
Popoverwhen the floating content needs to be interactive (has buttons, inputs, or links).
Dialog vs Drawer
- Choose
Dialogwhen the overlay should be centered, blocking, and focus attention on a specific task or confirmation. - Choose
Drawerwhen the content slides in from an edge and relates to what's already on screen (details, navigation, filters).
Disclosure and navigation
- Use
Accordionfor a set of related collapsible sections where only one (or a few) should be open at a time — FAQs, grouped settings. - Use
Collapsiblefor a single expandable section — don't useAccordionwith one item. - Use
Tabsfor peer content panels where switching shows one panel at a time — prefer for horizontal layouts. - Use
SegmentGroupinstead ofTabswhen switching modes or views rather than showing different full content panels. - Use
Stepsfor multi-step wizards and onboarding flows — shows progress and allows back/next navigation. - Use
Breadcrumbto show the user's location in a hierarchy. - Use
Paginationfor navigating paged datasets. - Use
Menufor dropdown navigation menus. - Use
TreeViewwhen a file-system-style hierarchy must stay visible and expandable in place.
Accordion vs Tabs vs Collapsible
- Choose
Accordionfor vertically stacked collapsible sections (FAQs, settings groups). - Choose
Tabsfor horizontal peer sections where all tabs are always visible. - Choose
Collapsiblefor a single show/hide section — not a group.
Data display
- Use
Tablefor structured tabular data with rows and columns — sortable headers, dense comparison. - Use
DataListfor key-value pairs (user profile details, metadata) — not true tabular data. - Use
Stat+StatGroupfor KPI metrics and dashboard numbers with up/down indicators. - Use
Timelinefor chronological events, changelogs, or process steps. - Use
Badgefor compact non-removable status labels (Active, Beta, New). - Use
TagoverBadgewhen the label should be removable or interactive. - Use
Avatar+AvatarGroupfor user profile pictures with fallback initials or icon. - Use
Carouselfor image galleries, feature showcases, or content sliders. - Use
QrCodeto render a QR code from a string value. - Use
ColorSwatchto display a color value visually.
Table vs DataList
- Choose
Tablewhen data has multiple comparable columns and rows. - Choose
DataListfor a single record's attributes displayed as label/value pairs.
Feedback and status
- Use
Alertfor persistent in-page messages (warnings, info, errors) that are part of the page layout. - Use
Toastfor transient post-action feedback — it disappears automatically. - Use
EmptyStatefor no-data and no-results states — provides structured layout for illustration, title, description, and actions. - Use
Spinnerfor indeterminate loading — content is fetching, duration unknown. - Use
Skeletonfor loading placeholders that approximate the shape of incoming content. - Use
Progressfor a linear progress bar on an operation with a known completion percentage. - Use
ProgressCirclefor the same use case when a circular indicator fits the layout better. - Use
Loaderas an alternative toSpinnerfor a different visual style of indeterminate loading.
Alert vs Toast vs EmptyState
- Choose
Alertwhen the message is persistent and tied to content on the current view. - Choose
Toastwhen the message is temporary and triggered by a user action. - Choose
EmptyStatewhen there is no content to display and you want to explain why and offer a next action.
Spinner vs Skeleton vs Progress
- Choose
Spinnerwhen loading is happening and the layout isn't known yet. - Choose
Skeletonwhen the layout is known — show placeholder shapes that match the expected content. - Choose
Progresswhen the operation has a measurable percentage.
Utilities
- Use
VisuallyHiddenfor screen-reader-only text — skip links, icon button labels added outside the button. - Use
SkipNavto add a skip-to-main-content accessibility link. - Use
Portalwhen a component must render outside its DOM parent to avoid z-index or overflow clipping issues. - Use
FocusTrapto constrain keyboard focus within a region (custom modals, custom drawers). - Use
Presenceto animate components on mount and unmount. - Use
Show/Hidefor responsive conditional rendering based on breakpoints. - Use
Foras a typed loop utility when rendering lists of components. - Use
ClientOnlyto prevent SSR hydration mismatches for browser-only content. - Use
FormatNumber/FormatBytefor locale-aware number and file-size formatting. - Use
Marqueefor scrolling announcement banners or news tickers.