Chakra UI v3 Patterns

Quick Guide: Chakra UI v3 styles through props (bg, p, color) rather than class names, and composes every complex component from parts (Dialog.Root, Dialog.Content). It dropped framer-motion and @emotion/styled — CSS animations and recipes replaced them — and every v2 closed component API (isOpen, useDisclosure, extendTheme) is gone.

Detailed Resources:

• examples/core.md — provider setup, layout components, typography, buttons, forms, the chakra factory, asChild
• examples/theming.md — custom tokens, semantic tokens, recipes, slot recipes, dark-mode setup
• examples/composable-components.md — Dialog, Menu, Popover, Drawer, Tabs and their controlled forms
• reference.md — style-prop and semantic-token tables, breakpoints, the v2→v3 migration reference

---

<critical_requirements>

Before writing Chakra UI code

Build a system with createSystem(defaultConfig, config) and hand it to ChakraProvider value={system}. Components read their tokens, recipes and conditions from that system, and render unstyled without it.

Declare the cascade layers in your root CSS: @layer reset, base, tokens, recipes;. The generated styles are emitted into those layers, and without the declaration the browser orders them arbitrarily.

Compose from parts — Dialog.Root, Dialog.Content, Dialog.Footer. v3 removed the closed component APIs, so the compound form is the only one that exists.

Style through style props, the css prop or the chakra factory. They resolve token values and conditions; a raw className string bypasses the token system and the dark-mode adaptation with it.

Reach for semantic tokens (bg.subtle, fg.muted) before any per-mode branching. They already carry a light and a dark value, so most dark-mode work disappears.

</critical_requirements>

---

Auto-detection: @chakra-ui/react, ChakraProvider, createSystem, defaultConfig, defaultSystem, defineConfig, defineRecipe, defineSlotRecipe, createSlotRecipeContext, useRecipe, chakra factory, colorPalette, semanticTokens, _dark, asChild, Field.Root, Dialog.Root, onOpenChange details, @chakra-ui/cli snippet

Applies to:

• React screens built from an accessible, composable component set
• Styling through props and conditions rather than a separate stylesheet
• Token-driven theming: raw tokens, semantic tokens, and per-component recipes
• Component variants through defineRecipe and defineSlotRecipe
• Dark mode with no conditional logic at the call site

Handled elsewhere:

• Form state, schemas and submission — Field supplies the label, help text and error slot plus their ARIA wiring; which runtime owns the values plugs in through invalid and the control's own props.
• Server state and caching — components take data as props and settle nothing about where it came from.
• Icons — v3 ships none; every component that takes an icon takes it as a child.
• Zero-runtime CSS — styles are generated at runtime here, so a build-time-only pipeline is a different choice.
• A separate CSS methodology — style props, recipes and the css prop are the styling surface; mixing a second one means managing layer order yourself.

---

<philosophy>

Philosophy

Chakra v3 sits on three things: Ark UI for headless behaviour and accessibility, a token-and-recipe API executed through Emotion at runtime, and Park UI as the default look. What follows from that:

1. Composable over configurable — compound parts replace prop-heavy components, so any part can be styled, replaced or reordered.
2. Tokens over hardcoded values — colours, spacing and radii reference the system, which is what makes a global change one edit.
3. Recipes over runtime style functions — variants are declared once and resolved to atomic classes.
4. Semantic tokens over conditionals — bg.subtle already knows both modes, so the call site carries no branch.
5. CSS animations over JS — no animation runtime ships with the library.

</philosophy>

---

<decision_framework>

Decision Framework

How should this be styled?

A standard Chakra component            -> style props: <Box bg="blue.500" p="4" />
It needs variants (size, tone, state)  -> defineRecipe
A multi-part component (card, table)   -> defineSlotRecipe + createSlotRecipeContext
A plain element that wants style props -> chakra("div")
A genuine one-off                      -> the css prop, or inline style props

Which overlay?

Destructive confirmation  -> Dialog with role="alertdialog"
Form or detailed content  -> Dialog
Edge-anchored panel       -> Drawer (placement="start" | "end" | "top" | "bottom")
Info anchored to a trigger-> Popover
List of commands          -> Menu

Which form control?

Single-line text     -> Input
Multi-line           -> Textarea
Few options          -> RadioGroup or SegmentedControl
Many options         -> Select
Boolean toggle       -> Switch
Agreement            -> Checkbox
Around any of them   -> Field.Root + Field.Label + Field.ErrorMessage

</decision_framework>

---

<patterns>

Core Patterns

Pattern 1: Provider Setup

createSystem merges your config into the defaults; the result is what ChakraProvider distributes.

import { createSystem, defaultConfig, defineConfig } from "@chakra-ui/react";

const config = defineConfig({
  theme: {
    tokens: { colors: { brand: { 500: { value: "#d53f8c" } } } },
  },
});

export const system = createSystem(defaultConfig, config);

<ChakraProvider value={system}>{children}</ChakraProvider>;

Token values always take the { value: "..." } form and become CSS variables. For zero config, import defaultSystem instead of calling createSystem.

Full code: examples/core.md

---

Pattern 2: Style Props

Props map to CSS properties, with shorthand aliases and token-aware values.

<Box bg="blue.500" color="white" p="4" rounded="md" shadow="lg" />;

<Box mt="4" px="6" w="full" maxW="md" mx="auto" />;

<Flex gap="4" align="center" justify="between" wrap="wrap">
  <Text fontSize="lg" fontWeight="bold">
    Title
  </Text>
  <Text color="fg.muted">Subtitle</Text>
</Flex>;

Full prop table: reference.md. Layout components: examples/core.md

---

Pattern 3: Responsive Values

Any style prop takes an object keyed by breakpoint, mobile-first from base.

<Box
  p={{ base: "4", md: "6", lg: "8" }}
  display={{ base: "block", md: "flex" }}
/>;

<Box p={["4", "4", "6"]} />;
{
  /* positional: base, sm, md, … */
}
<Text fontWeight={{ mdToXl: "bold" }} />;
{
  /* range targeting */
}
<Box hideBelow="md">Wide viewports only</Box>;

Breakpoint values: reference.md

---

Pattern 4: Composable Components

Every complex component is Root > Trigger > Content > …, and asChild hands the trigger's props to your own element rather than nesting two interactive nodes.

<Dialog.Root>
  <Dialog.Trigger asChild>
    <Button>Open</Button>
  </Dialog.Trigger>
  <Dialog.Backdrop />
  <Dialog.Content>
    <Dialog.Header>Confirm Action</Dialog.Header>
    <Dialog.Body>Are you sure?</Dialog.Body>
    <Dialog.Footer>
      <Dialog.CloseTrigger asChild>
        <Button variant="outline">Cancel</Button>
      </Dialog.CloseTrigger>
      <Button colorPalette="red">Confirm</Button>
    </Dialog.Footer>
  </Dialog.Content>
</Dialog.Root>

Full code: examples/composable-components.md

---

Pattern 5: Recipes and Variants

defineRecipe for a single element, defineSlotRecipe for a multi-part one. colorPalette.* values inside a recipe resolve against whatever palette the call site sets.

import { chakra, defineRecipe } from "@chakra-ui/react";

const badgeRecipe = defineRecipe({
  base: { display: "inline-flex", rounded: "full", fontWeight: "medium" },
  variants: {
    variant: {
      solid: { bg: "colorPalette.500", color: "white" },
      subtle: { bg: "colorPalette.100", color: "colorPalette.800" },
    },
    size: { sm: { px: "2", fontSize: "xs" }, md: { px: "3", fontSize: "sm" } },
  },
  defaultVariants: { variant: "subtle", size: "sm" },
});

const Badge = chakra("span", badgeRecipe);

<Badge variant="solid" colorPalette="green" size="md">
  Active
</Badge>;

Register it with defineConfig({ theme: { recipes: { badge: badgeRecipe } } }) to reach it through useRecipe as well.

Full code: examples/theming.md

---

Pattern 6: Dark Mode

Semantic tokens carry both modes, so the common case has no branch at all.

<Box bg="bg.subtle" color="fg" borderColor="border" />;

<Box bg="white" _dark={{ bg: "gray.800" }} />;
{
  /* per-mode override */
}
<Box bg={{ base: "white", _dark: "gray.800" }} />;
{
  /* inline condition */
}

The provider and toggle come from a generated snippet rather than a package: npx @chakra-ui/cli snippet add color-mode.

Full code: examples/theming.md

---

Pattern 7: Form Fields

Field owns the label, help text, error slot and the ARIA relationships between them; the validity flag comes from wherever the values live.

<Stack gap="4">
  <Field.Root required invalid={!!errors.password}>
    <Field.Label>Password</Field.Label>
    <Input type="password" />
    <Field.HelperText>At least 12 characters.</Field.HelperText>
    <Field.ErrorMessage>{errors.password}</Field.ErrorMessage>
  </Field.Root>
  <Button type="submit" colorPalette="blue">
    Sign In
  </Button>
</Stack>

Full code: examples/core.md

</patterns>

---

<red_flags>

Red flags

Breaks at runtime:

• Rendering without ChakraProvider — components silently lose their styles, since there is no system to resolve tokens against.
• @layer reset, base, tokens, recipes; missing from the root CSS — layer order is then arbitrary and styles land in the wrong precedence.
• v2 APIs: isOpen/onClose, useDisclosure, extendTheme, ChakraProvider theme={...} — all removed in v3, none with a deprecation shim.
• Importing framer-motion or @emotion/styled as Chakra dependencies — dropped in v3; motion is CSS and styled components come from the chakra factory.
• Flat sub-component imports — import { ModalHeader } and import { ListItem } are now Dialog.Header and List.Item.
• Importing icons from @chakra-ui/icons — the package is gone.

Surprising behaviour:

• onOpenChange receives { open: boolean }, not a bare boolean: onOpenChange={(details) => setOpen(details.open)}.
• is-prefixed booleans lost the prefix — disabled, loading, invalid, required.
• spacing on Stack is now gap.
• className strings on a Chakra component are passed through untouched — the token system, the type checking and the dark-mode adaptation all sit on style props instead.
• colorPalette swaps the palette for a whole subtree, so every descendant reading colorPalette.* changes with it.
• Several "components" are CLI-generated snippets under your own source tree (npx @chakra-ui/cli snippet add), not package exports — they are yours to edit and yours to keep updated.
• useColorModeValue still works, but a semantic token does the same job without the hook and without the render it costs.
• defaultSystem is the zero-config shortcut; reaching for createSystem(defaultConfig) with no second argument produces the same thing more slowly.

</red_flags>