---
name: chakra-ui
description: Builds accessible React applications with Chakra UI v3 components, tokens, and recipes. Use when creating styled component systems, theming, or accessible form controls.
---
# Chakra UI v3
Accessible React component library with built-in styling, theming, and design tokens.
## Quick Start
```bash
npm i @chakra-ui/react @emotion/react
# Add pre-built component snippets
npx @chakra-ui/cli snippet add
```
```tsx
// components/ui/provider.tsx (generated by CLI)
import { ChakraProvider, defaultSystem } from '@chakra-ui/react'
export function Provider({ children }: { children: React.ReactNode }) {
return {children}
}
```
```tsx
// app layout
import { Provider } from '@/components/ui/provider'
export default function RootLayout({ children }) {
return (
{children}
)
}
```
```tsx
// Usage
import { Button, HStack, Text } from '@chakra-ui/react'
function Demo() {
return (
)
}
```
## Core Concepts
### Compound Components (v3)
Chakra v3 uses compound components with dot notation:
```tsx
import { Accordion } from '@chakra-ui/react'
function FAQ() {
return (
What is Chakra UI?
A component library for React.
)
}
```
### Style Props
Apply styles directly via props:
```tsx
import { Box, Flex, Text } from '@chakra-ui/react'
Styled box
Title
Subtitle
```
### Common Style Props
| Prop | CSS Property | Example |
|------|--------------|---------|
| `bg` | background | `bg="blue.500"` |
| `color` | color | `color="gray.700"` |
| `p`, `px`, `py` | padding | `p="4"` `px="6"` |
| `m`, `mx`, `my` | margin | `m="auto"` `my="8"` |
| `w`, `h` | width, height | `w="full"` `h="100vh"` |
| `rounded` | border-radius | `rounded="lg"` |
| `shadow` | box-shadow | `shadow="md"` |
| `display` | display | `display="flex"` |
| `gap` | gap | `gap="4"` |
## Components
### Button
```tsx
import { Button, ButtonGroup } from '@chakra-ui/react'
```
### Input and Forms
```tsx
import { Field, Input, Textarea, NativeSelect } from '@chakra-ui/react'
Email
We'll never share your email
Password
Password is required
Country
```
### Dialog (Modal)
```tsx
import { Button, Dialog, Portal } from '@chakra-ui/react'
import { useState } from 'react'
function ModalExample() {
const [open, setOpen] = useState(false)
return (
setOpen(e.open)}>
Dialog Title
Dialog content goes here.
)
}
```
### Menu
```tsx
import { Button, Menu, Portal } from '@chakra-ui/react'
Edit
Duplicate
Delete
```
### Tabs
```tsx
import { Tabs } from '@chakra-ui/react'
Account
Settings
Billing
Account settings...
App settings...
Billing info...
```
### Card
```tsx
import { Card, Button, Image, Text } from '@chakra-ui/react'
Product Name
High-quality product description here.
$99.00
```
## Theming
### Custom Theme
```tsx
// theme.ts
import { createSystem, defaultConfig, defineConfig } from '@chakra-ui/react'
const config = defineConfig({
theme: {
tokens: {
colors: {
brand: {
50: { value: '#e6f2ff' },
100: { value: '#b3d9ff' },
200: { value: '#80bfff' },
300: { value: '#4da6ff' },
400: { value: '#1a8cff' },
500: { value: '#0073e6' },
600: { value: '#005cb3' },
700: { value: '#004480' },
800: { value: '#002d4d' },
900: { value: '#00161a' },
},
},
fonts: {
heading: { value: 'Inter, sans-serif' },
body: { value: 'Inter, sans-serif' },
},
},
semanticTokens: {
colors: {
brand: {
solid: { value: '{colors.brand.500}' },
contrast: { value: 'white' },
fg: { value: '{colors.brand.700}' },
muted: { value: '{colors.brand.100}' },
subtle: { value: '{colors.brand.50}' },
emphasized: { value: '{colors.brand.200}' },
focusRing: { value: '{colors.brand.500}' },
},
},
},
},
})
export const system = createSystem(defaultConfig, config)
```
```tsx
// provider.tsx
import { ChakraProvider } from '@chakra-ui/react'
import { system } from './theme'
export function Provider({ children }) {
return {children}
}
```
### Semantic Tokens
Chakra v3 provides 7 semantic tokens per color palette:
| Token | Purpose |
|-------|---------|
| `solid` | Background for solid buttons |
| `contrast` | Text on solid backgrounds |
| `fg` | Foreground/text color |
| `muted` | Muted backgrounds |
| `subtle` | Subtle backgrounds |
| `emphasized` | Hover states |
| `focusRing` | Focus ring color |
```tsx
Semantic tokens adjust for light/dark mode
```
### Dark Mode
```tsx
import { useColorMode, ColorModeButton } from '@chakra-ui/react'
function ThemeToggle() {
const { colorMode, toggleColorMode } = useColorMode()
return (
)
}
// Or use built-in button
```
## Recipes (Component Variants)
### Defining Recipes
```tsx
import { defineRecipe } from '@chakra-ui/react'
const buttonRecipe = defineRecipe({
base: {
display: 'inline-flex',
alignItems: 'center',
justifyContent: 'center',
fontWeight: 'medium',
rounded: 'lg',
transition: 'all 0.2s',
},
variants: {
visual: {
solid: {
bg: 'brand.500',
color: 'white',
_hover: { bg: 'brand.600' },
},
outline: {
border: '2px solid',
borderColor: 'brand.500',
color: 'brand.500',
},
},
size: {
sm: { h: '8', px: '3', fontSize: 'sm' },
md: { h: '10', px: '4', fontSize: 'md' },
lg: { h: '12', px: '6', fontSize: 'lg' },
},
},
defaultVariants: {
visual: 'solid',
size: 'md',
},
})
```
### Slot Recipes (Multi-part Components)
```tsx
import { defineSlotRecipe } from '@chakra-ui/react'
const cardRecipe = defineSlotRecipe({
slots: ['root', 'header', 'body', 'footer'],
base: {
root: {
bg: 'white',
rounded: 'xl',
shadow: 'md',
overflow: 'hidden',
},
header: {
p: '4',
borderBottom: '1px solid',
borderColor: 'gray.200',
},
body: {
p: '4',
},
footer: {
p: '4',
borderTop: '1px solid',
borderColor: 'gray.200',
},
},
variants: {
variant: {
elevated: {
root: { shadow: 'xl' },
},
outline: {
root: {
shadow: 'none',
border: '1px solid',
borderColor: 'gray.200',
},
},
},
},
})
```
## Responsive Styles
```tsx
// Object syntax
Responsive content
// Array syntax (mobile-first)
Responsive text
```
Breakpoints: `base` (0px), `sm` (480px), `md` (768px), `lg` (992px), `xl` (1280px), `2xl` (1536px)
## Layout Components
```tsx
import { Box, Flex, Grid, Stack, Container, Center } from '@chakra-ui/react'
// Flex layout
Item 1
Item 2
// Grid layout
Cell 1
Cell 2
Cell 3
// Stack (vertical by default)
Item 1
Item 2
// HStack / VStack
...
...
// Container with max-width
Centered content
// Center content
Centered both ways
```
## Best Practices
1. **Use compound components** - Prefer `Dialog.Root`, `Dialog.Content` over flat imports
2. **Leverage semantic tokens** - Use `brand.solid` instead of `brand.500` for theme flexibility
3. **Use snippets** - Run `npx @chakra-ui/cli snippet add` for pre-built patterns
4. **Responsive object syntax** - Clearer than array syntax for complex responsive styles
5. **Recipes for variants** - Define component variants in theme, not inline
## Reference Files
- [references/components.md](references/components.md) - Component API reference
- [references/theming.md](references/theming.md) - Advanced theming patterns