Documentation for theming Chakra UI v3.
# Animations
## Keyframes
Chakra UI supports the following keyframes out of the box.
| Animation Key | Example |
| ------------------------ | --------------------------------------------- |
| `spin` | |
| `pulse` | |
| `ping` | |
| `bounce` | |
| `bg-position` | |
| `position` | |
| `circular-progress` | |
| `expand-height` | |
| `collapse-height` | |
| `expand-width` | |
| `collapse-width` | |
| `fade-in` | |
| `fade-out` | |
| `slide-from-left-full` | |
| `slide-from-right-full` | |
| `slide-from-top-full` | |
| `slide-from-bottom-full` | |
| `slide-to-left-full` | |
| `slide-to-right-full` | |
| `slide-to-top-full` | |
| `slide-to-bottom-full` | |
| `slide-from-top` | |
| `slide-from-bottom` | |
| `slide-from-left` | |
| `slide-from-right` | |
| `slide-to-top` | |
| `slide-to-bottom` | |
| `slide-to-left` | |
| `slide-to-right` | |
| `scale-in` | |
| `scale-out` | |
## Durations
Chakra UI supports the following durations out of the box.
| Duration Token | Value | Example |
| -------------- | ------- | --------------------------------------------------------- |
| `slowest` | `500ms` | |
| `slower` | `400ms` | |
| `slow` | `300ms` | |
| `moderate` | `200ms` | |
| `fast` | `150ms` | |
| `faster` | `100ms` | |
| `fastest` | `50ms` | |
# Aspect Ratios
## Tokens
Chakra UI supports the following aspect ratios out of the box.
| Aspect Ratio Token | Value | Example |
| ------------------ | ----------- | ------------------------------- |
| `square` | `1 / 1` | |
| `landscape` | `4 / 3` | |
| `portrait` | `3 / 4` | |
| `wide` | `16 / 9` | |
| `ultrawide` | `18 / 5` | |
| `golden` | `1.618 / 1` | |
# Breakpoints
Chakra UI supports the following breakpoints out of the box.
| Breakpoint Token | Example |
| ---------------- | --------------------------------- |
| `sm` | |
| `md` | |
| `lg` | |
| `xl` | |
| `2xl` | |
# Colors
## Tokens
Chakra UI supports the following color tokens out of the box.
| Color Token | Value | Example |
| ------------ | --------- | ------------------------------------------ |
| `gray.50` | `#fafafa` | |
| `gray.100` | `#f4f4f5` | |
| `gray.200` | `#e4e4e7` | |
| `gray.300` | `#d4d4d8` | |
| `gray.400` | `#a1a1aa` | |
| `gray.500` | `#71717a` | |
| `gray.600` | `#52525b` | |
| `gray.700` | `#3f3f46` | |
| `gray.800` | `#27272a` | |
| `gray.900` | `#18181b` | |
| `gray.950` | `#111111` | |
| `red.50` | `#fef2f2` | |
| `red.100` | `#fee2e2` | |
| `red.200` | `#fecaca` | |
| `red.300` | `#fca5a5` | |
| `red.400` | `#f87171` | |
| `red.500` | `#ef4444` | |
| `red.600` | `#dc2626` | |
| `red.700` | `#991919` | |
| `red.800` | `#511111` | |
| `red.900` | `#300c0c` | |
| `red.950` | `#1f0808` | |
| `orange.50` | `#fff7ed` | |
| `orange.100` | `#ffedd5` | |
| `orange.200` | `#fed7aa` | |
| `orange.300` | `#fdba74` | |
| `orange.400` | `#fb923c` | |
| `orange.500` | `#f97316` | |
| `orange.600` | `#ea580c` | |
| `orange.700` | `#92310a` | |
| `orange.800` | `#6c2710` | |
| `orange.900` | `#3b1106` | |
| `orange.950` | `#220a04` | |
| `yellow.50` | `#fefce8` | |
| `yellow.100` | `#fef9c3` | |
| `yellow.200` | `#fef08a` | |
| `yellow.300` | `#fde047` | |
| `yellow.400` | `#facc15` | |
| `yellow.500` | `#eab308` | |
| `yellow.600` | `#ca8a04` | |
| `yellow.700` | `#845209` | |
| `yellow.800` | `#713f12` | |
| `yellow.900` | `#422006` | |
| `yellow.950` | `#281304` | |
| `green.50` | `#f0fdf4` | |
| `green.100` | `#dcfce7` | |
| `green.200` | `#bbf7d0` | |
| `green.300` | `#86efac` | |
| `green.400` | `#4ade80` | |
| `green.500` | `#22c55e` | |
| `green.600` | `#16a34a` | |
| `green.700` | `#116932` | |
| `green.800` | `#124a28` | |
| `green.900` | `#042713` | |
| `green.950` | `#03190c` | |
| `teal.50` | `#f0fdfa` | |
| `teal.100` | `#ccfbf1` | |
| `teal.200` | `#99f6e4` | |
| `teal.300` | `#5eead4` | |
| `teal.400` | `#2dd4bf` | |
| `teal.500` | `#14b8a6` | |
| `teal.600` | `#0d9488` | |
| `teal.700` | `#0c5d56` | |
| `teal.800` | `#114240` | |
| `teal.900` | `#032726` | |
| `teal.950` | `#021716` | |
| `blue.50` | `#eff6ff` | |
| `blue.100` | `#dbeafe` | |
| `blue.200` | `#bfdbfe` | |
| `blue.300` | `#a3cfff` | |
| `blue.400` | `#60a5fa` | |
| `blue.500` | `#3b82f6` | |
| `blue.600` | `#2563eb` | |
| `blue.700` | `#173da6` | |
| `blue.800` | `#1a3478` | |
| `blue.900` | `#14204a` | |
| `blue.950` | `#0c142e` | |
| `cyan.50` | `#ecfeff` | |
| `cyan.100` | `#cffafe` | |
| `cyan.200` | `#a5f3fc` | |
| `cyan.300` | `#67e8f9` | |
| `cyan.400` | `#22d3ee` | |
| `cyan.500` | `#06b6d4` | |
| `cyan.600` | `#0891b2` | |
| `cyan.700` | `#0c5c72` | |
| `cyan.800` | `#134152` | |
| `cyan.900` | `#072a38` | |
| `cyan.950` | `#051b24` | |
| `purple.50` | `#faf5ff` | |
| `purple.100` | `#f3e8ff` | |
| `purple.200` | `#e9d5ff` | |
| `purple.300` | `#d8b4fe` | |
| `purple.400` | `#c084fc` | |
| `purple.500` | `#a855f7` | |
| `purple.600` | `#9333ea` | |
| `purple.700` | `#641ba3` | |
| `purple.800` | `#4a1772` | |
| `purple.900` | `#2f0553` | |
| `purple.950` | `#1a032e` | |
| `pink.50` | `#fdf2f8` | |
| `pink.100` | `#fce7f3` | |
| `pink.200` | `#fbcfe8` | |
| `pink.300` | `#f9a8d4` | |
| `pink.400` | `#f472b6` | |
| `pink.500` | `#ec4899` | |
| `pink.600` | `#db2777` | |
| `pink.700` | `#a41752` | |
| `pink.800` | `#6d0e34` | |
| `pink.900` | `#45061f` | |
| `pink.950` | `#2c0514` | |
## Semantic Tokens
Chakra UI supports these semantic tokens out of the box.
:::info
In most cases, we recommend using semantic tokens.
:::
### Background
| Background Token | Example |
| ---------------- | -------------------------- |
| `bg` | |
| `bg.subtle` | |
| `bg.muted` | |
| `bg.emphasized` | |
| `bg.inverted` | |
| `bg.panel` | |
| `bg.error` | |
| `bg.warning` | |
| `bg.success` | |
| `bg.info` | |
### Text
| Text Token | Example |
| ------------- | --------------------------- |
| `fg` | |
| `fg.muted` | |
| `fg.subtle` | |
| `fg.inverted` | |
| `fg.error` | |
| `fg.warning` | |
| `fg.success` | |
| `fg.info` | |
### Border
| Border Token | Example |
| ------------------- | --------------------------------------- |
| `border` | |
| `border.muted` | |
| `border.subtle` | |
| `border.emphasized` | |
| `border.inverted` | |
| `border.error` | |
| `border.warning` | |
| `border.success` | |
| `border.info` | |
# Cursors
## Overview
Chakra UI uses the `cursor` token to define the cursor for interactive elements.
| Cursor Token | Value | Example |
| ------------ | ------------- | ------------------------- |
| `button` | `pointer` | |
| `checkbox` | `default` | |
| `disabled` | `not-allowed` | |
| `menuitem` | `default` | |
| `option` | `default` | |
| `radio` | `default` | |
| `slider` | `default` | |
| `switch` | `pointer` | |
## Cursor Tokens
To customize the cursor for interactive elements in Chakra, set the desired
`cursor` token values.
Here's a list of the available cursor tokens:
- **button**: Cursors for buttons
- **checkbox**: Cursors for checkbox and checkbox card
- **disabled**: Cursors for disabled elements
- **menuitem**: Cursors for menu item and menu option items.
- **option**: Cursors for select, combobox and listbox options
- **radio**: Cursors for radio and radio cards
- **slider**: Cursors for slider track and thumb interaction
- **switch**: Cursors for switch
## Customizing Cursors
Here's an example of how to change the cursor for a button, you can set the
`button` token to `default`.
```tsx
import { createSystem, defaultConfig } from "@chakra-ui/react"
export const system = createSystem(defaultConfig, {
theme: {
tokens: {
cursor: {
button: { value: "pointer" },
},
},
},
})
```
# Slot Recipes
Chakra UI provides these text styles out of the box.
# Overview
## Architecture
The Chakra UI theming system is built around the API of
[Panda CSS](https://panda-css.com/).
Here's a quick overview of how the system is structured to provide a performant
and extensible styling system:
- Define the styling system configuration using the `defineConfig` function
- Create the styling engine using the `createSystem` function
- Pass the styling engine to the `ChakraProvider` component
```tsx
import { ChakraProvider, createSystem, defineConfig } from "@chakra-ui/react"
const config = defineConfig({
theme: {
tokens: {
colors: {},
},
},
})
const system = createSystem(config)
export default function App() {
return (
Hello World
)
}
```
## Config
The Chakra UI system is configured using the `defineConfig` function. This
function accepts a configuration object that allows you to customize the styling
system's behavior.
After a config is defined, it is passed to the `createSystem` function to create
the styling engine.
### cssVarsRoot
`cssVarsRoot` is the root element where the token CSS variables will be applied.
```tsx title="theme.ts"
const config = defineConfig({
cssVarsRoot: ":where(:root, :host)",
})
export default createSystem(config)
```
### cssVarsPrefix
`cssVarsPrefix` is the prefix used for the token CSS variables.
```tsx title="theme.ts"
const config = defineConfig({
cssVarsPrefix: "ck",
})
export default createSystem(config)
```
### globalCss
`globalCss` is used to apply global styles to the system.
```tsx title="theme.ts"
const config = defineConfig({
globalCss: {
"html, body": {
margin: 0,
padding: 0,
},
},
})
export default createSystem(config)
```
### theme
Use the `theme` config property to define the system theme. This property
accepts the following properties:
- `breakpoints`: for defining breakpoints
- `keyframes`: for defining css keyframes animations
- `tokens`: for defining tokens
- `semanticTokens`: for defining semantic tokens
- `textStyles`: for defining typography styles
- `layerStyles`: for defining layer styles
- `animationStyles`: for defining animation styles
- `recipes`: for defining component recipes
- `slotRecipes`: for defining component slot recipes
```tsx title="theme.ts"
const config = defineConfig({
theme: {
breakpoints: {
sm: "320px",
md: "768px",
lg: "960px",
xl: "1200px",
},
tokens: {
colors: {
red: "#EE0F0F",
},
},
semanticTokens: {
colors: {
danger: { value: "{colors.red}" },
},
},
keyframes: {
spin: {
from: { transform: "rotate(0deg)" },
to: { transform: "rotate(360deg)" },
},
},
},
})
export default createSystem(config)
```
### conditions
Use the `conditions` config property to define custom selectors and media query
conditions for use in the system.
```tsx title="theme.ts"
const config = defineConfig({
conditions: {
cqSm: "@container(min-width: 320px)",
child: "& > *",
},
})
export default createSystem(config)
```
Sample usage:
```tsx
Hello World
```
### strictTokens
Use the `strictTokens` config property to enforce the usage of only design
tokens. This will throw a TS error if you try to use a token that is not defined
in the theme.
```tsx title="theme.ts"
const config = defineConfig({
strictTokens: true,
})
export default createSystem(config)
```
```tsx
// ❌ This will throw a TS error
Hello World
// ✅ This will work
Hello World
```
## TypeScript
When you configure the system properties (like `colors`, `space`, `fonts`,
etc.), the CLI can be used to generate type definitions for them.
```bash
npx @chakra-ui/cli typegen ./theme.ts
```
This will update the internal types in the `@chakra-ui/react` package, and make
sure they are in sync with the theme. Providing a type-safe API and delightful
experience for developers.
## System
After a config is defined, it is passed to the `createSystem` function to create
the styling engine. The returned `system` is framework-agnostic JavaScript
styling engine that can be used to style components.
```tsx
const system = createSystem(config)
```
The system includes the following properties:
### token
The token function is used to get a raw token value, or css variable.
```tsx
const system = createSystem(config)
// raw token
system.token("colors.red.200")
// => "#EE0F0F"
// token with fallback
system.token("colors.pink.240", "#000")
// => "#000"
```
Use the `token.var` function to get the css variable:
```tsx
// css variable
system.token.var("colors.red.200")
// => "var(--chakra-colors-red-200)"
// token with fallback
system.token.var("colors.pink.240", "colors.red.200")
// => "var(--chakra-colors-red-200)"
```
It's important to note that `semanticTokens` always return a css variable,
regardless of whether you use `token` or `token.var`. This is because semantic
tokens change based on the theme.
```tsx
// semantic token
system.token("colors.danger")
// => "var(--chakra-colors-danger)"
system.token.var("colors.danger")
// => "var(--chakra-colors-danger)"
```
### tokens
```tsx
const system = createSystem(config)
system.tokens.getVar("colors.red.200")
// => "var(--chakra-colors-red-200)"
system.tokens.expandReferenceInValue("3px solid {colors.red.200}")
// => "3px solid var(--chakra-colors-red-200)"
system.tokens.cssVarMap
// => Map { "colors": Map { "red.200": "var(--chakra-colors-red-200)" } }
system.tokens.flatMap
// => Map { "colors.red.200": "var(--chakra-colors-red-200)" }
```
### css
The `css` function is used to convert chakra style objects to CSS style object
that can be passed to `emotion` or `styled-components` or any other styling
library.
```tsx
const system = createSystem(config)
system.css({
color: "red.200",
bg: "blue.200",
})
// => { color: "var(--chakra-colors-red-200)", background: "var(--chakra-colors-blue-200)" }
```
### cva
The `cva` function is used to create component recipes. It returns a function
that, when called with a set of props, returns a style object.
```tsx
const system = createSystem(config)
const button = system.cva({
base: {
color: "white",
bg: "blue.500",
},
variants: {
outline: {
color: "blue.500",
bg: "transparent",
border: "1px solid",
},
},
})
button({ variant: "outline" })
// => { color: "blue.500", bg: "transparent", border: "1px solid" }
```
### sva
The `sva` function is used to create component slot recipes. It returns a
function that, when called with a set of props, returns a style object for each
slot.
```tsx
const system = createSystem(config)
const alert = system.sva({
slots: ["title", "description", "icon"],
base: {
title: { color: "white" },
description: { color: "white" },
icon: { color: "white" },
},
variants: {
status: {
info: {
title: { color: "blue.500" },
description: { color: "blue.500" },
icon: { color: "blue.500" },
},
},
},
})
alert({ status: "info" })
// => { title: { color: "blue.500" }, description: { color: "blue.500" }, icon: { color: "blue.500" } }
```
### isValidProperty
The `isValidProperty` function is used to check if a property is valid.
```tsx
const system = createSystem(config)
system.isValidProperty("color")
// => true
system.isValidProperty("background")
// => true
system.isValidProperty("invalid")
// => false
```
### splitCssProps
The `splitCssProps` function is used to split the props into css props and
non-css props.
```tsx
const system = createSystem(config)
system.splitCssProps({
color: "red.200",
bg: "blue.200",
"aria-label": "Hello World",
})
// => [{ color: "red.200", bg: "blue.200" }, { "aria-label": "Hello World" }]
```
### breakpoints
The `breakpoints` property is used to query breakpoints.
```tsx
const system = createSystem(config)
system.breakpoints.up("sm")
// => "@media (min-width: 320px)"
system.breakpoints.down("sm")
// => "@media (max-width: 319px)"
system.breakpoints.only("md")
// => "@media (min-width: 320px) and (max-width: 768px)"
system.breakpoints.keys()
// => ["sm", "md", "lg", "xl"]
```
## Tokens
To learn more about tokens, please refer to the [tokens](/docs/theming/tokens)
section.
## Recipes
To learn more about recipes, please refer to the
[recipes](/docs/theming/recipes) section.
# Radii
## Tokens
Chakra UI supports the following border radius tokens out of the box.
| Border Radius Token | Value | Example |
| ------------------- | ------------ | --------------------------- |
| `none` | `0` | |
| `2xs` | `0.0625rem` | |
| `xs` | `0.125rem` | |
| `sm` | `0.25rem` | |
| `md` | `0.375rem` | |
| `lg` | `0.5rem` | |
| `xl` | `0.75rem` | |
| `2xl` | `1rem` | |
| `3xl` | `1.5rem` | |
| `4xl` | `2rem` | |
| `full` | `9999px` | |
| `l1` | `{radii.xs}` | |
| `l2` | `{radii.sm}` | |
| `l3` | `{radii.md}` | |
Here’s the conversion of the given rem values to px, assuming the root font size is 16px (which is the default in most browsers)
| Size | rem Value | px Equivalent |
|-------|-----------|---------------|
| none | 0 | 0px |
| 2xs | 0.0625rem | 1px |
| xs | 0.125rem | 2px |
| sm | 0.25rem | 4px |
| md | 0.375rem | 6px |
| lg | 0.5rem | 8px |
| xl | 0.75rem | 12px |
| 2xl | 1rem | 16px |
| 3xl | 1.5rem | 24px |
| 4xl | 2rem | 32px |
| full | 9999px | 9999px |
# Recipes
## Overview
Chakra provides a way to write CSS-in-JS with better performance, developer
experience, and composability. One of its key features is the ability to create
multi-variant styles with a type-safe runtime API.
A recipe consists of these properties:
- `className`: The className to attach to the component
- `base`: The base styles for the component
- `variants`: The different visual styles for the component
- `compoundVariants`: The different combinations of variants for the component
- `defaultVariants`: The default variant values for the component
## Defining the recipe
Use the `defineRecipe` identity function to create a recipe.
```tsx title="button.recipe.ts"
import { defineRecipe } from "@chakra-ui/react"
export const buttonRecipe = defineRecipe({
base: {
display: "flex",
},
variants: {
visual: {
solid: { bg: "red.200", color: "white" },
outline: { borderWidth: "1px", borderColor: "red.200" },
},
size: {
sm: { padding: "4", fontSize: "12px" },
lg: { padding: "8", fontSize: "24px" },
},
},
})
```
## Using the recipe
There are two ways to use the recipe in a component:
- Directly in the component with `useRecipe`
- Creating a component (recommended) with the `chakra` factory
:::info
**RSC Tip:** Adding the `"use client"` directive is required since it relies on
react hooks like `useContext` and `useInsertionEffect` under the hood.
:::
### Directly in component
Use the `useRecipe` hook to get the recipe for a component. Then, call the
recipe with its variant props to get the styles.
```tsx title="button.tsx" {9}
"use client"
import { chakra, useRecipe } from "@chakra-ui/react"
import { buttonRecipe } from "./button.recipe"
export const Button = (props) => {
const { visual, size, ...restProps } = props
const recipe = useRecipe({ recipe: buttonRecipe })
const styles = recipe({ visual, size })
return
}
```
#### splitVariantProps
Notice how the `visual` and `size` props were destructured from the props to be
passed to the recipe. A smarter approach would be to automatically split the
recipe props from the component props.
To do that, use the `recipe.splitVariantProps` function to split the recipe
props from the component props.
```tsx title="button.tsx" {8}
"use client"
import { chakra, useRecipe } from "@chakra-ui/react"
import { buttonRecipe } from "./button.recipe"
export const Button = (props) => {
const recipe = useRecipe({ recipe: buttonRecipe })
const [recipeProps, restProps] = recipe.splitVariantProps(props)
const styles = recipe(recipeProps)
// ...
}
```
#### TypeScript
To infer the recipe variant prop types, use the `RecipeVariantProps` type
helper.
```tsx title="button.tsx"
import type { RecipeVariantProps } from "@chakra-ui/react"
import { buttonRecipe } from "./button.recipe"
type ButtonVariantProps = RecipeVariantProps
export interface ButtonProps
extends React.PropsWithChildren {}
```
### Creating a component
Use the `chakra` function to create a component from a recipe.
> **Note:** The recipe can also be inlined into the `chakra` function.
```tsx title="button.tsx"
"use client"
import { chakra } from "@chakra-ui/react"
import { buttonRecipe } from "./button.recipe"
export const Button = chakra("button", buttonRecipe)
```
Next, use the component and pass recipe properties to it.
```tsx title="app.tsx"
import { Button } from "./button"
const App = () => {
return (
)
}
```
## Default Variants
The `defaultVariants` property is used to set the default variant values for the
recipe. This is useful when you want to apply a variant by default.
```tsx title="button.tsx" {19-22}
"use client"
import { chakra } from "@chakra-ui/react"
const Button = chakra("button", {
base: {
display: "flex",
},
variants: {
visual: {
solid: { bg: "red.200", color: "white" },
outline: { borderWidth: "1px", borderColor: "red.200" },
},
size: {
sm: { padding: "4", fontSize: "12px" },
lg: { padding: "8", fontSize: "24px" },
},
},
defaultVariants: {
visual: "solid",
size: "lg",
},
})
```
## Compound Variants
Use the `compoundVariants` property to define a set of variants that are applied
based on a combination of other variants.
```tsx title="button.tsx" /compoundVariants/
"use client"
import { chakra } from "@chakra-ui/react"
const button = cva({
base: {
display: "flex",
},
variants: {
visual: {
solid: { bg: "red.200", color: "white" },
outline: { borderWidth: "1px", borderColor: "red.200" },
},
size: {
sm: { padding: "4", fontSize: "12px" },
lg: { padding: "8", fontSize: "24px" },
},
},
compoundVariants: [
{
size: "small",
visual: "outline",
css: {
borderWidth: "2px",
},
},
],
})
```
When you use the `size="small"` and `visual="outline"` variants together, the
`compoundVariants` will apply the `css` property to the component.
```tsx title="app.tsx"
```
### Caveat
Due to the design constraints, using `compoundVariants` with responsive values
doesn't work.
This means a code like this will not work:
```tsx
```
For this cases, we recommend rendering multiple versions of the component with
different breakpoints, then hide/show as needed.
## Theme Usage
To use the recipe in a reusable manner, move it to the system theme and add it
to `theme.recipes` property.
```tsx title="theme.ts"
import { createSystem, defineConfig } from "@chakra-ui/react"
import { buttonRecipe } from "./button.recipe"
const config = defineConfig({
theme: {
recipes: {
button: buttonRecipe,
},
},
})
export default createSystem(config)
```
### TypeScript
Use the CLI to generate the types for the recipe.
```bash
npx @chakra-ui/cli typegen ./theme.ts
```
Then, import the generated types in your component.
```tsx title="button.tsx"
import type { RecipeVariantProps } from "@chakra-ui/react"
import { buttonRecipe } from "./button.recipe"
type ButtonVariantProps = RecipeVariantProps
export interface ButtonProps
extends React.PropsWithChildren {}
```
### Update code
If you use the recipe directly in your component, update the `useRecipe` to use
the `key` property to get the recipe from the theme.
```diff title="button.tsx"
const Button = () => {
- const recipe = useRecipe({ recipe: buttonRecipe })
+ const recipe = useRecipe({ key: "button" })
// ...
}
```
# Semantic Tokens
## Overview
Semantic tokens are tokens that are designed to be used in a specific context. A
semantic token consists of the following properties:
- `value`: The value of the token or a reference to an existing token.
- `description`: An optional description of what the token can be used for.
## Defining Semantic Tokens
In most cases, the value of a semantic token references to an existing token.
> To reference a value in a semantic token, use the token reference `{}` syntax.
```js title="theme.ts"
import { createSystem, defineConfig } from "@chakra-ui/react"
const config = defineConfig({
theme: {
tokens: {
colors: {
red: { value: "#EE0F0F" },
},
},
semanticTokens: {
colors: {
danger: { value: "{colors.red}" },
},
},
},
})
export default createSystem(config)
```
## Using Semantic Tokens
After defining semantic tokens, we recommend using the Chakra CLI to generate
theme typings for your tokens.
```bash
npx @chakra-ui/cli typegen ./src/theme.ts
```
This will provide autocompletion for your tokens in your editor.
```tsx
Hello World
```
## Conditional Token
Semantic tokens can also be changed based on the conditions like light and dark
modes.
For example, if you want a color to change automatically based on light or dark
mode.
```js title="theme.ts"
import { createSystem, defineConfig } from "@chakra-ui/react"
const config = defineConfig({
theme: {
semanticTokens: {
colors: {
danger: {
value: { base: "{colors.red}", _dark: "{colors.darkred}" },
},
success: {
value: { base: "{colors.green}", _dark: "{colors.darkgreen}" },
},
},
},
},
})
export default createSystem(config)
```
:::info
The conditions used in semantic tokens must be an at-rule or parent selector
[condition](/docs/styling/conditional-styles#reference).
:::
## Semantic Token Nesting
Semantic tokens can be nested to create a hierarchy of tokens. This is useful
when you want to group tokens together.
:::info
Use the `DEFAULT` key to define the default value of a nested token.
:::
```js title="theme.ts"
import { createSystem, defineConfig } from "@chakra-ui/react"
const config = defineConfig({
theme: {
semanticTokens: {
colors: {
bg: {
DEFAULT: { value: "{colors.gray.100}" },
primary: { value: "{colors.teal.100}" },
secondary: { value: "{colors.gray.100}" },
},
},
},
},
})
export default createSystem(config)
```
This allows the use of the `bg` token in the following ways:
```tsx
Hello WorldHello World
```
# Shadows
## Semantic Tokens
Chakra UI supports these semantic tokens out of the box.
| Shadow Token | Example |
| ------------ | ---------------------- |
| `xs` | |
| `sm` | |
| `md` | |
| `lg` | |
| `xl` | |
| `2xl` | |
| `inner` | |
| `inset` | |
Here’s an example of how to add new shadows.
```javascript
export const system = createSystem(defaultConfig, {
theme: {
semanticTokens: {
shadows: {
custom: {
value: {
_light: "0 32px 56px 0 rgba(0, 0, 0, 0.25)",
_dark: "0 32px 56px 0 rgba(0, 0, 0, 0.25)",
},
},
},
},
},
});
```
# Sizes
## Tokens
Chakra UI supports the following size tokens out of the box.
# Slot Recipes
## Overview
Slot Recipes come in handy when you need to apply style variations to multiple
parts of a component.
A slot recipe consists of these properties:
- `className`: The className prefix to attach to the component slot
- `slots`: An array of component parts to style
- `base`: The base styles per slot
- `variants`: The different visual styles for each slot
- `defaultVariants`: The default variant for the component
- `compoundVariants`: The compound variant combination and style overrides for
each slot.
## Defining the recipe
Use the `defineSlotRecipe` identity function to create a slot recipe.
```tsx title="checkbox.recipe.ts"
import { defineSlotRecipe } from "@chakra-ui/react"
export const checkboxSlotRecipe = defineSlotRecipe({
slots: ["root", "control", "label"],
base: {
root: { display: "flex", alignItems: "center", gap: "2" },
control: { borderWidth: "1px", borderRadius: "sm" },
label: { marginStart: "2" },
},
variants: {
size: {
sm: {
control: { width: "8", height: "8" },
label: { fontSize: "sm" },
},
md: {
control: { width: "10", height: "10" },
label: { fontSize: "md" },
},
},
},
})
```
## Using the recipe
There are two ways to use the recipe in a component:
- Directly in the component with `useSlotRecipe`
- As a compound component (recommended) with `createSlotRecipeContext`
:::info
Adding the `"use client"` directive is required to use the `useSlotRecipe` hook
or `createSlotRecipeContext` function. This is because they rely on react hooks
like `useContext` and `useInsertionEffect` under the hood.
:::
### Directly in component
Use the `useSlotRecipe` hook to get the recipe for a component. Then, call the
recipe with its variant props to get the styles.
```tsx title="checkbox.tsx"
"use client"
import { chakra, useSlotRecipe } from "@chakra-ui/react"
import { checkboxSlotRecipe } from "./checkbox.recipe"
export const Checkbox = (props) => {
const { size, ...restProps } = props
const recipe = useSlotRecipe({ recipe: checkboxSlotRecipe })
const styles = recipe({ size })
return (
Checkbox Label
)
}
```
#### splitVariantProps
Notice how the `size` prop was destructured from the props to be passed to the
recipe. A smarter approach would be to automatically split the recipe props from
the component props.
To do that, use the `recipe.splitVariantProps` function to split the recipe
props from the component props.
```tsx title="checkbox.tsx" {8}
"use client"
import { chakra, useSlotRecipe } from "@chakra-ui/react"
import { checkboxSlotRecipe } from "./checkbox.recipe"
export const Checkbox = (props) => {
const recipe = useSlotRecipe({ recipe: checkboxSlotRecipe })
const [recipeProps, restProps] = recipe.splitVariantProps(props)
const styles = recipe(recipeProps)
//...
}
```
#### TypeScript
To infer the recipe variant prop types, use the `RecipeVariantProps` type
helper.
```tsx title="checkbox.tsx"
import type { RecipeVariantProps } from "@chakra-ui/react"
import { checkboxSlotRecipe } from "./checkbox.recipe"
type CheckboxVariantProps = RecipeVariantProps
export interface CheckboxProps
extends React.PropsWithChildren {}
```
### Create compound components
Pass the recipe to the `createSlotRecipeContext` function to create a slot
recipe context.
Then, use the `withProvider` and `withContext` functions to create the compound
components that share the same context.
:::info
You will need to manually type the generics for `withProvider` and
`withContext`. This approach is designed to optimize TypeScript performance.
Auto-inference, while convenient, would slow down TypeScript compilation due to
the complexity of the types involved.
:::
```tsx title="checkbox.tsx"
"use client"
import { createSlotRecipeContext } from "@chakra-ui/react"
import { checkboxSlotRecipe } from "./checkbox.recipe"
const { withProvider, withContext } = createSlotRecipeContext({
recipe: checkboxSlotRecipe,
})
interface CheckboxRootProps
extends HTMLChakraProps<
"label",
RecipeVariantProps
> {}
export const CheckboxRoot = withProvider(
"label",
"root",
)
interface CheckboxControlProps extends HTMLChakraProps<"input"> {}
export const CheckboxControl = withContext<
HTMLInputElement,
CheckboxControlProps
>("input", "control")
interface CheckboxLabelProps extends HTMLChakraProps<"span"> {}
export const CheckboxLabel = withContext(
"span",
"label",
)
```
Pass the variant props to the "root" component that to apply the styles.
> **Note:** The root component is the one that used the `withProvider` function.
```tsx title="app.tsx"
const App = () => {
return (
)
}
```
#### unstyled prop
This approach supports the use of the `unstyled` prop to remove the styles
applied by the recipe.
```tsx title="checkbox.tsx" /unstyled/
```
#### TypeScript
To infer the recipe variant prop types, use the `RecipeVariantProps` type
helper.
```ts
import type { RecipeVariantProps, UnstyledProp } from "@chakra-ui/react"
import { checkboxSlotRecipe } from "./checkbox.recipe"
type CheckboxVariantProps = RecipeVariantProps
export interface CheckboxProps
extends React.PropsWithChildren,
UnstyledProp {}
```
## Compound Variants
Use the `compoundVariants` property to define a set of variants that are applied
based on a combination of other variants.
```tsx title="checkbox.recipe.ts" /compoundVariants/
import { defineSlotRecipe } from "@chakra-ui/react"
export const checkboxRecipe = defineSlotRecipe({
slots: ["root", "control", "label"],
base: {},
variants: {
size: {
sm: {},
md: {},
},
visual: {
contained: {},
outline: {},
},
},
compoundVariants: [
{
size: "sm",
visual: "outline",
css: {
control: { borderWidth: "1px" },
label: { color: "green.500" },
},
},
],
})
```
## Targeting a slot
In some cases, targeting a slot by className might be needed.
- Set the `className` property in the config
- The naming convention is `${className}__${slot}`
```tsx title="checkbox.recipe.ts" /& .checkbox__label/
import { defineSlotRecipe } from "@chakra-ui/react"
export const checkboxRecipe = defineSlotRecipe({
className: "checkbox",
slots: ["root", "control", "label"],
base: {
root: {
bg: "blue.500",
_hover: {
"& .checkbox__label": { color: "white" },
},
},
},
})
```
## Theme Usage
To use the recipe in a reusable manner, move it to the system theme and add it
to `theme.slotRecipes` property.
> No need to add the `"use client"` directive when using the recipe in the
> theme.
```tsx title="theme.ts"
import { createSystem, defineConfig } from "@chakra-ui/react"
import { checkboxSlotRecipe } from "./checkbox.recipe"
const config = defineConfig({
theme: {
slotRecipes: {
checkbox: checkboxSlotRecipe,
},
},
})
export default createSystem(config)
```
### TypeScript
Use the CLI to generate the types for the recipe.
```bash
npx @chakra-ui/cli typegen ./theme.ts
```
Then, import the generated types in your component.
```tsx title="checkbox.tsx"
import type { SlotRecipeProps, UnstyledProp } from "@chakra-ui/react"
export interface CheckboxProps
extends SlotRecipeProps<"checkbox">,
UnstyledProp {}
```
### Update code
If you use the recipe directly in your component, update the `useRecipe` to use
the `key` property to get the recipe from the theme.
```diff title="checkbox.tsx"
const Checkbox = () => {
- const recipe = useRecipe({ recipe: checkboxRecipe })
+ const recipe = useRecipe({ key: "checkbox" })
// ...
}
```
If you create a compound component, update the `createSlotRecipeContext` to use
the `key` property.
```diff title="checkbox.tsx"
const { withProvider, withContext } = createSlotRecipeContext({
- recipe: checkboxRecipe,
+ key: "checkbox",
})
```
# Spacing
## Tokens
Chakra UI supports the following spacing tokens out of the box.
| Spacing Token | Value | Example |
| ------------- | ---------- | --------------------- |
| `0.5` | `0.125rem` | |
| `1` | `0.25rem` | |
| `1.5` | `0.375rem` | |
| `2` | `0.5rem` | |
| `2.5` | `0.625rem` | |
| `3` | `0.75rem` | |
| `3.5` | `0.875rem` | |
| `4` | `1rem` | |
| `4.5` | `1.125rem` | |
| `5` | `1.25rem` | |
| `6` | `1.5rem` | |
| `7` | `1.75rem` | |
| `8` | `2rem` | |
| `9` | `2.25rem` | |
| `10` | `2.5rem` | |
| `11` | `2.75rem` | |
| `12` | `3rem` | |
| `14` | `3.5rem` | |
| `16` | `4rem` | |
| `20` | `5rem` | |
| `24` | `6rem` | |
| `28` | `7rem` | |
| `32` | `8rem` | |
| `36` | `9rem` | |
| `40` | `10rem` | |
| `44` | `11rem` | |
| `48` | `12rem` | |
| `52` | `13rem` | |
| `56` | `14rem` | |
| `60` | `15rem` | |
| `64` | `16rem` | |
| `72` | `18rem` | |
| `80` | `20rem` | |
| `96` | `24rem` | |
# Text Styles
Chakra UI provides these text styles out of the box.
# Tokens
## Overview
Design tokens are the platform-agnostic way to manage design decisions in your
application or website. It is a collection of attributes that describe any
fundamental/atomic visual style. Each attribute is a key-value pair.
> Design tokens in Chakra are largely influenced by the
> [W3C Token Format](https://tr.designtokens.org/format/).
A design token consists of the following properties:
- `value`: The value of the token. This can be any valid CSS value.
- `description`: An optional description of what the token can be used for.
## Defining Tokens
Tokens are defined in the under the `theme` key in your system config.
```ts title="theme.ts"
import { createSystem, defineConfig } from "@chakra-ui/react"
const config = defineConfig({
theme: {
tokens: {
colors: {
primary: { value: "#0FEE0F" },
secondary: { value: "#EE0F0F" },
},
fonts: {
body: { value: "system-ui, sans-serif" },
},
},
},
})
export const system = createSystem(config)
```
:::warning
> Token values need to be nested in an object with a `value` key. This is to
> allow for additional properties like `description` and more in the future.
:::
## Using Tokens
After defining tokens, we recommend using the Chakra CLI to generate theme
typings for your tokens.
```bash
npx @chakra-ui/cli typegen ./src/theme.ts
```
This will provide autocompletion for your tokens in your editor.
```tsx
Hello World
```
### Token reference syntax
Chakra UI enables you to reference design tokens within composite values for CSS
properties like `border`, `padding`, and `box-shadow`.
This is achieved through the token reference syntax: `{path.to.token}`.
:::note
It is important to use the complete token path; for example, instead of using
`red.300`, you must reference it as `colors.red.300`.
:::
Here’s an example where token reference syntax is applied to both the border and
p (padding) props:
```tsx
```
## Token Nesting
Tokens can be nested to create a hierarchy of tokens. This is useful when you
want to group related tokens together.
:::info
Use the `DEFAULT` key to define the default value of a nested token.
:::
```ts title="theme.ts"
import { defineConfig } from "@chakra-ui/react"
const config = defineConfig({
theme: {
tokens: {
colors: {
red: {
DEFAULT: { value: "#EE0F0F" },
100: { value: "#EE0F0F" },
},
},
},
},
})
export default createSystem(config)
```
```tsx
Hello World
```
## Token Types
### Colors
Colors have meaning and support the purpose of the content, communicating things
like hierarchy of information, and states. It is mostly defined as a string
value or reference to other tokens.
```tsx title="theme.ts"
import { defineTokens } from "@chakra-ui/react"
const tokens = defineTokens({
colors: {
red: {
100: { value: "#fff1f0" },
},
},
})
export default createSystem({
theme: { tokens },
})
```
### Gradients
Gradient tokens represent a smooth transition between two or more colors. Its
value can be defined as a string or a composite value.
```tsx title="theme.ts"
import { defineTokens } from "@chakra-ui/react"
const tokens = defineTokens({
gradients: {
// string value
simple: { value: "linear-gradient(to right, red, blue)" },
// composite value
primary: {
value: { type: "linear", placement: "to right", stops: ["red", "blue"] },
},
},
})
export default createSystem({
theme: { tokens },
})
```
### Sizes
Size tokens represent the width and height of an element. Its value is defined
as a string.
```tsx title="theme.ts"
import { defineTokens } from "@chakra-ui/react"
const tokens = defineTokens({
sizes: {
sm: { value: "12px" },
},
})
export default createSystem({
theme: { tokens },
})
```
> Size tokens are typically used in `width`, `height`, `minWidth`, `maxWidth`,
> `minHeight`, `maxHeight` properties.
### Spacing
Spacing tokens represent the margin and padding of an element. Its value is
defined as a string.
```tsx title="theme.ts"
import { defineTokens } from "@chakra-ui/react"
const tokens = defineTokens({
spacing: {
gutter: { value: "12px" },
},
})
export default createSystem({
theme: { tokens },
})
```
> Spacing tokens are typically used in `margin`, `padding`, `gap`, and
> `{top,right,bottom,left}` properties.
### Fonts
Font tokens represent the font family of a text element. Its value is defined as
a string or an array of strings.
```tsx title="theme.ts"
import { defineTokens } from "@chakra-ui/react"
const tokens = defineTokens({
fonts: {
body: { value: "Inter, sans-serif" },
heading: { value: ["Roboto Mono", "sans-serif"] },
},
})
export default createSystem({
theme: { tokens },
})
```
> Font tokens are typically used in `font-family` property.
### Font Sizes
Font size tokens represent the size of a text element. Its value is defined as a
string.
```tsx title="theme.ts"
import { defineTokens } from "@chakra-ui/react"
const tokens = defineTokens({
fontSizes: {
sm: { value: "12px" },
},
})
export default createSystem({
theme: { tokens },
})
```
> Font size tokens are typically used in `font-size` property.
### Font Weights
Font weight tokens represent the weight of a text element. Its value is defined
as a string.
```tsx title="theme.ts"
import { defineTokens } from "@chakra-ui/react"
const tokens = defineTokens({
fontWeights: {
bold: { value: "700" },
},
})
export default createSystem({
theme: { tokens },
})
```
> Font weight tokens are typically used in `font-weight` property.
### Letter Spacings
Letter spacing tokens represent the spacing between letters in a text element.
Its value is defined as a string.
```tsx
const tokens = defineTokens({
letterSpacings: {
wide: { value: "0.1em" },
},
})
export default createSystem({
theme: { tokens },
})
```
> Letter spacing tokens are typically used in `letter-spacing` property.
### Line Heights
Line height tokens represent the height of a line of text. Its value is defined
as a string.
```tsx title="theme.ts"
import { defineTokens } from "@chakra-ui/react"
const tokens = defineTokens({
lineHeights: {
normal: { value: "1.5" },
},
})
export default createSystem({
theme: { tokens },
})
```
> Line height tokens are typically used in `line-height` property.
### Radii
Radii tokens represent the radius of a border. Its value is defined as a string.
```tsx title="theme.ts"
import { defineTokens } from "@chakra-ui/react"
const tokens = defineTokens({
radii: {
sm: { value: "4px" },
},
})
export default createSystem({
theme: { tokens },
})
```
> Radii tokens are typically used in `border-radius` property.
### Borders
A border is a line surrounding a UI element. You can define them as string
values or as a composite value
```tsx title="theme.ts"
import { defineTokens } from "@chakra-ui/react"
const tokens = defineTokens({
borders: {
// string value
subtle: { value: "1px solid red" },
// string value with reference to color token
danger: { value: "1px solid {colors.red.400}" },
// composite value
accent: { value: { width: "1px", color: "red", style: "solid" } },
},
})
export default createSystem({
theme: { tokens },
})
```
> Border tokens are typically used in `border`, `border-top`, `border-right`,
> `border-bottom`, `border-left`, `outline` properties.
### Border Widths
Border width tokens represent the width of a border. Its value is defined as a
string.
```tsx title="theme.ts"
import { defineTokens } from "@chakra-ui/react"
const tokens = defineTokens({
borderWidths: {
thin: { value: "1px" },
thick: { value: "2px" },
medium: { value: "1.5px" },
},
})
export default createSystem({
theme: { tokens },
})
```
### Shadows
Shadow tokens represent the shadow of an element. Its value is defined as single
or multiple values containing a string or a composite value.
```tsx title="theme.ts"
import { defineTokens } from "@chakra-ui/react"
const tokens = defineTokens({
shadows: {
// string value
subtle: { value: "0 1px 2px 0 rgba(0, 0, 0, 0.05)" },
// composite value
accent: {
value: {
offsetX: 0,
offsetY: 4,
blur: 4,
spread: 0,
color: "rgba(0, 0, 0, 0.1)",
},
},
// multiple string values
realistic: {
value: [
"0 1px 2px 0 rgba(0, 0, 0, 0.05)",
"0 1px 4px 0 rgba(0, 0, 0, 0.1)",
],
},
},
})
export default createSystem({
theme: { tokens },
})
```
> Shadow tokens are typically used in `box-shadow` property.
### Easings
Easing tokens represent the easing function of an animation or transition. Its
value is defined as a string or an array of values representing the cubic
bezier.
```tsx title="theme.ts"
import { defineTokens } from "@chakra-ui/react"
const tokens = defineTokens({
easings: {
// string value
easeIn: { value: "cubic-bezier(0.4, 0, 0.2, 1)" },
// array value
easeOut: { value: [0.4, 0, 0.2, 1] },
},
})
export default createSystem({
theme: { tokens },
})
```
> Ease tokens are typically used in `transition-timing-function` property.
### Opacity
Opacity tokens help you set the opacity of an element.
```tsx title="theme.ts"
import { defineTokens } from "@chakra-ui/react"
const tokens = defineTokens({
opacity: {
50: { value: 0.5 },
},
})
export default createSystem({
theme: { tokens },
})
```
> Opacity tokens are typically used in `opacity` property.
### Z-Index
This token type represents the depth of an element's position on the z-axis.
```tsx title="theme.ts"
import { defineTokens } from "@chakra-ui/react"
const tokens = defineTokens({
zIndex: {
modal: { value: 1000 },
},
})
export default createSystem({
theme: { tokens },
})
```
> Z-index tokens are typically used in `z-index` property.
### Assets
Asset tokens represent a url or svg string. Its value is defined as a string or
a composite value.
```ts
type CompositeAsset = { type: "url" | "svg"; value: string }
type Asset = string | CompositeAsset
```
```tsx title="theme.ts"
import { defineTokens } from "@chakra-ui/react"
const tokens = defineTokens({
tokens: {
assets: {
logo: {
value: { type: "url", value: "/static/logo.png" },
},
checkmark: {
value: { type: "svg", value: "" },
},
},
},
})
export default createSystem({
theme: { tokens },
})
```
> Asset tokens are typically used in `background-image` property.
### Durations
Duration tokens represent the length of time in milliseconds an animation or
animation cycle takes to complete. Its value is defined as a string.
```tsx title="theme.ts"
import { defineTokens } from "@chakra-ui/react"
const tokens = defineTokens({
durations: {
fast: { value: "100ms" },
},
})
export default createSystem({
theme: { tokens },
})
```
> Duration tokens are typically used in `transition-duration` and
> `animation-duration` properties.
### Animations
Animation tokens represent a keyframe animation. Its value is defined as a
string value.
```tsx title="theme.ts"
import { defineTokens } from "@chakra-ui/react"
const tokens = defineTokens({
animations: {
spin: {
value: "spin 1s linear infinite",
},
},
})
export default createSystem({
theme: { tokens },
})
```
> Animation tokens are typically used in `animation` property.
### Aspect Ratios
Aspect ratio tokens represent the aspect ratio of an element. Its value is
defined as a string.
```tsx title="theme.ts"
import { defineTokens } from "@chakra-ui/react"
const tokens = defineTokens({
aspectRatios: {
"1:1": { value: "1 / 1" },
"16:9": { value: "16 / 9" },
},
})
export default createSystem({
theme: { tokens },
})
```
# Typography
## Fonts
Here's the list of available fonts.
| Font Token | Example |
| ---------- | ----------------------------- |
| `heading` | |
| `body` | |
| `mono` | |
## Font Sizes
Here's the list of available font sizes.
| Font Size Token | Value | Example |
| --------------- | ---------- | ----------------------- |
| `2xs` | `0.625rem` | |
| `xs` | `0.75rem` | |
| `sm` | `0.875rem` | |
| `md` | `1rem` | |
| `lg` | `1.125rem` | |
| `xl` | `1.25rem` | |
| `2xl` | `1.5rem` | |
| `3xl` | `1.875rem` | |
| `4xl` | `2.25rem` | |
| `5xl` | `3rem` | |
| `6xl` | `3.75rem` | |
| `7xl` | `4.5rem` | |
| `8xl` | `6rem` | |
| `9xl` | `8rem` | |
## Font Weights
Here's the list of available font weights.
| Font Weight Token | Value | Example |
| ----------------- | ----- | -------------------------------- |
| `thin` | `100` | |
| `extralight` | `200` | |
| `light` | `300` | |
| `normal` | `400` | |
| `medium` | `500` | |
| `semibold` | `600` | |
| `bold` | `700` | |
| `extrabold` | `800` | |
| `black` | `900` | |
## Line Heights
Here's the list of available line heights.
| Line Height Token | Value | Example |
| ----------------- | ------- | ------------------------------ |
| `shorter` | `1.25` | |
| `short` | `1.375` | |
| `moderate` | `1.5` | |
| `tall` | `1.625` | |
| `taller` | `2` | |
## Letter Spacings
Here's the list of available letter spacing.
| Letter Spacing Token | Value | Example |
| -------------------- | ---------- | -------------------------------- |
| `tighter` | `-0.05em` | |
| `tight` | `-0.025em` | |
| `wide` | `0.025em` | |
| `wider` | `0.05em` | |
| `widest` | `0.1em` | |
# Z-Index
## Tokens
Chakra UI supports the following z-index tokens out of the box.
| Z Index Token | Value | Example |
| ------------- | ------------ | ------------------------- |
| `hide` | `-1` | |
| `base` | `0` | |
| `docked` | `10` | |
| `dropdown` | `1000` | |
| `sticky` | `1100` | |
| `banner` | `1200` | |
| `overlay` | `1300` | |
| `modal` | `1400` | |
| `popover` | `1500` | |
| `skipNav` | `1600` | |
| `toast` | `1700` | |
| `tooltip` | `1800` | |
| `max` | `2147483647` | |
# Animations
:::info
Please read the [overview](/docs/theming/customization/overview) first to learn
how to properly customize the styling engine, and get type safety.
:::
## Keyframes
Keyframes are used to define the animation sequence. Here's how to define custom
keyframes:
```tsx title="theme.ts"
import { createSystem, defaultConfig, defineConfig } from "@chakra-ui/react"
const config = defineConfig({
theme: {
keyframes: {
shakeX: {
"0%, 100%": { transform: "translateX(-100%)" },
"50%": { transform: "translateX(100%)" },
},
},
},
})
export const system = createSystem(defaultConfig, config)
```
## Animation Tokens
After defining keyframes, you can create animation tokens that reference them.
Animation tokens can include the keyframe name, duration, timing function, and
other animation properties.
```tsx title="theme.ts"
import { createSystem, defaultConfig, defineConfig } from "@chakra-ui/react"
const config = defineConfig({
theme: {
keyframes: {
// ... keyframes from above
},
tokens: {
animations: {
shakeX: { value: "shakeX 1s ease-in-out infinite" },
},
},
},
})
export const system = createSystem(defaultConfig, config)
```
## Usage
You can use the animation token directly in your component style props.
```tsx
```
or as individual animation properties
```tsx
```
# Breakpoints
:::info
Please read the [overview](/docs/theming/customization/overview) first to learn
how to properly customize the styling engine, and get type safety.
:::
## Example
Here's an example of how to customize breakpoints in Chakra UI.
```tsx title="theme.ts"
import { createSystem, defaultConfig, defineConfig } from "@chakra-ui/react"
const config = defineConfig({
theme: {
breakpoints: {
tablet: "992px",
desktop: "1200px",
wide: "1400px",
},
},
})
export default createSystem(defaultConfig, config)
```
## Usage
When using responsive properties, reference the new breakpoints.
```tsx title="App.tsx"
Hello
```
# Colors
:::info
Please read the [overview](/docs/theming/customization/overview) first to learn
how to properly customize the styling engine, and get type safety.
:::
## Tokens
To create new colors, we recommend providing `50` - `950` color values. Here's
an example of how to customize colors in Chakra UI.
```tsx title="theme.ts"
import { createSystem, defaultConfig, defineConfig } from "@chakra-ui/react"
const customConfig = defineConfig({
theme: {
tokens: {
colors: {
brand: {
50: { value: "#e6f2ff" },
100: { value: "#e6f2ff" },
200: { value: "#bfdeff" },
300: { value: "#99caff" },
// ...
950: { value: "#001a33" },
},
},
},
},
})
export const system = createSystem(defaultConfig, customConfig)
```
To use the `brand` color, you can set the value of any color related properties,
like `bg`, `borderColor`, `color`, etc. to the `brand` token.
```tsx
```
## Semantic Tokens
### Color Palette
For new colors defined in the theme, we recommend creating these matching
semantic tokens to ensure consistency.
- `solid`: The bold fill color of the color.
- `contrast`: The text color that goes on solid color.
- `fg`: The foreground color used for text, icons, etc.
- `muted`: The muted color of the color.
- `subtle`: The subtle color of the color.
- `emphasized`: The emphasized version of the subtle color.
- `focusRing`: The focus ring color when interactive element is focused.
:::note
This is required if you intend to use the color in `colorPalette` property.
:::
```tsx title="theme.ts"
const customConfig = defineConfig({
theme: {
tokens: {
colors: {
brand: {
// ...
},
},
},
semanticTokens: {
colors: {
brand: {
solid: { value: "{colors.brand.500}" },
contrast: { value: "{colors.brand.100}" },
fg: { value: "{colors.brand.700}" },
muted: { value: "{colors.brand.100}" },
subtle: { value: "{colors.brand.200}" },
emphasized: { value: "{colors.brand.300}" },
focusRing: { value: "{colors.brand.500}" },
},
},
},
},
})
```
To use the color palette in components, you can use the `colorPalette` property.
```tsx
```
Alternative, you can also use the semantic token directly.
```tsx
Hello world
```
### Custom Tokens
Here's an example of how to create custom semantic tokens.
```tsx title="theme.ts"
import { createSystem, defaultConfig, defineConfig } from "@chakra-ui/react"
const customConfig = defineConfig({
theme: {
semanticTokens: {
colors: {
"checkbox-border": {
value: { _light: "gray.200", _dark: "gray.800" },
},
},
},
},
})
export const system = createSystem(defaultConfig, customConfig)
```
Then, you can apply the `checkbox-border` token to any component.
```tsx
```
# Conditions
:::info
Please read the [overview](/docs/theming/customization/overview) first to learn
how to properly customize the styling engine, and get type safety.
:::
## Example
Here's an example of how to customize conditions in Chakra UI.
```tsx title="theme.ts"
import { createSystem, defaultConfig, defineConfig } from "@chakra-ui/react"
const customConfig = defineConfig({
conditions: {
off: "&:is([data-state=off])",
on: "&:is([data-state=on])",
},
})
export const system = createSystem(defaultConfig, customConfig)
```
## Usage
Use `_off` and `_on` conditions to style elements based on the `data-state`
attribute.
```tsx title="app.tsx"
import { Box } from "@chakra-ui/react"
```
# CSS Variables
:::info
Please read the [overview](/docs/theming/customization/overview) first to learn
how to properly customize the styling engine, and get type safety.
:::
## Variable Root
Here's an example of how to customize the selector that token CSS variables are
applied to.
```tsx title="theme.ts"
import { createSystem, defaultConfig, defineConfig } from "@chakra-ui/react"
const customConfig = defineConfig({
cssVarsRoot: ":where(html)",
})
export const system = createSystem(defaultConfig, customConfig)
```
The emitted CSS variables will now be applied to the `html` element.
```css
:where(html) {
--chakra-colors-gray-100: #e6f2ff;
--chakra-colors-gray-200: #bfdeff;
--chakra-colors-gray-300: #99caff;
}
```
## Variable Prefix
Here's an example of how to customize the prefix of the emitted CSS variables.
```tsx title="theme.ts"
import { createSystem, defaultConfig, defineConfig } from "@chakra-ui/react"
const customConfig = defineConfig({
cssVarsPrefix: "sui",
})
export const system = createSystem(defaultConfig, customConfig)
```
The emitted CSS variables will now use the `sui` prefix.
```css
:where(html) {
--sui-colors-gray-100: #e6f2ff;
--sui-colors-gray-200: #bfdeff;
--sui-colors-gray-300: #99caff;
}
```
# Global CSS
:::info
Please read the [overview](/docs/theming/customization/overview) first to learn
how to properly customize the styling engine, and get type safety.
:::
## Example
Here's an example of how to customize the global CSS in Chakra UI.
```tsx title="theme.ts"
import { createSystem, defaultConfig, defineConfig } from "@chakra-ui/react"
const customConfig = defineConfig({
globalCss: {
"*::placeholder": {
opacity: 1,
color: "fg.subtle",
},
"*::selection": {
bg: "green.200",
},
},
})
export const system = createSystem(defaultConfig, customConfig)
```
After customizing the global CSS, make sure to update your provider component to
use the new system.
```tsx title="components/ui/provider.tsx" /value={system}/
"use client"
import { system } from "@/components/theme"
import {
ColorModeProvider,
type ColorModeProviderProps,
} from "@/components/ui/color-mode"
import { ChakraProvider } from "@chakra-ui/react"
export function Provider(props: ColorModeProviderProps) {
return (
)
}
```
# Customization
## Overview
Chakra UI uses a system of configs to define the default styling system.
- `defaultBaseConfig`: contains the conditions and style properties.
- `defaultConfig`: everything from `defaultBaseConfig` plus the built-in tokens
and recipes.
The `defaultSystem` exported from Chakra UI uses the `defaultConfig` by default.
When customizing the theme, it's important to decide if you want to merge your
config with `defaultConfig` or start from scratch with `defaultBaseConfig`.
## Customization
These are the key functions needed to customize the Chakra UI theme.
- `defineConfig`: used to define the system config
- `createSystem`: used to create a styling engine from the config
```tsx title="theme.ts"
import { createSystem, defaultBaseConfig, defineConfig } from "@chakra-ui/react"
const customConfig = defineConfig({
theme: {
colors: {
brand: {
500: "tomato",
},
},
},
})
export const system = createSystem(defaultBaseConfig, customConfig)
```
Next, update the `ChakraProvider` to use the custom system.
```tsx title="provider.tsx"
import { ChakraProvider } from "@chakra-ui/react"
import { ThemeProvider } from "next-themes"
import { system } from "./theme"
export function Provider(props: { children: React.ReactNode }) {
return (
{props.children}
)
}
```
## Complete Customization
In most cases, we recommend starting with the default configuration and only
specify the things you want to customize.
However, if you prefer to start from scratch, scaffold the default tokens and
recipes using the CLI.
```bash
npx @chakra-ui/cli eject --outdir ./theme
```
This will generate a file that includes all the tokens and recipes in Chakra.
## TypeScript
After customizing the default config, you may need to update the types.
```bash
npx @chakra-ui/cli typegen ./theme.ts
```
# Recipes
:::info
Please read the [overview](/docs/theming/customization/overview) first to learn
how to properly customize the styling engine, and get type safety.
:::
## Recipes
### Extending variants
Use the `defineRecipe` function to define a recipe override.
Here's an example of extending the `Button` to add a new `xl` size
```tsx title="theme.ts"
const buttonRecipe = defineRecipe({
variants: {
size: {
xl: {
fontSize: "lg",
px: 6,
py: 3,
},
},
},
})
const customConfig = defineConfig({
theme: {
recipes: {
button: buttonRecipe,
},
},
})
export const system = createSystem(defaultConfig, customConfig)
```
Then you can use the new size variant in your components.
```tsx
```
### Adding new variant
Use the `defineRecipe` function to define a new recipe variant.
Here's an example of defining a boolean variant called `raised`.
```tsx title="theme.ts"
const buttonRecipe = defineRecipe({
variants: {
raised: {
true: {
boxShadow: "md",
},
},
},
})
const customConfig = defineConfig({
theme: {
recipes: {
button: buttonRecipe,
},
},
})
export const system = createSystem(defaultConfig, customConfig)
```
Then you can use the new variant in your components.
```tsx
```
### Custom recipe
Use the `defineRecipe` function to define a custom recipe all together.
Here's an example of defining a custom recipe called `Title`
```tsx title="theme.ts"
const titleRecipe = defineRecipe({
baseStyle: {
fontWeight: "bold",
letterSpacing: "tight",
},
variants: {
size: {
md: { fontSize: "xl" },
lg: { fontSize: "2xl" },
},
},
})
const customConfig = defineConfig({
theme: {
recipes: {
title: titleRecipe,
},
},
})
export const system = createSystem(defaultConfig, customConfig)
```
Then, use the new recipe to create a components
```tsx
const Title = (props) => {
const recipe = useRecipe({ key: "title" })
const styles = recipe({ size: "lg" })
return
}
```
## Slot Recipes
To effectively override an existing slot recipe, we recommend connecting to its
anatomy. Slot recipes are added to the `theme.slotRecipes` object.
### Extending variants
Here's an example of how to extend the `Alert` slot recipe to create an `xl`
size.
```tsx title="theme.ts"
import { alertAnatomy } from "@chakra-ui/react/anatomy"
const alertSlotRecipe = defineSlotRecipe({
slots: alertAnatomy.keys(),
variants: {
size: {
xl: {
root: {
fontSize: "lg",
px: 6,
py: 3,
},
},
},
},
})
const customConfig = defineConfig({
theme: {
slotRecipes: {
alert: alertSlotRecipe,
},
},
})
export const system = createSystem(defaultConfig, customConfig)
```
Then you can use the new size variant in your components.
```tsx /size="xl"/
```
### Adding new variant
Here's an example of how to extend the `Alert` slot recipe to add a new variant
called `shape`.
```tsx title="theme.ts"
import { alertAnatomy } from "@chakra-ui/react/anatomy"
const alertSlotRecipe = defineSlotRecipe({
slots: alertAnatomy.keys(),
variants: {
shape: {
rounded: {
root: { borderRadius: "full" },
},
},
},
})
const customConfig = defineConfig({
theme: {
slotRecipes: {
alert: alertSlotRecipe,
},
},
})
export const system = createSystem(defaultConfig, customConfig)
```
Then you can use the new variant in your components.
```tsx /shape="rounded"/
```
### Custom recipe
Here's an example of how to define a custom slot recipe called `Navbar`.
```tsx title="theme.ts"
const navbarSlotRecipe = defineSlotRecipe({
slots: ["root", "badge", "icon"],
base: {
root: {
bg: "blue.500",
color: "white",
px: 4,
py: 2,
},
badge: {
borderRadius: "full",
px: 2,
py: 1,
},
},
})
const customConfig = defineConfig({
theme: {
slotRecipes: {
navbar: navbarSlotRecipe,
},
},
})
export const system = createSystem(defaultConfig, customConfig)
```
Then you can use the new recipe to create a components
```tsx
const Navbar = (props) => {
const recipe = useSlotRecipe({ key: "navbar" })
const styles = recipe()
return (
{props.children}
)
}
```
# Sizes
:::info
Please read the [overview](/docs/theming/customization/overview) first to learn
how to properly customize the styling engine, and get type safety.
:::
## Example
Here's an example of how to customize sizes in Chakra UI.
```tsx title="theme.ts"
import { createSystem, defaultConfig, defineConfig } from "@chakra-ui/react"
const customConfig = defineConfig({
theme: {
tokens: {
sizes: {
"1/7": { value: "14.285%" },
"2/7": { value: "28.571%" },
"3/7": { value: "42.857%" },
},
},
},
})
export const system = createSystem(defaultConfig, customConfig)
```
## Usage
Set the value of any size related properties, like `width`, `height`,
`minWidth`, `minHeight`, `maxWidth`, `maxHeight`, etc. to the `sizes` token.
```tsx
```
# Spacing
:::info
Please read the [overview](/docs/theming/customization/overview) first to learn
how to properly customize the styling engine, and get type safety.
:::
## Example
Here's an example of how to customize spacing in Chakra UI.
```tsx title="theme.ts"
import { createSystem, defaultConfig, defineConfig } from "@chakra-ui/react"
const customConfig = defineConfig({
theme: {
tokens: {
spacing: {
"128": { value: "32rem" },
"144": { value: "36rem" },
},
},
},
})
export const system = createSystem(defaultConfig, customConfig)
```
## Usage
Here's how to use the custom spacing in Chakra UI.
```tsx
```