([])
if (!editor) return null
return (
<>
setOpen(e.open)}>
Insert Image
{
const url = (
document.getElementById(
"image-url-input",
) as HTMLInputElement
).value
if (url) {
editor.chain().focus().setImage({ src: url }).run()
setOpen(false)
}
}}
>
Insert
{
const uploaded = accepted.files ?? []
setFiles(uploaded)
if (uploaded[0]) {
const url = URL.createObjectURL(uploaded[0])
editor.chain().focus().setImage({ src: url }).run()
setOpen(false)
}
}}
>
Drag and drop a file here
.png, .jpg up to 5MB
setOpen(false)}>
Cancel
)
}
function slugify(text: string) {
return text
.toLowerCase()
.trim()
.replace(/[^a-z0-9]+/g, "-") // replace non-alphanumeric with dash
.replace(/^-+|-+$/g, "") // remove leading/trailing dashes
}
const HeadingWithSlug = Heading.extend({
addAttributes() {
return {
...this.parent?.(),
id: {
default: null,
parseHTML: (element) => element.getAttribute("id"),
renderHTML: (attributes) => ({
id: attributes.id,
}),
},
}
},
addProseMirrorPlugins() {
return [
new Plugin({
appendTransaction: (_transactions, _oldState, newState) => {
const tr = newState.tr
let modified = false
newState.doc.descendants((node, pos) => {
if (node.type.name === "heading") {
const text = node.textContent
const slug = slugify(text)
if (node.attrs.id !== slug) {
tr.setNodeMarkup(pos, undefined, {
...node.attrs,
id: slug,
})
modified = true
}
}
})
return modified ? tr : null
},
}),
]
},
})
const editorContent = `
Legend Of X: The Complete Saga
In a world where technology and humanity collide, the fate of civilization hangs in the balance. This is the story of those who dared to question everything they knew.
Chapter 1: Awakening
The city of Neo-Tokyo stretched endlessly beneath the artificial sky. Maya Tanaka stood at the edge of the observation deck, watching the streams of data flow through the neural network that powered the megacity. She had always believed the System was infallible, that the Architects who built it had created a perfect world.
But something was wrong. The anomalies in the code were becoming more frequent, more deliberate. Someone—or something—was trying to break through.
Part 1: The First Glitch
It started with small things. A flicker in the holographic displays. A delay in the transportation grid. Messages that appeared and disappeared before anyone could read them. Maya had noticed these irregularities for weeks, but she was afraid to report them. In Neo-Tokyo, questioning the System was considered treason.
One evening, as she worked late in the Neural Operations Center, the main screen went black. Then, slowly, text began to appear: "They are watching. They have always been watching. Find the Archive before it's too late."
Part 2: The Underground
The next day, Maya received an encrypted message directing her to an abandoned sector of the city. She knew it was dangerous, but curiosity overwhelmed her caution. The meeting place was a decrepit building, its walls covered in graffiti that depicted symbols she didn't recognize.
Inside, she found a group of people huddled around old terminals. They called themselves the Disconnected—those who had rejected the neural implants that connected everyone to the System. Their leader, a man named Kenzo, explained that the glitches were intentional.
"We're trying to wake people up," he said. "The System isn't what you think it is. The Architects didn't save humanity—they enslaved it."
Chapter 2: The Archive
Maya's decision to join the Disconnected changed everything. Kenzo taught her how to navigate the hidden layers of the System, the forgotten protocols and backdoors that the Architects thought they had sealed. Together, they began their search for the Archive.
The journey took them through the darkest corners of Neo-Tokyo. They encountered other groups of rebels, each with their own theories about what the Archive contained. Some believed it held the key to shutting down the System entirely. Others thought it was a weapon that could be used to take control.
Part 3: Revelations
After months of searching, they found it. The Archive wasn't a physical location—it was a fragment of code hidden in the deepest layer of the System, protected by encryption so complex that even the Architects had lost access to it.
When Maya finally broke through the encryption, what she found shocked her. The Archive contained memories—thousands of them, uploaded from the minds of people who had lived before the Great Collapse. They revealed a truth that the Architects had hidden: the Collapse had been engineered.
The Architects had created the disaster that destroyed the old world so they could rebuild it in their image. And now, they were planning to do it again.
Chapter 3: Resistance
Armed with the truth, Maya and the Disconnected began spreading the Archive's contents throughout the city. The response was immediate. Some people refused to believe it, clinging to their faith in the System. Others joined the resistance, ready to fight for their freedom.
The Architects responded with force. Security drones filled the streets, hunting down anyone suspected of accessing the Archive. The city descended into chaos as the battle between the Disconnected and the System's defenders intensified.
Part 4: The Final Stand
Maya knew they couldn't win through violence alone. The System was too powerful, too entrenched. Instead, she devised a plan to use the Archive itself as a weapon. If they could upload its contents directly into the neural network, everyone connected to the System would see the truth simultaneously.
The operation was risky. It required infiltrating the Central Node, the heart of the System's infrastructure. Many of the Disconnected would have to sacrifice themselves to create a distraction. But it was their only chance.
As Maya stood before the Central Node's interface, her fingers trembling over the controls, she thought about all the lives that had been lost, all the lies that had been told. With one final command, she initiated the upload.
Epilogue: A New Beginning
The System didn't collapse overnight. But once people knew the truth, they began to question, to resist, to rebuild. Maya watched from a rooftop as the artificial sky flickered and went dark for the first time in decades, revealing the stars above.
The world would never be perfect. But it would be real. And that, she thought, was worth fighting for.
`
const menuItems = [
{
label: "File",
items: [
{ label: "New", icon:
```
### Customizing Content Padding
The editor uses CSS custom properties for content padding:
```tsx
```
### Custom Controls
The `RichTextEditor` provides three factory functions for creating custom
controls that integrate seamlessly with the editor: `createBooleanControl`,
`createSelectControl`, and `createSwatchControl`.
**Boolean Controls**
Boolean controls toggle editor states (bold, italic, etc.) and are the most
common control type:
```tsx
import { createBooleanControl } from "@/components/ui/rich-text-editor"
import { LuSparkles } from "react-icons/lu"
export const CustomHighlight = createBooleanControl({
label: "Highlight Important",
icon: LuSparkles,
command: (editor) => {
editor
.chain()
.focus()
.toggleMark("textStyle", {
backgroundColor: "#fef08a",
fontWeight: "bold"
})
.run()
},
getVariant: (editor) => {
const attrs = editor.getAttributes("textStyle")
return attrs.backgroundColor === "#fef08a" ? "subtle" : "ghost"
},
isDisabled: (editor) => !editor.can().toggleMark("textStyle")
})
// Use it in your toolbar
```
**Select Controls**
Select controls provide dropdown menus for choosing between multiple options:
```tsx
import { createSelectControl } from "@/components/ui/rich-text-editor"
export const LineHeight = createSelectControl({
label: "Line Height",
width: "100px",
placeholder: "Normal",
options: [
{ value: "normal", label: "Normal" },
{ value: "1.5", label: "1.5" },
{ value: "2", label: "Double" },
{ value: "2.5", label: "2.5" },
],
getValue: (editor) => {
return editor.getAttributes("textStyle")?.lineHeight || "normal"
},
command: (editor, value) => {
if (value === "normal") {
editor.chain().focus().unsetMark("textStyle").run()
} else {
editor.chain().focus().setMark("textStyle", { lineHeight: value }).run()
}
},
renderValue: (value, option) => {
return {option?.label || "Normal"}
},
})
```
**Swatch Controls**
Swatch controls provide color picker interfaces with predefined color swatches:
```tsx
import { createSwatchControl } from "@/components/ui/rich-text-editor"
import { LuPaintbrush } from "react-icons/lu"
export const BackgroundColor = createSwatchControl({
label: "Background Color",
icon: LuPaintbrush,
swatches: [
{ value: "#fef3c7", color: "#fef3c7", label: "Yellow" },
{ value: "#dbeafe", color: "#dbeafe", label: "Blue" },
{ value: "#dcfce7", color: "#dcfce7", label: "Green" },
{ value: "#fce7f3", color: "#fce7f3", label: "Pink" },
],
getValue: (editor) => {
return editor.getAttributes("textStyle")?.backgroundColor || ""
},
command: (editor, color) => {
editor
.chain()
.focus()
.setMark("textStyle", { backgroundColor: color })
.run()
},
getProps: (editor) => ({
variant: editor.getAttributes("textStyle")?.backgroundColor
? "subtle"
: "ghost",
}),
showRemove: true,
onRemove: (editor) => {
editor
.chain()
.focus()
.updateAttributes("textStyle", { backgroundColor: null })
.run()
},
})
```
# Scroll Area
```tsx
import { ScrollArea } from "@chakra-ui/react"
import LoremIpsum from "react-lorem-ipsum"
export const ScrollAreaBasic = () => (
)
```
## Usage
```tsx
import { ScrollArea } from "@chakra-ui/react"
```
```tsx
```
## Examples
### Variants
Use the `variant` prop to change the scrollbar visibility behavior. Values can
be either `hover` (default) or `always`.
```tsx
import { For, ScrollArea, Stack, Text } from "@chakra-ui/react"
import Lorem from "react-lorem-ipsum"
export const ScrollAreaWithVariants = () => (
{(variant) => (
variant="{variant}"
)}
)
```
### Sizes
Use the `size` prop to change the size of the scroll area. This affects the
scrollbar thickness and content padding.
```tsx
import { For, ScrollArea, Stack, Text } from "@chakra-ui/react"
import LoremIpsum from "react-lorem-ipsum"
export const ScrollAreaWithSizes = () => (
{(size) => (
size="{size}"
)}
)
```
### Horizontal Scrolling
The scroll area automatically supports horizontal scrolling when content
overflows horizontally.
```tsx
import { Flex, ScrollArea } from "@chakra-ui/react"
export const ScrollAreaHorizontal = () => (
{Array.from({ length: 12 }, (_, i) => (
Item {i + 1}
))}
)
```
### Both Directions
When content overflows in both directions, both scrollbars will appear.
```tsx
import { ScrollArea } from "@chakra-ui/react"
import LoremIpsum from "react-lorem-ipsum"
export const ScrollAreaBothDirections = () => (
)
```
:::info
You can render the `ScrollArea.Corner` component to show a corner indicator to
fill the intersection of the two scrollbars for a seamless, styled appearance.
:::
### Scroll Shadow
Add visual feedback when content is scrollable by implementing scroll shadows
that appear at the edges using `mask-image`.
Use the `data-overflow-y` attribute to only show shadows when content actually
overflows—this prevents shadows from appearing when there's a single item or no
scrollable content.
```tsx
import { ScrollArea } from "@chakra-ui/react"
export const ScrollAreaWithScrollShadow = () => {
return (
{Array.from({ length: 10 }, (_, i) => (
Item {i + 1}
))}
)
}
```
### Thumb Styling
Customize the appearance of the scrollbar thumb with different styles and
colors.
```tsx
import { ScrollArea } from "@chakra-ui/react"
import LoremIpsum from "react-lorem-ipsum"
export const ScrollAreaWithThumbStyling = () => (
)
```
### Stick to Bottom
Implement chat-like behavior where new content automatically scrolls to the
bottom, but allows manual scrolling.
> This example uses `use-stick-to-bottom` to scroll pinning.
```tsx
"use client"
import {
Box,
Button,
ButtonGroup,
IconButton,
ScrollArea,
VStack,
} from "@chakra-ui/react"
import { useState } from "react"
import { LuArrowDown } from "react-icons/lu"
import { useStickToBottom } from "use-stick-to-bottom"
export const ScrollAreaStickToBottom = () => {
const sticky = useStickToBottom()
const [messages, setMessages] = useState([
"Message 1 - 10:00:00",
"Message 2 - 10:00:01",
"Message 3 - 10:00:02",
"Message 4 - 10:00:03",
"Message 5 - 10:00:04",
"Message 6 - 10:00:05",
"Message 7 - 10:00:06",
"Message 8 - 10:00:07",
"Message 9 - 10:00:08",
"Message 10 - 10:00:09",
])
const addMessage = () => {
const newMessage = `Message ${messages.length + 1} - ${new Date().toLocaleTimeString()}`
setMessages((prev) => [...prev, newMessage])
}
const addMultipleMessages = () => {
const newMessages = Array.from(
{ length: 5 },
(_, i) =>
`Batch message ${messages.length + i + 1} - ${new Date().toLocaleTimeString()}`,
)
setMessages((prev) => [...prev, ...newMessages])
}
const removeMessage = () => {
setMessages((prev) => prev.slice(0, -1))
}
return (
Add Message
Add 5 Messages
Remove Message
{messages.map((message, index) => (
{message}
))}
{
sticky.scrollToBottom()
}}
colorScheme="blue"
variant="solid"
>
)}
)
}
```
### Virtualization
Handle large datasets efficiently by rendering only visible items using
`@tanstack/react-virtual`.
```tsx
"use client"
import { Box, ScrollArea } from "@chakra-ui/react"
import { type VirtualItem, useVirtualizer } from "@tanstack/react-virtual"
import React, { useCallback, useMemo, useRef } from "react"
export const ScrollAreaVirtualization = () => {
const scrollRef = useRef(null)
const items = useMemo(
() =>
Array.from({ length: 1000 }, (_, i) => ({
id: i,
name: `Item ${i + 1}`,
})),
[],
)
const virtualizer = useVirtualizer({
count: items.length,
getScrollElement: () => scrollRef.current,
estimateSize: () => 80,
overscan: 5,
})
const contentProps = useMemo(
(): React.ComponentProps<"div"> => ({
style: {
height: `${virtualizer.getTotalSize()}px`,
width: "100%",
position: "relative",
},
}),
[virtualizer],
)
const getItemProps = useCallback(
(item: VirtualItem): React.ComponentProps<"div"> => ({
style: {
position: "absolute",
top: 0,
left: 0,
width: "100%",
paddingBottom: 4,
height: `${item.size}px`,
transform: `translateY(${item.start}px)`,
},
}),
[],
)
return (
{virtualizer.getVirtualItems().map((virtualItem) => {
const item = items[virtualItem.index]
return (
{item.name}
)
})}
)
}
```
### Store
Use the scroll area with external state management and programmatic control.
```tsx
"use client"
import { ScrollArea, useScrollArea } from "@chakra-ui/react"
import LoremIpsum from "react-lorem-ipsum"
export const ScrollAreaWithStore = () => {
const scrollArea = useScrollArea()
return (
)
}
```
### Scroll to Side
Programmatically navigate through content by scrolling to different sides and
directions.
```tsx
"use client"
import {
Button,
ButtonGroup,
ScrollArea,
Stack,
useScrollArea,
} from "@chakra-ui/react"
import LoremIpsum from "react-lorem-ipsum"
export const ScrollAreaScrollToSide = () => {
const scrollArea = useScrollArea()
return (
scrollArea.scrollToEdge({ edge: "bottom", behavior: "smooth" })
}
>
Scroll to bottom
scrollArea.scrollToEdge({ edge: "top", behavior: "smooth" })
}
>
Scroll to top
)
}
```
### Scroll to Position
Jump to specific positions or items within the scrollable area with smooth
animations.
```tsx
"use client"
import { Button, ScrollArea, Stack, useScrollArea } from "@chakra-ui/react"
import LoremIpsum from "react-lorem-ipsum"
export const ScrollAreaScrollToPosition = () => {
const scrollArea = useScrollArea()
return (
scrollArea.scrollTo({ top: 200, behavior: "smooth" })}
>
Scroll to 100px
)
}
```
### RTL Support
The scroll area component fully supports Right-to-Left (RTL) languages like
Arabic and Hebrew.
```tsx
import { LocaleProvider, ScrollArea } from "@chakra-ui/react"
const arabicText = [
"مرحباً بكم في نظام التمرير المخصص",
"هذا مثال على النص العربي في منطقة التمرير",
"يدعم النظام اللغات التي تُكتب من اليمين إلى اليسار",
"التمرير الأفقي يعمل بشكل صحيح مع النصوص العربية",
"يمكنك رؤية كيف تتكيف أشرطة التمرير مع اتجاه النص",
"النظام يدعم التمرير العمودي والأفقي في نفس الوقت",
"يمكن تخصيص مظهر أشرطة التمرير حسب التصميم المطلوب",
"التفاعل مع أشرطة التمرير سهل ومريح للمستخدم",
"يعمل النظام بسلاسة على جميع المتصفحات الحديثة",
"يمكن دمج هذا المكون مع مكونات أخرى بسهولة",
"الأداء محسّن للتعامل مع كميات كبيرة من المحتوى",
]
export const ScrollAreaWithRtl = () => {
return (
{arabicText.map((text, i) => (
{text}
))}
)
}
```
### With Menu
Combine scroll area with other components like menus to handle overflowing
content. This example shows how to create a scrollable menu with many items.
```tsx
import { Button, Menu, Portal, ScrollArea } from "@chakra-ui/react"
import { useId } from "react"
export const ScrollAreaWithMenu = () => {
const contentId = useId()
return (
Open Menu with Scroll
{menuItems.map((item) => (
{item.label}
))}
)
}
function MenuContent(props: Menu.ContentProps) {
const { id, children, ...rest } = props
return (
{children}
)
}
const menuItems = [
{ value: "profile", label: "Profile" },
{ value: "settings", label: "Settings" },
{ value: "notifications", label: "Notifications" },
{ value: "messages", label: "Messages" },
{ value: "documents", label: "Documents" },
{ value: "files", label: "Files" },
{ value: "images", label: "Images" },
{ value: "videos", label: "Videos" },
{ value: "music", label: "Music" },
{ value: "downloads", label: "Downloads" },
{ value: "share", label: "Share" },
{ value: "copy", label: "Copy" },
{ value: "edit", label: "Edit" },
{ value: "favorites", label: "Favorites" },
{ value: "liked", label: "Liked Items" },
{ value: "bookmarks", label: "Bookmarks" },
{ value: "flagged", label: "Flagged Items" },
{ value: "help", label: "Help & Support" },
{ value: "trash", label: "Trash" },
{ value: "logout", label: "Logout" },
]
```
## Props
### Root
| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| colorPalette | gray | `'gray' \| 'red' \| 'orange' \| 'yellow' \| 'green' \| 'teal' \| 'blue' \| 'cyan' \| 'purple' \| 'pink'` | The color palette of the component |
| variant | hover | `'hover' \| 'always'` | The variant of the component |
| size | md | `'xs' \| 'sm' \| 'md' \| 'lg'` | The size of the component |
| as | undefined | `React.ElementType` | The underlying element to render. |
| asChild | undefined | `boolean` | Use the provided child element as the default rendered element, combining their props and behavior. |
| unstyled | undefined | `boolean` | Whether to remove the component's style. |
| ids | undefined | `Partial<{ root: string; viewport: string; content: string; scrollbar: string; thumb: string }>` | The ids of the scroll area elements |
### Viewport
| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| as | undefined | `React.ElementType` | The underlying element to render. |
| asChild | undefined | `boolean` | Use the provided child element as the default rendered element, combining their props and behavior. |
### Content
| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| as | undefined | `React.ElementType` | The underlying element to render. |
| asChild | undefined | `boolean` | Use the provided child element as the default rendered element, combining their props and behavior. |
### Scrollbar
| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| as | undefined | `React.ElementType` | The underlying element to render. |
| asChild | undefined | `boolean` | Use the provided child element as the default rendered element, combining their props and behavior. |
| orientation | undefined | `Orientation` | undefined |
### Thumb
| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| as | undefined | `React.ElementType` | The underlying element to render. |
| asChild | undefined | `boolean` | Use the provided child element as the default rendered element, combining their props and behavior. |
### Corner
| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| as | undefined | `React.ElementType` | The underlying element to render. |
| asChild | undefined | `boolean` | Use the provided child element as the default rendered element, combining their props and behavior. |
## Explorer
Explore the `Scroll Area` component parts interactively. Click on parts in the
sidebar to highlight them in the preview.
)
}
```
## Usage
```tsx
import { SegmentGroup } from "@chakra-ui/react"
```
```tsx
```
## Shortcuts
The `SegmentGroup` component also provides a set of shortcuts for common use
cases.
### SegmentGroupItems
The `SegmentGroupItems` shortcut renders a list of items based on the `items`
prop.
This works:
```tsx
<>
{items.map((item) => (
{item.label}
))}
```
This might be more concise, if you don't need to customize the items:
```tsx
{(size) => (
size = {size}
)}
)
}
```
### Controlled
Use the `value` and `onValueChange` props to control the selected item.
```tsx
"use client"
import { SegmentGroup } from "@chakra-ui/react"
import { useState } from "react"
export const SegmentedControlControlled = () => {
const [value, setValue] = useState("React")
return (
setValue(e.value)}>
)
}
```
### Hook Form
Here's an example of how to use the `SegmentedControl` with `react-hook-form`.
```tsx
"use client"
import { Button, Field, SegmentGroup, Stack } from "@chakra-ui/react"
import { standardSchemaResolver } from "@hookform/resolvers/standard-schema"
import { Controller, useForm } from "react-hook-form"
import { z } from "zod"
const formSchema = z.object({
fontSize: z.string({ message: "Font size is required" }),
})
type FormValues = z.infer
export const SegmentedControlWithHookForm = () => {
const {
handleSubmit,
formState: { errors },
control,
} = useForm({
defaultValues: { fontSize: "md" },
resolver: standardSchemaResolver(formSchema),
})
const onSubmit = handleSubmit((data) => console.log(data))
return (
)
}
```
### Vertical
By default, the segmented control is horizontal. Set the `orientation` prop to
`vertical` to change the orientation of the segmented control.
```tsx
import { SegmentGroup } from "@chakra-ui/react"
export const SegmentedControlVertical = () => {
return (
)
}
```
### Disabled
Use the `disabled` prop to disable the segmented control.
```tsx
import { SegmentGroup } from "@chakra-ui/react"
export const SegmentedControlWithDisabled = () => {
return (
)
}
```
### Disabled Item
Use the `disabled` prop on the item to disable it.
```tsx
import { SegmentGroup } from "@chakra-ui/react"
export const SegmentedControlWithDisabledItem = () => {
return (
)
}
```
### Custom Indicator
Customize the indicator appearance using CSS variables like
`--segment-indicator-bg` and `--segment-indicator-shadow`.
```tsx
import { SegmentGroup } from "@chakra-ui/react"
export const SegmentedControlWithCustomIndicator = () => {
return (
)
}
```
### Color Palette
By default, the segment control doesn't support changing the design via the
`colorPalette` prop. This example shows how to customize the segmented control
to make the `colorPalette` prop work.
```tsx
import { Center, For, SegmentGroup } from "@chakra-ui/react"
export const SegmentedControlWithColorPalette = () => {
return (
{(item) => (
{item}
)}
)
}
```
### Icon
Render the `label` as a `ReactNode` to render an icon.
```tsx
import { HStack, SegmentGroup } from "@chakra-ui/react"
import { LuGrid2X2, LuList, LuTable } from "react-icons/lu"
export const SegmentedControlWithIcon = () => {
return (
),
},
{
value: "list",
label: (
),
},
]}
/>
)
}
```
### Card
Here's an example of how to use the `SegmentedControl` within a `Card`.
```tsx
import { Button, Card, Field, Heading, SegmentGroup } from "@chakra-ui/react"
import { LuSearch } from "react-icons/lu"
export const SegmentedControlInCard = () => {
return (
Find your dream home
Bedrooms
Beds
Bathrooms
Reset
)
}
```
## Props
### Root
| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| orientation | horizontal | `'horizontal' \| 'vertical'` | Orientation of the radio group |
| size | md | `'xs' \| 'sm' \| 'md' \| 'lg'` | The size of the component |
| as | undefined | `React.ElementType` | The underlying element to render. |
| asChild | undefined | `boolean` | Use the provided child element as the default rendered element, combining their props and behavior. |
| unstyled | undefined | `boolean` | Whether to remove the component's style. |
| defaultValue | undefined | `string` | The initial value of the checked radio when rendered.
Use when you don't need to control the value of the radio group. |
| disabled | undefined | `boolean` | If `true`, the radio group will be disabled |
| form | undefined | `string` | The associate form of the underlying input. |
| id | undefined | `string` | The unique identifier of the machine. |
| ids | undefined | `Partial<{\n root: string\n label: string\n indicator: string\n item: (value: string) => string\n itemLabel: (value: string) => string\n itemControl: (value: string) => string\n itemHiddenInput: (value: string) => string\n}>` | The ids of the elements in the radio. Useful for composition. |
| invalid | undefined | `boolean` | If `true`, the radio group is marked as invalid. |
| name | undefined | `string` | The name of the input fields in the radio
(Useful for form submission). |
| onValueChange | undefined | `(details: ValueChangeDetails) => void` | Function called once a radio is checked |
| readOnly | undefined | `boolean` | Whether the radio group is read-only |
| required | undefined | `boolean` | If `true`, the radio group is marked as required. |
| value | undefined | `string` | The controlled value of the radio group |
# Select
```tsx
"use client"
import { Portal, Select, createListCollection } from "@chakra-ui/react"
export const SelectBasic = () => {
return (
Select framework
{frameworks.items.map((framework) => (
{framework.label}
))}
)
}
const frameworks = createListCollection({
items: [
{ label: "React.js", value: "react" },
{ label: "Vue.js", value: "vue" },
{ label: "Angular", value: "angular" },
{ label: "Svelte", value: "svelte" },
],
})
```
## Usage
```jsx
import { Select } from "@chakra-ui/react"
```
```jsx
```
To setup the select, use `useListCollection` to manage the
[list collection](https://ark-ui.com/docs/collections/list-collection).
## Examples
### Sizes
Use the `size` prop to change the size of the select component.
```tsx
"use client"
import {
For,
Portal,
Select,
Stack,
createListCollection,
} from "@chakra-ui/react"
export const SelectWithSizes = () => {
return (
{(size) => (
size = {size}
{frameworks.items.map((framework) => (
{framework.label}
))}
)}
)
}
const frameworks = createListCollection({
items: [
{ label: "React.js", value: "react" },
{ label: "Vue.js", value: "vue" },
{ label: "Angular", value: "angular" },
{ label: "Svelte", value: "svelte" },
],
})
```
### Variants
Use the `variant` prop to change the appearance of the select component.
```tsx
"use client"
import {
For,
Portal,
Select,
Stack,
createListCollection,
} from "@chakra-ui/react"
export const SelectWithVariants = () => {
return (
{(variant) => (
Select framework - {variant}
{frameworks.items.map((framework) => (
{framework.label}
))}
)}
)
}
const frameworks = createListCollection({
items: [
{ label: "React.js", value: "react" },
{ label: "Vue.js", value: "vue" },
{ label: "Angular", value: "angular" },
{ label: "Svelte", value: "svelte" },
],
})
```
### Color Palette
The Select component is designed to be neutral-colored by default for
consistency across form elements. To apply a color palette, style the trigger
and indicator components directly using the `colorPalette` token.
```tsx
"use client"
import { Portal, Select, createListCollection } from "@chakra-ui/react"
export const SelectWithColorPalette = () => {
return (
Select framework
{frameworks.items.map((framework) => (
{framework.label}
))}
)
}
const frameworks = createListCollection({
items: [
{ label: "React.js", value: "react" },
{ label: "Vue.js", value: "vue" },
{ label: "Angular", value: "angular" },
{ label: "Svelte", value: "svelte" },
],
})
```
### Option Group
Use the `Select.ItemGroup` component to group select options.
```tsx
"use client"
import { Portal, Select, createListCollection } from "@chakra-ui/react"
import { groupBy } from "es-toolkit"
export const SelectWithOptionGroup = () => {
return (
Select framework
{categories.map(([category, items]) => (
{category}
{items.map((item) => (
{item.label}
))}
))}
)
}
const collection = createListCollection({
items: [
{ label: "Naruto", value: "naruto", category: "Anime" },
{ label: "One Piece", value: "one-piece", category: "Anime" },
{ label: "Dragon Ball", value: "dragon-ball", category: "Anime" },
{
label: "The Shawshank Redemption",
value: "the-shawshank-redemption",
category: "Movies",
},
{ label: "The Godfather", value: "the-godfather", category: "Movies" },
{ label: "The Dark Knight", value: "the-dark-knight", category: "Movies" },
],
})
const categories = Object.entries(
groupBy(collection.items, (item) => item.category),
)
```
### Controlled
Use the `value` and `onValueChange` props to control the select component.
```tsx
"use client"
import { Portal, Select, createListCollection } from "@chakra-ui/react"
import { useState } from "react"
export const SelectControlled = () => {
const [value, setValue] = useState([])
return (
setValue(e.value)}
>
Select framework
{frameworks.items.map((framework) => (
{framework.label}
))}
)
}
const frameworks = createListCollection({
items: [
{ label: "React.js", value: "react" },
{ label: "Vue.js", value: "vue" },
{ label: "Angular", value: "angular" },
{ label: "Svelte", value: "svelte" },
],
})
```
### Async Loading
Here's an example of how to populate the select `collection` from a remote
source.
```tsx
"use client"
import { Portal, Select, Spinner, createListCollection } from "@chakra-ui/react"
import { useMemo } from "react"
import { useAsync } from "react-use"
interface Pokemon {
name: string
url: string
}
export const SelectAsyncLoading = () => {
const state = useAsync(async (): Promise => {
const response = await fetch("https://pokeapi.co/api/v2/pokemon")
const data = await response.json()
return data.results
}, [])
const collection = useMemo(() => {
return createListCollection({
items: state.value ?? [],
itemToString: (pokemon) => pokemon.name,
itemToValue: (pokemon) => pokemon.name,
})
}, [state.value])
return (
Select pokemon
{state.loading && (
{collection.items.map((pokemon) => (
{pokemon.name}
))}
)
}
```
### Hook Form
Here's an example of how to use the `Select` component with `react-hook-form`.
```tsx
"use client"
import {
Button,
Field,
Portal,
Select,
Stack,
createListCollection,
} from "@chakra-ui/react"
import { standardSchemaResolver } from "@hookform/resolvers/standard-schema"
import { Controller, useForm } from "react-hook-form"
import { z } from "zod"
const formSchema = z.object({
framework: z.string({ message: "Framework is required" }).array(),
})
type FormValues = z.infer
export const SelectWithHookForm = () => {
const {
handleSubmit,
formState: { errors },
control,
} = useForm({
resolver: standardSchemaResolver(formSchema),
})
const onSubmit = handleSubmit((data) => console.log(data))
return (
)
}
const frameworks = createListCollection({
items: [
{ label: "React.js", value: "react" },
{ label: "Vue.js", value: "vue" },
{ label: "Angular", value: "angular" },
{ label: "Svelte", value: "svelte" },
],
})
```
### Disabled
Use the `disabled` prop to disable the select component.
```tsx
"use client"
import { Portal, Select, createListCollection } from "@chakra-ui/react"
export const SelectWithDisabled = () => {
return (
Select framework
{frameworks.items.map((framework) => (
{framework.label}
))}
)
}
const frameworks = createListCollection({
items: [
{ label: "React.js", value: "react" },
{ label: "Vue.js", value: "vue" },
{ label: "Angular", value: "angular" },
{ label: "Svelte", value: "svelte" },
],
})
```
### Invalid
Here's an example of how to compose the `Select` component with the `Field`
component to display an error state.
```tsx
"use client"
import { Field, Portal, Select, createListCollection } from "@chakra-ui/react"
export const SelectWithInvalid = () => {
return (
Select framework
{frameworks.items.map((framework) => (
{framework.label}
))}
This is an error
)
}
const frameworks = createListCollection({
items: [
{ label: "React.js", value: "react" },
{ label: "Vue.js", value: "vue" },
{ label: "Angular", value: "angular" },
{ label: "Svelte", value: "svelte" },
],
})
```
### Multiple
Use the `multiple` prop to allow multiple selections.
```tsx
"use client"
import { Portal, Select, createListCollection } from "@chakra-ui/react"
export const SelectWithMultiple = () => {
return (
Select framework
{frameworks.items.map((framework) => (
{framework.label}
))}
)
}
const frameworks = createListCollection({
items: [
{ label: "React.js", value: "react" },
{ label: "Vue.js", value: "vue" },
{ label: "Angular", value: "angular" },
{ label: "Svelte", value: "svelte" },
],
})
```
### Positioning
Use the `positioning` prop to control the underlying `floating-ui` options of
the select component.
```tsx
"use client"
import { Portal, Select, createListCollection } from "@chakra-ui/react"
export const SelectWithPositioning = () => {
return (
Select framework
{frameworks.items.map((framework) => (
{framework.label}
))}
)
}
const frameworks = createListCollection({
items: [
{ label: "React.js", value: "react" },
{ label: "Vue.js", value: "vue" },
{ label: "Angular", value: "angular" },
{ label: "Svelte", value: "svelte" },
],
})
```
### Clear Trigger
Render the `Select.ClearTrigger` component to show a clear button. Clicking the
clear button will clear the selected value.
```tsx
"use client"
import { Portal, Select, createListCollection } from "@chakra-ui/react"
export const SelectWithClear = () => {
return (
Select fav. anime
{animeMovies.items.map((anime) => (
{anime.label}
))}
)
}
const animeMovies = createListCollection({
items: [
{ label: "Spirited Away", value: "spirited_away" },
{ label: "My Neighbor Totoro", value: "my_neighbor_totoro" },
{ label: "Akira", value: "akira" },
{ label: "Princess Mononoke", value: "princess_mononoke" },
{ label: "Grave of the Fireflies", value: "grave_of_the_fireflies" },
{ label: "Howl's Moving Castle", value: "howls_moving_castle" },
{ label: "Ghost in the Shell", value: "ghost_in_the_shell" },
{ label: "Naruto", value: "naruto" },
{ label: "Hunter x Hunter", value: "hunter_x_hunter" },
{ label: "The Wind Rises", value: "the_wind_rises" },
{ label: "Kiki's Delivery Service", value: "kikis_delivery_service" },
{ label: "Perfect Blue", value: "perfect_blue" },
{
label: "The Girl Who Leapt Through Time",
value: "the_girl_who_leapt_through_time",
},
{ label: "Weathering with You", value: "weathering_with_you" },
{ label: "Ponyo", value: "ponyo" },
{ label: "5 Centimeters per Second", value: "5_centimeters_per_second" },
{ label: "A Silent Voice", value: "a_silent_voice" },
{ label: "Paprika", value: "paprika" },
{ label: "Wolf Children", value: "wolf_children" },
{ label: "Redline", value: "redline" },
{
label: "The Tale of the Princess Kaguya",
value: "the_tale_of_the_princess_kaguya",
},
],
})
```
### Overflow
When the options are too many, the options will overflow the container due to
the `maxHeight` set.
```tsx
"use client"
import { Portal, Select, createListCollection } from "@chakra-ui/react"
export const SelectWithOverflow = () => {
return (
Select anime
{animeMovies.items.map((movie) => (
{movie.label}
))}
)
}
const animeMovies = createListCollection({
items: [
{ label: "Spirited Away", value: "spirited_away" },
{ label: "My Neighbor Totoro", value: "my_neighbor_totoro" },
{ label: "Akira", value: "akira" },
{ label: "Princess Mononoke", value: "princess_mononoke" },
{ label: "Grave of the Fireflies", value: "grave_of_the_fireflies" },
{ label: "Howl's Moving Castle", value: "howls_moving_castle" },
{ label: "Ghost in the Shell", value: "ghost_in_the_shell" },
{ label: "Naruto", value: "naruto" },
{ label: "Hunter x Hunter", value: "hunter_x_hunter" },
{ label: "The Wind Rises", value: "the_wind_rises" },
{ label: "Kiki's Delivery Service", value: "kikis_delivery_service" },
{ label: "Perfect Blue", value: "perfect_blue" },
{
label: "The Girl Who Leapt Through Time",
value: "the_girl_who_leapt_through_time",
},
{ label: "Weathering with You", value: "weathering_with_you" },
{ label: "Ponyo", value: "ponyo" },
{ label: "5 Centimeters per Second", value: "5_centimeters_per_second" },
{ label: "A Silent Voice", value: "a_silent_voice" },
{ label: "Paprika", value: "paprika" },
{ label: "Wolf Children", value: "wolf_children" },
{ label: "Redline", value: "redline" },
{
label: "The Tale of the Princess Kaguya",
value: "the_tale_of_the_princess_kaguya",
},
],
})
```
### Item Description
Here's an example of how to render a description for each item.
```tsx
"use client"
import {
Portal,
Select,
Span,
Stack,
createListCollection,
} from "@chakra-ui/react"
export const SelectWithItemDescription = () => {
return (
Select plan
{frameworks.items.map((framework) => (
{framework.label}
{framework.description}
))}
)
}
const frameworks = createListCollection({
items: [
{
label: "Basic Plan",
value: "basic",
description: "$9/month - Perfect for small projects",
},
{
label: "Pro Plan",
value: "pro",
description: "$29/month - Advanced features",
},
{
label: "Business Plan",
value: "business",
description: "$99/month - Enterprise-grade solutions",
},
{
label: "Enterprise Plan",
value: "enterprise",
description: "Custom pricing - Tailored solutions",
},
],
})
```
### Open From Popover
Here's an example of how to use the `Select` within a `Popover` component.
```tsx
"use client"
import {
Button,
Popover,
Portal,
Select,
createListCollection,
} from "@chakra-ui/react"
export const SelectOpenFromPopover = () => {
return (
Select in Popover
Select in Popover
{frameworks.items.map((item) => (
{item.label}
))}
)
}
const frameworks = createListCollection({
items: [
{ label: "React.js", value: "react" },
{ label: "Vue.js", value: "vue" },
{ label: "Angular", value: "angular" },
{ label: "Svelte", value: "svelte" },
],
})
```
### Open From Dialog
To use the `Select` within a `Dialog`, you need to avoid portalling the
`Select.Positioner` to the document's body.
```diff
-
{/* ... */}
-
```
If you have set `scrollBehavior="inside"` on the `Dialog`, you need to:
- Set the select positioning to `fixed` to avoid the select from being clipped
by the dialog.
- Set `hideWhenDetached` to `true` to hide the select when the trigger is
scrolled out of view.
```tsx
{/* ... */}
```
```tsx
"use client"
import {
Button,
CloseButton,
Dialog,
Portal,
Select,
createListCollection,
} from "@chakra-ui/react"
export const SelectOpenFromDialog = () => {
return (
Open Dialog
Select in Dialog
)
}
const frameworks = createListCollection({
items: [
{ label: "React.js", value: "react" },
{ label: "Vue.js", value: "vue" },
{ label: "Angular", value: "angular" },
{ label: "Svelte", value: "svelte" },
],
})
function DialogSelect() {
return (
Select framework
{frameworks.items.map((item) => (
{item.label}
))}
)
}
```
### Avatar Select
Here's an example of how to compose the `Select` and the `Avatar`.
```tsx
"use client"
import {
Avatar,
HStack,
Select,
createListCollection,
useSelectContext,
} from "@chakra-ui/react"
const SelectValue = () => {
const select = useSelectContext()
const items = select.selectedItems as Array<{ name: string; avatar: string }>
const { name, avatar } = items[0]
return (
{name}
)
}
export const SelectWithAvatar = () => {
return (
Select member
{members.items.map((item) => (
{item.name}
))}
)
}
const members = createListCollection({
items: [
{
name: "Jessica Jones",
id: "jessica_jones",
avatar:
"https://images.unsplash.com/photo-1531746020798-e6953c6e8e04?w=100",
},
{
name: "Kenneth Johnson",
id: "kenneth_johnson",
avatar:
"https://images.unsplash.com/photo-1523477800337-966dbabe060b?w=100",
},
{
name: "Kate Wilson",
id: "kate_wilson",
avatar:
"https://images.unsplash.com/photo-1609712409631-dbbb050746d1?w=100",
},
],
itemToString: (item) => item.name,
itemToValue: (item) => item.id,
})
```
### Country Select
Here's an example of how to use the `Select` component to select a country.
```tsx
"use client"
import { Portal, Select, createListCollection } from "@chakra-ui/react"
import { groupBy } from "es-toolkit"
export const SelectWithCountry = () => {
return (
Select country
{continents.map(([continent, items]) => (
{continent}
{items.map((item) => (
{countries.stringifyItem(item)}
))}
))}
)
}
const countries = createListCollection({
items: [
{ value: "US", label: "United States", flag: "🇺🇸", continent: "America" },
{ value: "CA", label: "Canada", flag: "🇨🇦", continent: "America" },
{ value: "MX", label: "Mexico", flag: "🇲🇽", continent: "America" },
{ value: "BR", label: "Brazil", flag: "🇧🇷", continent: "America" },
{ value: "ZA", label: "South Africa", flag: "🇿🇦", continent: "Africa" },
{ value: "NG", label: "Nigeria", flag: "🇳🇬", continent: "Africa" },
{ value: "MA", label: "Morocco", flag: "🇲🇦", continent: "Africa" },
{ value: "EG", label: "Egypt", flag: "🇪🇬", continent: "Africa" },
{ value: "CN", label: "China", flag: "🇨🇳", continent: "Asia" },
{ value: "JP", label: "Japan", flag: "🇯🇵", continent: "Asia" },
{ value: "IN", label: "India", flag: "🇮🇳", continent: "Asia" },
{ value: "KR", label: "South Korea", flag: "🇰🇷", continent: "Asia" },
{ value: "GB", label: "United Kingdom", flag: "🇬🇧", continent: "Europe" },
{ value: "FR", label: "France", flag: "🇫🇷", continent: "Europe" },
{ value: "DE", label: "Germany", flag: "🇩🇪", continent: "Europe" },
{ value: "IT", label: "Italy", flag: "🇮🇹", continent: "Europe" },
{ value: "ES", label: "Spain", flag: "🇪🇸", continent: "Europe" },
{ value: "AU", label: "Australia", flag: "🇦🇺", continent: "Oceania" },
{ value: "NZ", label: "New Zealand", flag: "🇳🇿", continent: "Oceania" },
{ value: "FJ", label: "Fiji", flag: "🇫🇯", continent: "Oceania" },
],
itemToString: (item) => `${item.flag} ${item.label}`,
itemToValue: (item) => item.value,
})
const continents = Object.entries(
groupBy(countries.items, (item) => item.continent),
)
```
### Icon Button
Here's an example of how to trigger the select component with an `IconButton`.
```tsx
"use client"
import {
HStack,
IconButton,
Portal,
Select,
createListCollection,
useSelectContext,
} from "@chakra-ui/react"
import {
RiAngularjsLine,
RiForbidLine,
RiReactjsLine,
RiSvelteLine,
RiVuejsLine,
} from "react-icons/ri"
const SelectTrigger = () => {
const select = useSelectContext()
const items = select.selectedItems as Framework[]
return (
{select.hasSelectedItems ? items[0].icon :
)
}
export const SelectWithIconButton = () => {
return (
{frameworks.items.map((framework) => (
{framework.icon}
{framework.label}
))}
)
}
const frameworks = createListCollection({
items: [
{ label: "React.js", value: "react", icon: ` | The collection of items |
| closeOnSelect | true | `boolean` | Whether the select should close after an item is selected |
| composite | true | `boolean` | Whether the select is a composed with other composite widgets like tabs or combobox |
| hideMode | 'display-none' | `HideMode` | How to hide content when mounted but not present.
- `'display-none'`: HTML `hidden` attribute. Effects stay alive.
- `'activity'`: React 19 ``. Effects pause. Requires React 19+. |
| variant | outline | `'outline' \| 'subtle' \| 'ghost'` | The variant of the component |
| size | md | `'xs' \| 'sm' \| 'md' \| 'lg'` | The size of the component |
| as | undefined | `React.ElementType` | The underlying element to render. |
| asChild | undefined | `boolean` | Use the provided child element as the default rendered element, combining their props and behavior. |
| unstyled | undefined | `boolean` | Whether to remove the component's style. |
| autoComplete | undefined | `string` | The autocomplete attribute for the hidden select. Enables browser autofill (e.g. "address-level1" for state). |
| defaultHighlightedValue | undefined | `string` | The initial value of the highlighted item when opened.
Use when you don't need to control the highlighted value of the select. |
| defaultOpen | undefined | `boolean` | Whether the select's open state is controlled by the user |
| defaultValue | undefined | `string[]` | The initial default value of the select when rendered.
Use when you don't need to control the value of the select. |
| deselectable | undefined | `boolean` | Whether the value can be cleared by clicking the selected item.
**Note:** this is only applicable for single selection |
| disabled | undefined | `boolean` | Whether the select is disabled |
| form | undefined | `string` | The associate form of the underlying select. |
| highlightedValue | undefined | `string` | The controlled key of the highlighted item |
| id | undefined | `string` | The unique identifier of the machine. |
| ids | undefined | `Partial<{\n root: string\n content: string\n control: string\n trigger: string\n clearTrigger: string\n label: string\n hiddenSelect: string\n positioner: string\n item: (id: string \| number) => string\n itemGroup: (id: string \| number) => string\n itemGroupLabel: (id: string \| number) => string\n}>` | The ids of the elements in the select. Useful for composition. |
| immediate | undefined | `boolean` | Whether to synchronize the present change immediately or defer it to the next frame |
| invalid | undefined | `boolean` | Whether the select is invalid |
| lazyMount | false | `boolean` | Whether to enable lazy mounting |
| loopFocus | false | `boolean` | Whether to loop the keyboard navigation through the options |
| multiple | undefined | `boolean` | Whether to allow multiple selection |
| name | undefined | `string` | The `name` attribute of the underlying select. |
| onExitComplete | undefined | `VoidFunction` | Function called when the animation ends in the closed state |
| onFocusOutside | undefined | `(event: FocusOutsideEvent) => void` | Function called when the focus is moved outside the component |
| onHighlightChange | undefined | `(details: HighlightChangeDetails) => void` | The callback fired when the highlighted item changes. |
| onInteractOutside | undefined | `(event: InteractOutsideEvent) => void` | Function called when an interaction happens outside the component |
| onOpenChange | undefined | `(details: OpenChangeDetails) => void` | Function called when the popup is opened |
| onPointerDownOutside | undefined | `(event: PointerDownOutsideEvent) => void` | Function called when the pointer is pressed down outside the component |
| onSelect | undefined | `(details: SelectionDetails) => void` | Function called when an item is selected |
| onValueChange | undefined | `(details: ValueChangeDetails) => void` | The callback fired when the selected item changes. |
| open | undefined | `boolean` | Whether the select menu is open |
| positioning | undefined | `PositioningOptions` | The positioning options of the menu. |
| present | undefined | `boolean` | Whether the node is present (controlled by the user) |
| readOnly | undefined | `boolean` | Whether the select is read-only |
| required | undefined | `boolean` | Whether the select is required |
| scrollToIndexFn | undefined | `(details: ScrollToIndexDetails) => void` | Function to scroll to a specific index |
| skipAnimationOnMount | false | `boolean` | Whether to allow the initial presence animation. |
| translations | undefined | `IntlTranslations` | Specifies the localized strings that identifies the accessibility elements and their states |
| unmountOnExit | false | `boolean` | Whether to unmount on exit. |
| value | undefined | `string[]` | The controlled keys of the selected items |
## Explorer
Explore the `Select` component parts interactively. Click on parts in the
sidebar to highlight them in the preview.
First
Second
Third
)
}
```
## Usage
```jsx
import { Separator } from "@chakra-ui/react"
```
```jsx
)
}
```
### Sizes
Use the `size` prop to change the size of the separator.
```tsx
import { Separator, Stack } from "@chakra-ui/react"
export const SeparatorWithSizes = () => {
return (
)
}
```
### Label
Use the `label` prop to add a label to the separator.
```tsx
import { HStack, Separator, Stack, Text } from "@chakra-ui/react"
export const SeparatorWithLabel = () => {
return (
Label (start)
Label (end)
Label (center)
)
}
```
### Vertical
Use the `orientation` prop to change the orientation of the separator.
```tsx
import { HStack, Separator, Text } from "@chakra-ui/react"
export const SeparatorVertical = () => {
return (
First
Second
)
}
```
### Responsive Orientation
Here's an example of how to change the `orientation` property based on the
screen size.
```tsx
import { Separator, Stack } from "@chakra-ui/react"
import { Box } from "@chakra-ui/react"
export const SeparatorWithResponsiveOrientation = () => {
return (
First
Second
)
}
```
:::note
When the `orientation` prop is a responsive value, the separator will be
rendered without `aria-orientation` and the role is set to `presentation`.
:::
## Props
| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| variant | solid | `'solid' \| 'dashed' \| 'dotted'` | The variant of the component |
| orientation | horizontal | `'vertical' \| 'horizontal'` | The orientation of the component |
| size | sm | `'xs' \| 'sm' \| 'md' \| 'lg'` | The size of the component |
| as | undefined | `React.ElementType` | The underlying element to render. |
| asChild | undefined | `boolean` | Use the provided child element as the default rendered element, combining their props and behavior. |
# Show
```tsx
"use client"
import { Button, Show, Stack } from "@chakra-ui/react"
import { useState } from "react"
export const ShowBasic = () => {
const [count, setCount] = useState(0)
return (
setCount(count + 1)}>
Value: {count}
3}>
My Content
)
}
```
## Usage
The `Show` component renders its children when the `when` value is truthy,
otherwise it renders the `fallback` prop.
```jsx
import { Show } from "@chakra-ui/react"
```
```jsx
Content
```
## Examples
### Fallback
Use the `fallback` prop to render a fallback component when the array is empty
or undefined.
```tsx
"use client"
import { Button, Show, Stack, Text } from "@chakra-ui/react"
import { useState } from "react"
export const ShowWithFallback = () => {
const [count, setCount] = useState(0)
return (
setCount(count + 1)}>
Value: {count}
3}
fallback={Not there yet. Keep clicking... }
>
Congrats! I am here
)
}
```
### Render Prop
Use the `children` render prop to narrow the type of the `when` value and remove
`undefined` | `null`
```tsx
import { Show } from "@chakra-ui/react"
export const ShowWithRenderProp = () => {
const value: number | undefined = 10
return {(value) => Value: {value}
}
}
```
## Props
| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| when | undefined | `T \| null \| undefined` | If `true`, it'll render the `children` prop |
| fallback | undefined | `React.ReactNode \| undefined` | The fallback content to render if `when` is `false` |
| as | undefined | `React.ElementType` | The underlying element to render. |
| asChild | undefined | `boolean` | Use the provided child element as the default rendered element, combining their props and behavior. |
# SimpleGrid
```tsx
import { SimpleGrid } from "@chakra-ui/react"
import { Box } from "@chakra-ui/react"
export const SimpleGridBasic = () => {
return (
)
}
```
## Usage
The `SimpleGrid` component allows you to create responsive grid layouts with
ease.
```jsx
import { SimpleGrid } from "@chakra-ui/react"
```
```jsx
```
## Examples
### Columns
Specify the number of columns for the grid layout using the `columns` prop.
```tsx
import { SimpleGrid } from "@chakra-ui/react"
import { Box } from "@chakra-ui/react"
export const SimpleGridWithColumns = () => (
)
```
### Auto-responsive
Make the grid responsive and adjust automatically without passing columns, by
using the `minChildWidth` prop. This uses css grid auto-fit and minmax()
internally.
```tsx
import { SimpleGrid } from "@chakra-ui/react"
import { Box } from "@chakra-ui/react"
export const SimpleGridWithAutofit = () => (
)
```
### Column Span
Specify the size of the column by using the `colSpan` prop.
```tsx
import { GridItem, SimpleGrid } from "@chakra-ui/react"
import { Box } from "@chakra-ui/react"
export const SimpleGridWithColSpan = () => (
Column 1
Column 2
)
```
### Row and Column Gap
Pass the `rowGap` and `columnGap` props to change the row and column spacing
between the grid items.
```tsx
import { SimpleGrid } from "@chakra-ui/react"
import { Box } from "@chakra-ui/react"
export const SimpleGridWithRowAndColGap = () => {
return (
)
}
```
# Skeleton
```tsx
import { HStack, Skeleton, SkeletonCircle, Stack } from "@chakra-ui/react"
export const SkeletonBasic = () => {
return (
)
}
```
## Usage
```jsx
import { Skeleton, SkeletonCircle, SkeletonText } from "@chakra-ui/react"
```
```jsx
```
## Examples
### Feed
Use the `Skeleton` component to create a feed skeleton.
```tsx
import {
HStack,
Skeleton,
SkeletonCircle,
SkeletonText,
Stack,
} from "@chakra-ui/react"
export const SkeletonForFeed = () => {
return (
)
}
```
### Text
Use the `SkeletonText` component to create a skeleton for text.
```tsx
import { SkeletonText } from "@chakra-ui/react"
export const SkeletonForText = () => {
return
Select
Select
)
}
```
### Variants
Use the `variant` prop to change the visual style of the Skeleton.
```tsx
import { HStack, Skeleton, Stack, Text } from "@chakra-ui/react"
export const SkeletonWithVariants = () => {
return (
pulse
shine
)
}
```
### Content Loading
When `loading` is changed to `false`, the Skeleton component will fade in.
```tsx
"use client"
import { Button, Skeleton, Stack, Text } from "@chakra-ui/react"
import { useState } from "react"
export const SkeletonWithLoaded = () => {
const [loading, setLoading] = useState(true)
return (
Chakra UI is cool
setLoading((c) => !c)}>
Toggle
)
}
```
### Start and End Color
Use the `--start-color` and `--end-color` CSS variables to change the start and
end color of the skeleton.
```tsx
import { Skeleton } from "@chakra-ui/react"
export const SkeletonWithStartEndColor = () => {
return (
Skip to Content
{/* Simulated navigation */}
Navigation
This represents a navigation area that users might want to skip over.
{/* Main content area */}
Main Content
This is the main content area. When users press Tab and then Enter
on the "Skip to Content" link, focus will jump directly here,
bypassing the navigation.
)
}
```
## Usage
Skip Navigation link and destination container for screen readers and keyboard
users.
Per
[WebAIM.org on WCAG 2.4.1 (Bypass Blocks - Level A)](https://webaim.org/standards/wcag/checklist#sc2.4.1),
because the main content is not always the first section that the user
encounters on a page, it is strongly recommended to include a skip link for
users to be able to bypass content that is present on multiple pages. Navigation
links are the most common skipped.
> A user with a screen reader or specialized software could skip content via the
> headings or `main` region, but this is not sufficient for sighted users who
> primarily use a keyboard.
```jsx
import { SkipNavContent, SkipNavLink } from "@chakra-ui/react"
```
```jsx
Skip to content
Skip to Content
{/* Simulated navigation */}
Navigation
This represents a navigation area that users might want to skip over.
{/* Main content area */}
Main Content
This is the main content area. When users press Tab and then Enter
on the "Skip to Content" link, focus will jump directly here,
bypassing the navigation.
)
}
```
### Custom ID
You can supply a custom id value using the `id` prop but you will have to use
this prop and value in both components, or they will not match.
```tsx
import { Box, SkipNavContent, SkipNavLink, Text } from "@chakra-ui/react"
export const SkipNavCustomId = () => {
return (
Skip to Main Content
{/* Simulated header and navigation */}
Header & Navigation
This example uses a custom ID "main-content" for both components to
ensure they match.
{/* Main content area with custom ID */}
Main Content (Custom ID)
Both the SkipNavLink and SkipNavContent use the same custom ID
"main-content" to ensure proper linking and focus management.
)
}
```
### With Main Content
The `SkipNavContent` component can wrap your main content area to ensure proper
focus management.
```tsx
import {
Box,
Heading,
SkipNavContent,
SkipNavLink,
Text,
VStack,
} from "@chakra-ui/react"
export const SkipNavWithContent = () => {
return (
Skip to Content
{/* Simulated header with multiple navigation items */}
Site Header
• Home
• About
• Services
• Contact
{/* SkipNavContent wrapping main content */}
Welcome to Our Site
This is the main content area. The SkipNavContent component wraps
this entire section, making it the target for the skip navigation
link.
When keyboard users press Tab to focus the "Skip to Content" link
and then press Enter, focus will jump directly to this content
area, bypassing all the navigation items above.
This is especially helpful for users with screen readers or those
who navigate primarily with keyboards.
)
}
```
## In Action
You can see these components in action on this page!
1. Place your cursor in the browser's address bar.
2. Remove any id queries from the url. (i.e. `/skip-nav#usage`)
3. Hit `Enter` to reload the page, then hit `Tab`. The Skip Nav link will appear
in the upper left.
4. Hitting `Enter` on the link will take you to the top of the docs content.
# Slider
```tsx
import { Slider } from "@chakra-ui/react"
export const SliderBasic = () => {
return (
)
}
```
## Usage
```tsx
import { Slider } from "@chakra-ui/react"
```
```tsx
```
:::info
If you prefer a closed component composition, check out the
[snippet below](#closed-component).
:::
## Shortcuts
### `Slider.Thumbs`
This component renders the `Slider.Thumb` and `Slider.HiddenInput` components
for each value.
The code below works:
```tsx
```
but this might be better if you don't need to customize the thumb:
```tsx
```
but this might be better if you don't need to customize the marker:
```tsx
{(size) => (
Slider - {size}
)}
)
}
```
### Variants
Use the `variant` prop to change the visual style of the slider.
```tsx
import { For, Slider, Stack } from "@chakra-ui/react"
export const SliderWithVariants = () => {
return (
{(variant) => (
Slider - {variant}
)}
)
}
```
### Colors
Use the `colorPalette` prop to change the color of the slider.
```tsx
import { For, Slider, Stack } from "@chakra-ui/react"
const colors = ["gray", "blue", "red", "green", "pink"]
export const SliderWithColors = () => {
return (
{(color) => (
)}
)
}
```
### Label
Use the `label` prop to add a label to the slider.
```tsx
import { Slider } from "@chakra-ui/react"
export const SliderWithLabel = () => {
return (
Quantity
)
}
```
### Range Slider
Set the `value` or `defaultValue` prop to an array to create a range slider.
```tsx
import { Slider } from "@chakra-ui/react"
export const SliderWithMultipleThumbs = () => {
return (
)
}
```
### Prevent Overlap
Use the `minStepsBetweenThumbs` prop to avoid thumbs with the same value.
```tsx
import { Slider } from "@chakra-ui/react"
export const SliderPreventOverlap = () => {
return (
)
}
```
### Collision Behavior
Use the `thumbCollisionBehavior` prop to control how thumbs interact when they
collide. Options are `"none"` (default), `"push"`, or `"swap"`.
```tsx
import { Slider, Stack, Text } from "@chakra-ui/react"
export const SliderWithCollisionBehavior = () => {
return (
Price Range
Try dragging the thumbs together to see them push each other
)
}
```
### Customization
Here's an example of customizing the thumb with custom icon and background.
```tsx
"use client"
import { Box, Slider } from "@chakra-ui/react"
import { MdGraphicEq } from "react-icons/md"
export const SliderCustomization = () => {
return (
)
}
```
### Value Text
Use the `Slider.ValueText` component to show the current value of the slider.
```tsx
import { HStack, Slider } from "@chakra-ui/react"
export const SliderWithValueText = () => {
return (
Volume
)
}
```
### Controlled
Use the `value` and `onValueChange` props to control the value of the slider.
```tsx
"use client"
import { Slider } from "@chakra-ui/react"
import { useState } from "react"
export const SliderControlled = () => {
const [value, setValue] = useState([40])
return (
setValue(e.value)}
>
)
}
```
### Store
An alternative way to control the slider is to use the `RootProvider` component
and the `useSlider` store hook.
This way you can access the slider state and methods from outside the slider.
```tsx
"use client"
import { Code, Slider, Stack, useSlider } from "@chakra-ui/react"
export const SliderWithStore = () => {
const slider = useSlider({
defaultValue: [40],
thumbAlignment: "center",
})
return (
current: {slider.value}
Slider
)
}
```
### Hook Form
Here's an example of how to integrate a slider with `react-hook-form`.
```tsx
"use client"
import { Button, Field, Slider, Stack } from "@chakra-ui/react"
import { standardSchemaResolver } from "@hookform/resolvers/standard-schema"
import { Controller, useForm } from "react-hook-form"
import { z } from "zod"
const formSchema = z.object({
value: z.array(
z
.number({ message: "Value is required" })
.min(60, { message: "Value must be greater than 60" }),
),
})
type FormValues = z.infer
export const SliderWithHookForm = () => {
const {
control,
handleSubmit,
formState: { errors },
} = useForm({
resolver: standardSchemaResolver(formSchema),
defaultValues: { value: [40] },
})
const onSubmit = handleSubmit((data) => console.log(data))
return (
)
}
```
### Disabled
Use the `disabled` prop to disable the slider.
```tsx
import { Slider } from "@chakra-ui/react"
export const SliderDisabled = () => {
return (
)
}
```
### Change End
Use the `onValueChangeEnd` prop to listen to the end of the slider change.
```tsx
"use client"
import { Box, Code, Slider, Stack } from "@chakra-ui/react"
import { useState } from "react"
const initialValue = [50]
export const SliderChangeEnd = () => {
const [value, setValue] = useState(initialValue)
const [endValue, setEndValue] = useState(initialValue)
return (
setValue(e.value)}
onValueChangeEnd={(e) => setEndValue(e.value)}
>
onChange: {value}
onChangeEnd: {endValue}
)
}
```
### Steps
Use the `step` prop to set the step value of the slider.
```tsx
import { Slider } from "@chakra-ui/react"
export const SliderWithStep = () => {
return (
)
}
```
### Thumb Alignment
Use the `thumbAlignment` and `thumbSize` prop to align the thumb within the
track. By default, the thumb is aligned to the start of the track.
```tsx
import { Slider, Stack } from "@chakra-ui/react"
export const SliderWithThumbAlignment = () => {
return (
Slider (contain)
Slider (center)
)
}
```
### Marks
Use the `marks` prop to display marks on the slider.
```tsx
import { For, Slider, Stack, Text, VStack } from "@chakra-ui/react"
export const SliderWithMarks = () => {
return (
{(size) => (
size = {size}
)}
)
}
```
You can also add labels to the marks using the `marks` prop.
```tsx
import { Slider } from "@chakra-ui/react"
const marks = [
{ value: 0, label: "0%" },
{ value: 50, label: "50%" },
{ value: 100, label: "100%" },
]
export const SliderWithMarksAndLabel = () => {
return (
)
}
```
### Vertical
Use the `orientation` prop to change the orientation of the slider.
```tsx
import { Slider } from "@chakra-ui/react"
export const SliderVertical = () => {
return (
)
}
```
### Vertical with Marks
Here's an example of a vertical slider with marks.
```tsx
import { Slider } from "@chakra-ui/react"
const marks = [
{ value: 0, label: "0%" },
{ value: 50, label: "50%" },
{ value: 100, label: "100%" },
]
export const SliderWithMarksVertical = () => {
return (
)
}
```
### Dragging Indicator
Render the `Slider.DraggingIndicator` component to show an indicator or tooltip
when dragging the thumb.
> Pro Tip: You can render the `Slider.ValueText` component inside the
> `Slider.DraggingIndicator` to show the current value.
```tsx
import { Slider } from "@chakra-ui/react"
export const SliderWithDraggingIndicator = () => {
return (
)
}
```
### Closed Component
If you prefer a closed component composition, check out the snippet below.
)
}
```
### Colors
Use the `colorPalette` prop to change the color scheme of the spinner.
```tsx
import { Spinner, Stack } from "@chakra-ui/react"
export const SpinnerWithColors = () => {
return (
{["gray","red","green","blue","teal","pink","purple","cyan","orange","yellow"].map((colorPalette) => (
))}
)
}
```
### Custom Color
Use the `color` prop to pass a custom color to the spinner.
```tsx
import { Spinner } from "@chakra-ui/react"
export const SpinnerCustomColor = () => {
return
)
```
### Label
Compose the spinner with a label to provide additional context.
```tsx
import { Spinner, Text, VStack } from "@chakra-ui/react"
export const SpinnerWithLabel = () => {
return (
Loading...
)
}
```
### Overlay
Compose spinner with the `AbsoluteCenter` component to overlay the spinner on
top of another component.
```tsx
import { Box, Center, Heading, Spinner, Text } from "@chakra-ui/react"
export const SpinnerWithOverlay = () => {
return (
Some heading text
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed ac
consectetur libero, id ultricies urna. Sed ac consectetur libero, id
fames ac ante ipsum primis in faucibus.
)
}
```
## Props
### Root
| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| size | md | `'inherit' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | The size of the component |
| as | undefined | `React.ElementType` | The underlying element to render. |
| asChild | undefined | `boolean` | Use the provided child element as the default rendered element, combining their props and behavior. |
# Splitter
```tsx
import { Center, Splitter } from "@chakra-ui/react"
export const SplitterBasic = () => {
return (
A
B
)
}
```
## Usage
```jsx
import { Splitter } from "@chakra-ui/react"
```
```jsx
```
## Shortcuts
The `Splitter` component provides shortcuts for common use cases.
### SplitterResizeTrigger
The `Splitter.ResizeTrigger` renders the `Splitter.ResizeTriggerSeparator` and
`Splitter.ResizeTriggerIndicator` within it by default.
Explicitly writing this:
```jsx
```
## Examples
### Controlled
Use `onResize` and `size` props to manage panel sizes programmatically.
```tsx
setSizes(details.size)}
>
{/* ... */}
```
```tsx
"use client"
import { Center, Code, HStack, Span, Splitter, Stack } from "@chakra-ui/react"
import { useState } from "react"
import { LuMouse, LuMoveHorizontal } from "react-icons/lu"
export const SplitterControlled = () => {
const [sizes, setSizes] = useState([50, 50])
return (
Drag the handle to resize panels
setSizes(details.size)}
borderWidth="1px"
minH="60"
>
A
B
Panel A: {sizes[0].toFixed(1)}% | Panel B: {sizes[1].toFixed(1)}%
)
}
```
### Store
An alternative way to control the splitter is to use the `RootProvider`
component and the `useSplitter` store hook.
This way you can access the splitter state and methods from outside the
splitter.
```tsx
"use client"
import { Center, Code, Splitter, Stack, useSplitter } from "@chakra-ui/react"
export const SplitterWithStore = () => {
const splitter = useSplitter({
defaultSize: [50, 50],
panels: [{ id: "a" }, { id: "b", minSize: 20 }],
})
const sizes = splitter
.getSizes()
.map((size) => size.toFixed(1))
.join("%, ")
return (
A
B
Size: {JSON.stringify(sizes, null, 2)}
)
}
```
### Vertical
Pass the `orientation="vertical"` prop to the `Splitter.Root` component for
stacked panels that resize vertically.
```tsx
import { Center, Splitter } from "@chakra-ui/react"
export const SplitterVertical = () => {
return (
A
B
)
}
```
### Responsive Orientation
Use the `useBreakpointValue` hook to change the splitter orientation based on
screen size. This example shows a vertical splitter on mobile devices and a
horizontal splitter on larger screens.
```tsx
"use client"
import { Center, Splitter, useBreakpointValue } from "@chakra-ui/react"
export const SplitterResponsiveOrientation = () => {
const orientation = useBreakpointValue<"horizontal" | "vertical">({
base: "vertical",
md: "horizontal",
})
return (
A
B
)
}
```
### Multiple Panels
Create layouts with more than two resizable panels by passing an array of panels
to the `panels` prop of the `Splitter.Root` component.
```tsx
import { Center, Splitter } from "@chakra-ui/react"
export const SplitterMultiplePanels = () => {
return (
A
B
C
)
}
```
### Collapsible Panels
Make the panels collapsible and snapped to a specific size by setting the
`collapsible` and `collapsedSize` properties on a panel in the `panels` array.
This allows users to snap panels to a defined minimum size.
```tsx
{/* ... */}
```
```tsx
import { Box, Center, HStack, Splitter } from "@chakra-ui/react"
import { LuMouse, LuMoveHorizontal } from "react-icons/lu"
export const SplitterCollapsible = () => {
return (
A
B
)
}
```
### Min/Max Constraints
Set `minSize` and `maxSize` on panels to constrain their resizable range and
prevent resizing beyond these boundaries.
```tsx
"use client"
import { Center, Code, HStack, Span, Splitter, Stack } from "@chakra-ui/react"
import { useState } from "react"
import { LuMouse, LuMoveHorizontal } from "react-icons/lu"
export const SplitterMinMaxConstraints = () => {
const [sizes, setSizes] = useState([30, 70])
return (
Drag to resize - Panel A: 20-60%, Panel B: min 40%
setSizes(details.size)}
minH="60"
>
A
{sizes[0].toFixed(1)}% (min: 20%, max: 60%)
B
{sizes[1].toFixed(1)}% (min: 40%)
)
}
```
### CSS Unit Sizes
In addition to percentages, `defaultSize`, `minSize`, and `maxSize` accept CSS
units like `px`, `em`, `rem`, `vh`, and `vw`. This is useful for panels that
should keep a fixed width, such as a navigation sidebar.
:::warning
CSS-unit sizes are measured on the client, so panels using them can shift after
hydration. Use percentage sizes for a stable server-rendered layout.
:::
```tsx
import { Center, Splitter } from "@chakra-ui/react"
export const SplitterCssUnits = () => {
return (
Nav
Main
)
}
```
### Resize Behavior
Set `resizeBehavior` on a panel to control how it reacts when the parent group
resizes. Use `"preserve-pixel-size"` to keep a panel's pixel size constant (so
the other panels absorb the change) instead of scaling proportionally.
```tsx
import { Center, Code, Splitter, Stack } from "@chakra-ui/react"
export const SplitterResizeBehavior = () => {
return (
Main
)
}
```
### Nested Panels
Here's an example of how to nest splitters inside panels to create more complex
layouts. Each nested splitter can have its own orientation, sizes, and behaviors
independent of the parent splitter.
```tsx
import { Center, Splitter } from "@chakra-ui/react"
export const SplitterNested = () => {
return (
A
B1
B2
)
}
```
### Storage
Set a `defaultSize` and pair it with a storage solution, such as
`useLocalStorage`, to save users’ panel size preferences. This ensures that
panel layouts persist across sessions. Alternatively, you can use cookies or
other storage mechanisms depending on your needs.
```tsx
"use client"
import {
Badge,
Button,
Center,
HStack,
Span,
Splitter,
Stack,
} from "@chakra-ui/react"
import { LuBox, LuMouse, LuMoveHorizontal, LuTrash2 } from "react-icons/lu"
import { useLocalStorage } from "react-use"
export const SplitterWithStorage = () => {
const [sizes, setSizes] = useLocalStorage("splitter-sizes", [70, 50])
const formattedSizes = sizes?.map((size) => size.toFixed(1)).join(", ")
const hasSavedState = sizes && sizes.length > 0
const clearStorage = () => {
setSizes(undefined)
}
return (
Drag to resize panels
{hasSavedState && (
)}
setSizes(e.size)}
borderWidth="1px"
minH="60"
>
A
B
)
}
```
### Disabled Resize
Pass the `disabled` prop to the `Splitter.ResizeTrigger` to disable resize on a
panel. This is useful if you want certain panels to remain fixed while allowing
others to resize.
```tsx
A
B
)
}
```
### Separator Only
Customize the resize trigger to show only the separator without the indicator.
This creates a minimal, clean appearance while maintaining full resize
functionality.
```tsx
```
```tsx
import { Center, Splitter } from "@chakra-ui/react"
export const SplitterSeparatorOnly = () => {
return (
A
B
)
}
```
### Reset on Double Click
Use `Splitter.Context` to access the splitter context and add a double-click
handler to the resize trigger. This example resets panel sizes to their default
values when the resize handle is double-clicked.
```tsx
"use client"
import { Center, Splitter } from "@chakra-ui/react"
export const SplitterResetOnDoubleClick = () => {
return (
A
{(context) => (
{
context.resetSizes()
}}
/>
)}
B
)
}
```
### Resize Events
Track resize events using `onResizeStart`, `onResize`, and `onResizeEnd` props.
This example logs all resize events with timestamps and panel sizes, useful for
debugging or implementing custom resize behavior.
```tsx
"use client"
import { Center, HStack, Span, Splitter, Stack } from "@chakra-ui/react"
import { useCallback, useEffect, useRef } from "react"
import { useState } from "react"
import { LuMouse, LuMoveHorizontal } from "react-icons/lu"
type EventLog = [number, string, string]
export const SplitterResizeEvents = () => {
const [eventLog, setEventLog] = useState([])
const logEvent = useCallback(
(eventName: string, details?: { size?: number[] }) => {
const timestamp = Date.now()
const sizeInfo = details?.size
? `[${details.size.map((s) => s.toFixed(1)).join(", ")}]`
: ""
setEventLog((prev) => [[timestamp, eventName, sizeInfo], ...prev])
},
[],
)
const throttledLogEvent = useThrottle(logEvent, 100)
return (
Drag the handle to resize panels
logEvent("onResizeStart")}
onResize={(details) => throttledLogEvent("onResize", details)}
onResizeEnd={(details) => logEvent("onResizeEnd", details)}
>
A
B
{eventLog.length === 0 ? (
Resize events will appear here...
) : (
eventLog.map(([time, eventName, sizeInfo], i) => {
const date = new Date(time)
return (
{date.toLocaleTimeString()}
{eventName}
{sizeInfo && {sizeInfo} }
)
})
)}
)
}
function useThrottle void>(
fn: T,
delay: number,
): T {
const lastRunRef = useRef(0)
const timeoutRef = useRef(null)
useEffect(() => {
return () => {
if (timeoutRef.current) {
clearTimeout(timeoutRef.current)
}
}
}, [])
return useCallback(
((...args: Parameters) => {
const now = Date.now()
const timeSinceLastRun = now - lastRunRef.current
if (timeSinceLastRun >= delay) {
lastRunRef.current = now
fn(...args)
} else {
if (timeoutRef.current) {
clearTimeout(timeoutRef.current)
}
timeoutRef.current = setTimeout(() => {
lastRunRef.current = Date.now()
fn(...args)
}, delay - timeSinceLastRun)
}
}) as T,
[fn, delay],
)
}
```
### Keyboard Resize
The `Splitter` supports keyboard-based resizing for accessibility and precise
control:
- Press Tab until the resize handle is focused.
- Use Arrow keys to resize panels.
- Hold Shift for larger steps.
- Press Home / End to jump to minimum or maximum sizes.
- Control the step size using the `keyboardResizeBy` prop.
```tsx
import { Box, Center, HStack, Span, Splitter } from "@chakra-ui/react"
import { LuKeyboard, LuMoveLeft, LuMoveRight } from "react-icons/lu"
export const SplitterKeyboardResize = () => {
return (
Focus the resize handle and use arrow keys
A
B
)
}
```
### Conditional Rendering
This example shows a horizontal splitter where panels can be shown or hidden
dynamically. Use the buttons above the splitter to toggle the left and right
panels - perfect for layouts where certain sections may not always be needed.
The splitter automatically adjusts the remaining panels when one is hidden,
keeping everything responsive. Initial panel sizes are set with `defaultSize`,
and `minSize` ensures panels never shrink too small.
```tsx
"use client"
import {
Button,
Center,
HStack,
Splitter,
Stack,
useSplitter,
} from "@chakra-ui/react"
import { Fragment, useRef, useState } from "react"
const initialPanels: Splitter.PanelData[] = [
{ id: "left", order: 0 },
{ id: "center", order: 1 },
{ id: "right", order: 2 },
]
const getLayoutKey = (panels: Array<{ id: string }>): string => {
return panels.map((p) => p.id).join(":")
}
const distributeSizes = (count: number): number[] =>
Array(count).fill(100 / count)
export const SplitterConditionalRendering = () => {
const [panels, setPanels] = useState(initialPanels)
const [sizes, setSizes] = useState([])
const initialLayout = getLayoutKey(initialPanels)
const layoutCache = useRef>({
[initialLayout]: [],
})
const splitter = useSplitter({
panels: panels.map((p) => ({ id: p.id, minSize: 20 })),
size: sizes,
orientation: "horizontal",
onResize: ({ size, layout }) => {
setSizes(size)
layoutCache.current[layout] = size
},
})
const items = splitter.getItems()
const hidePanel = (id: string) => {
const currentLayout = getLayoutKey(panels)
layoutCache.current[currentLayout] = sizes
const index = panels.findIndex((panel) => panel.id === id)
const newPanels = panels.filter((panel) => panel.id !== id)
const newSizes = sizes.filter((_, i) => i !== index)
setPanels(newPanels)
setSizes(newSizes)
}
const showPanel = (id: string) => {
const panel = initialPanels.find((panel) => panel.id === id)
if (!panel) return
const nextPanels = [...panels, panel].sort(
(a, b) => (a.order ?? 0) - (b.order ?? 0),
)
const nextLayout = getLayoutKey(nextPanels)
const cachedSizes = layoutCache.current[nextLayout]
setPanels(nextPanels)
setSizes(cachedSizes || distributeSizes(nextPanels.length))
}
const isPanelVisible = (id: string) => {
return panels.some((p) => p.id === id)
}
const togglePanel = (id: string) => {
if (isPanelVisible(id)) {
hidePanel(id)
} else {
showPanel(id)
}
}
return (
togglePanel("left")}>
{isPanelVisible("left") ? "Hide Left" : "Show Left"}
togglePanel("right")}
>
{isPanelVisible("right") ? "Hide Right" : "Show Right"}
{items.map((item) => (
{item.type === "panel" && (
{item.id}
)}
{item.type === "handle" &&
))}
)
}
```
### Dynamic Panels
Add or remove panels dynamically while maintaining relative proportions. This
example demonstrates how to manage panel state and redistribute sizes when
panels are added or removed.
```tsx
"use client"
import {
Button,
Center,
HStack,
IconButton,
Splitter,
Stack,
useSplitter,
} from "@chakra-ui/react"
import { Fragment, useState } from "react"
import { LuMinus, LuPlus } from "react-icons/lu"
const MAX_PANELS = 5
export const SplitterDynamicPanel = () => {
const [panelIds, setPanelIds] = useState(["a", "b"])
const [sizes, setSizes] = useState(distributeSizes(2))
const splitter = useSplitter({
size: sizes,
panels: panelIds.map((id: string) => ({ id, minSize: 15 })),
onResize: (details) => setSizes(details.size),
})
const items = splitter.getItems()
const panelCount = items.filter((item) => item.type === "panel").length
const addPanel = () => {
if (panelIds.length >= MAX_PANELS) return // Prevent adding more than MAX_PANELS
const newId = uuid()
const newSizes = redistributeSizesForNewPanel(sizes, panelIds.length + 1)
setSizes(newSizes)
setPanelIds([...panelIds, newId])
}
const removePanel = (id: string) => {
if (panelIds.length <= 1) return
const indexToRemove = panelIds.indexOf(id)
const newSizes = redistributeSizesAfterRemoval(sizes, indexToRemove)
setSizes(newSizes)
setPanelIds(panelIds.filter((panelId: string) => panelId !== id))
}
return (
= MAX_PANELS}
>
{panelCount} panel{panelCount !== 1 ? "s" : ""}
{items.map((item) => (
{item.type === "panel" && (
{item.id}
removePanel(item.id)}
disabled={panelCount === 1}
>
)}
{item.type === "handle" &&
))}
)
}
const uuid = () => {
// Generate a single random lowercase letter
const letters = "cdefghijklmnopqrstuvwxyz"
return letters[Math.floor(Math.random() * letters.length)]
}
const distributeSizes = (count: number): number[] =>
Array(count).fill(100 / count)
const calculateTotalSize = (sizes: number[]): number =>
sizes.reduce((sum, size) => sum + size, 0)
const redistributeSizesForNewPanel = (
currentSizes: number[],
newPanelCount: number,
): number[] => {
const totalSize = calculateTotalSize(currentSizes)
const newPanelSize = totalSize / newPanelCount
// Reduce existing panels proportionally to make room for the new panel
const adjustedSizes = currentSizes.map((size) => {
const proportion = size / totalSize
return size - newPanelSize * proportion
})
adjustedSizes.push(newPanelSize)
return adjustedSizes
}
const redistributeSizesAfterRemoval = (
currentSizes: number[],
indexToRemove: number,
): number[] => {
const removedSize = currentSizes[indexToRemove] || 0
const remainingSizes = currentSizes.filter((_, i) => i !== indexToRemove)
const totalRemainingSize = calculateTotalSize(remainingSizes)
// Distribute removed panel's size proportionally to remaining panels
return remainingSizes.map(
(size) => size + (removedSize * size) / totalRemainingSize,
)
}
```
### Composition
A real-world VS Code-like layout demonstrating nested splitters with different
orientations, collapsible panels, and integrated code editing.
```tsx
"use client"
import {
CodeBlock,
HStack,
Span,
Splitter,
Stack,
createShikiAdapter,
} from "@chakra-ui/react"
import React, { useState } from "react"
import { LuFile, LuFolder } from "react-icons/lu"
import type { HighlighterGeneric } from "shiki"
type FileNode = {
name: string
type: "file" | "folder"
id?: string
children?: FileNode[]
}
const fileTree: FileNode[] = [
{
name: "src",
type: "folder",
children: [
{ name: "App.tsx", type: "file", id: "app" },
{ name: "index.tsx", type: "file", id: "index" },
],
},
{ name: "package.json", type: "file", id: "package" },
]
export const SplitterIdeLayout = () => {
const [activeFileId, setActiveFileId] = useState("app")
const activeFile = fileContents[activeFileId] || fileContents.app
return (
{/* File Explorer */}
{/* Editor */}
)
}
////////////////////////////////////////////////////////////////////////////////
type FileTreeProps = {
nodes: FileNode[]
activeFileId: string
onFileClick: (fileId: string) => void
}
const FileTree = ({ nodes, activeFileId, onFileClick }: FileTreeProps) => {
const renderFileTree = (fileNodes: FileNode[], level = 0) => {
return fileNodes.map((node) => {
if (node.type === "folder") {
return (
0 ? "4" : "0"}
width="full"
>
{node.name}
{node.children && (
{renderFileTree(node.children, level + 1)}
)}
)
}
const isActive = node.id === activeFileId
return (
node.id && onFileClick(node.id)}
>
{node.name}
)
})
}
return (
{renderFileTree(nodes)}
)
}
////////////////////////////////////////////////////////////////////////////////
const shikiAdapter = createShikiAdapter>({
async load() {
const { createHighlighter } = await import("shiki")
return createHighlighter({
langs: ["tsx", "ts", "js", "json", "bash"],
themes: ["github-dark"],
})
},
theme: "github-dark",
})
const CodeBlockAdapter = (props: React.PropsWithChildren) => (
{props.children}
)
type EditorProps = {
activeFileId: string
activeFile: { code: string; language: string }
fileTree: FileNode[]
}
const Editor = ({ activeFileId, activeFile, fileTree }: EditorProps) => {
const fileName =
fileTree
.flatMap((node) =>
node.type === "folder" ? node.children || [] : [node],
)
.find((node) => node.id === activeFileId)?.name || "App.tsx"
return (
{fileName}
)
}
////////////////////////////////////////////////////////////////////////////////
type TerminalProps = {
output: string
}
const Terminal = ({ output }: TerminalProps) => {
return (
Terminal
)
}
////////////////////////////////////////////////////////////////////////////////
const fileContents: Record = {
app: {
code: `import { useState } from "react"
export const Counter = () => {
const [count, setCount] = useState(0)
return (
Count: {count}
setCount(count + 1)}>
Increment
)
}`,
language: "tsx",
},
index: {
code: `import React from "react"
import ReactDOM from "react-dom/client"
import App from "./App"
ReactDOM.createRoot(document.getElementById("root")!).render(
)`,
language: "tsx",
},
package: {
code: `{
"name": "my-app",
"version": "1.0.0",
"scripts": {
"dev": "vite",
"build": "vite build"
},
"dependencies": {
"react": "^18.2.0",
"react-dom": "^18.2.0"
}
}`,
language: "json",
},
}
const terminalOutput = `$ npm run dev
> dev@1.0.0 dev
> vite
VITE v5.0.0 ready in 234 ms
➜ Local: http://localhost:5173/
➜ Network: use --host to expose
➜ press h + enter to show help`
```
## Guides
### Splitter Context
When you need to programmatically control the splitter, you can access the
splitter context and its methods in two ways:
- using the `Splitter.Context` render prop
- using the `useSplitterContext` hook
#### Splitter.Context Render Prop
Use `Splitter.Context` as a render prop to access the context within the
component tree:
```tsx
Panel A
{(context) => (
{
context.resetSizes()
}}
/>
)}
Panel B
```
#### useSplitterContext Hook
Alternatively, use the `useSplitterContext` hook in a child component:
```tsx
import { useSplitterContext } from "@chakra-ui/react"
const ResetButton = () => {
const splitter = useSplitterContext()
return splitter.resetSizes()}>Reset Sizes
}
const Demo = () => (
Panel A
)
```
The context object (from either method) includes:
- **`resetSizes()`**: Reset all panels to their default sizes
- **`setSize(sizes)`**: Set panel sizes programmatically
- **`collapsePanel(id)`**: Collapse a specific panel
- **`expandPanel(id)`**: Expand a collapsed panel
- **`isPanelCollapsed(id)`**: Check if a panel is collapsed
- **`getItems()`**: Get the current items (panels and handles)
- **`size`**: Current panel sizes array
## Props
### Root
| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| panels | undefined | `PanelData[]` | The size constraints of the panels. |
| orientation | horizontal | `'horizontal' \| 'vertical'` | The orientation of the splitter. Can be `horizontal` or `vertical` |
| as | undefined | `React.ElementType` | The underlying element to render. |
| asChild | undefined | `boolean` | Use the provided child element as the default rendered element, combining their props and behavior. |
| unstyled | undefined | `boolean` | Whether to remove the component's style. |
| defaultSize | undefined | `PanelSize[]` | The initial size of the panels when rendered.
Use when you don't need to control the size of the panels. |
| id | undefined | `string` | The unique identifier of the machine. |
| ids | undefined | `Partial<{\n root: string\n resizeTrigger: (id: string) => string\n label: (id: string) => string\n panel: (id: string \| number) => string\n}>` | The ids of the elements in the splitter. Useful for composition. |
| keyboardResizeBy | undefined | `number` | The number of pixels to resize the panel by when the keyboard is used. |
| nonce | undefined | `string` | The nonce for the injected splitter cursor stylesheet. |
| onCollapse | undefined | `(details: ExpandCollapseDetails) => void` | Function called when a panel is collapsed. |
| onExpand | undefined | `(details: ExpandCollapseDetails) => void` | Function called when a panel is expanded. |
| onResize | undefined | `(details: ResizeDetails) => void` | Function called when the splitter is resized. |
| onResizeEnd | undefined | `(details: ResizeEndDetails) => void` | Function called when the splitter resize ends. |
| onResizeStart | undefined | `() => void` | Function called when the splitter resize starts. |
| registry | undefined | `SplitterRegistry` | The splitter registry to use for multi-drag support.
When provided, enables dragging at the intersection of multiple splitters. |
| size | undefined | `PanelSize[]` | The controlled size data of the panels |
### Panel
| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| id | undefined | `string` | undefined |
| as | undefined | `React.ElementType` | The underlying element to render. |
| asChild | undefined | `boolean` | Use the provided child element as the default rendered element, combining their props and behavior. |
### ResizeTrigger
| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| id | undefined | `ResizeTriggerId` | undefined |
| as | undefined | `React.ElementType` | The underlying element to render. |
| asChild | undefined | `boolean` | Use the provided child element as the default rendered element, combining their props and behavior. |
| disabled | undefined | `boolean` | undefined |
## Explorer
Explore the `Splitter` component parts interactively. Click on parts in the
sidebar to highlight them in the preview.
)
}
```
## Usage
By default, Stack applies `flex-direction: column` and `gap: 8px` to its
children.
```jsx
import { HStack, Stack, VStack } from "@chakra-ui/react"
```
```jsx
```
## Examples
### Horizontal
Use the `direction` prop to change the direction of the stack.
```tsx
import { Stack } from "@chakra-ui/react"
import { Box } from "@chakra-ui/react"
export const StackHorizontal = () => {
return (
)
}
```
### HStack
Alternatively, you can use the `HStack` to create a horizontal stack and align
its children horizontally.
```tsx
import { HStack } from "@chakra-ui/react"
import { Box } from "@chakra-ui/react"
export const StackWithHstack = () => {
return (
)
}
```
### VStack
Use the `VStack` to create a vertical stack and align its children vertically.
```tsx
import { VStack } from "@chakra-ui/react"
import { Box } from "@chakra-ui/react"
export const StackWithVstack = () => {
return (
)
}
```
### Separator
Use the `separator` prop to add a separator between the stack items.
```tsx
import { Stack, StackSeparator } from "@chakra-ui/react"
import { Box } from "@chakra-ui/react"
export const StackWithSeparator = () => {
return (
)
}
```
# Stat
```tsx
import { Stat } from "@chakra-ui/react"
export const StatBasic = () => {
return (
Unique visitors
192.1k
)
}
```
## Usage
```tsx
import { Stat } from "@chakra-ui/react"
```
```tsx
```
## Examples
### Format Options
Use the `FormatNumber` component within `Stat.ValueText` to format the value.
```tsx
import { FormatNumber, Stat } from "@chakra-ui/react"
export const StatWithFormatOptions = () => {
return (
Revenue
)
}
```
### Indicator
Here's an example of how to display a statistic with an indicator.
```tsx
import { Badge, Stat } from "@chakra-ui/react"
export const StatWithIndicator = () => {
return (
Unique visitors
192.1k
)
}
```
### Info Tip
Compose the `InfoTip` and `Stat.Label` components to display an info tip.
```tsx
import { Stat } from "@chakra-ui/react"
import { InfoTip } from "@/components/ui/toggle-tip"
export const StatWithInfoTip = () => {
return (
Unique
Some info
192.1k
)
}
```
### Value Unit
Here's an example of how to display a value with a unit.
```tsx
import { Stat } from "@chakra-ui/react"
export const StatWithValueUnit = () => {
return (
Time to complete
3 hr
20 min
)
}
```
### Progress Bar
Here's an example of how to display a statistic with a progress bar.
```tsx
import { FormatNumber, Progress, Stat } from "@chakra-ui/react"
export const StatWithProgressBar = () => {
return (
This week
+12% from last week
)
}
```
### Icon
Here's an example of how to display a statistic with an icon.
```tsx
import { HStack, Icon, Stat } from "@chakra-ui/react"
import { LuDollarSign } from "react-icons/lu"
export const StatWithIcon = () => {
return (
Sales
$4.24k
)
}
```
### Trend
Here's an example of how to display a statistic with a trend indicator.
```tsx
import { Badge, FormatNumber, HStack, Stat } from "@chakra-ui/react"
export const StatWithTrend = () => {
return (
Unique
since last month
)
}
```
### Closed Component
Here's how to setup the Stat for a closed component composition.
)
}
```
## Usage
```tsx
import { Status } from "@chakra-ui/react"
```
```tsx
```
:::info
If you prefer a closed component composition, check out the
[snippet below](#closed-component).
:::
## Examples
### Label
Render the label within the `Status.Root` component.
```tsx
import { HStack, Status } from "@chakra-ui/react"
export const StatusWithLabel = () => {
return (
)
}
```
### Sizes
Use the `size` prop to change the size of the status component.
```tsx
import { For, HStack, Stack, Status } from "@chakra-ui/react"
export const StatusWithSizes = () => {
return (
{(size) => (
)}
)
}
```
### Closed Component
Here's how to setup the Status for a closed component composition.
{steps.map((step, index) => (
{step.title}
))}
{steps.map((step, index) => (
{step.description}
))}
All steps are complete!
Prev
Next
)
}
const steps = [
{
title: "Step 1",
description: "Step 1 description",
},
{
title: "Step 2",
description: "Step 2 description",
},
{
title: "Step 3",
description: "Step 3 description",
},
]
```
## Usage
```tsx
import { Steps } from "@chakra-ui/react"
```
```tsx
```
## Examples
### Sizes
Use the `size` prop to change the size of the steps component.
```tsx
import { Button, ButtonGroup, For, Stack, Steps } from "@chakra-ui/react"
export const StepsWithSizes = () => {
return (
{(size) => (
{steps.map((step, index) => (
{step.title}
))}
{steps.map((step, index) => (
{step.description}
))}
All steps are complete!
Prev
Next
)}
)
}
const steps = [
{
title: "Step 1",
description: "Step 1 description",
},
{
title: "Step 2",
description: "Step 2 description",
},
{
title: "Step 3",
description: "Step 3 description",
},
]
```
### Variants
Use the `variant` prop to change the appearance of the steps component.
```tsx
import { Button, ButtonGroup, For, Stack, Steps } from "@chakra-ui/react"
export const StepsWithVariants = () => {
return (
{(variant) => (
{steps.map((step, index) => (
{step.title}
))}
{steps.map((step, index) => (
{step.description}
))}
All steps are complete!
Prev
Next
)}
)
}
const steps = [
{
title: "Step 1",
description: "Step 1 description",
},
{
title: "Step 2",
description: "Step 2 description",
},
{
title: "Step 3",
description: "Step 3 description",
},
]
```
### Colors
Use the `colorPalette` prop to change the color scheme of the component.
```tsx
import { Button, ButtonGroup, For, Stack, Steps } from "@chakra-ui/react"
export const StepsWithColors = () => {
return (
{(colorPalette) => (
{steps.map((step, index) => (
{step.title}
))}
{steps.map((step, index) => (
{step.description}
))}
All steps are complete!
Prev
Next
)}
)
}
const steps = [
{
title: "Step 1",
description: "Step 1 description",
},
{
title: "Step 2",
description: "Step 2 description",
},
{
title: "Step 3",
description: "Step 3 description",
},
]
```
### Trigger
Use the `Steps.Trigger` component to make the step clickable.
```tsx
import { Button, ButtonGroup, Steps } from "@chakra-ui/react"
export const StepsWithTrigger = () => {
return (
{steps.map((step, index) => (
{step.title}
))}
{steps.map((step, index) => (
{step.description}
))}
All steps are complete!
Prev
Next
)
}
const steps = [
{
title: "Step 1",
description: "Step 1 description",
},
{
title: "Step 2",
description: "Step 2 description",
},
{
title: "Step 3",
description: "Step 3 description",
},
]
```
### Vertical
Use the `orientation` prop to change the orientation of the steps component.
```tsx
import { Button, ButtonGroup, Stack, Steps } from "@chakra-ui/react"
export const StepsVertical = () => {
return (
{steps.map((step, index) => (
{step.title}
))}
{steps.map((step, index) => (
{step.description}
))}
All steps are complete!
Prev
Next
)
}
const steps = [
{
title: "Step 1",
description: "Step 1 description",
},
{
title: "Step 2",
description: "Step 2 description",
},
{
title: "Step 3",
description: "Step 3 description",
},
]
```
### Controlled
Use the `step` and `onStepChange` props to control the current step of the steps
component.
```tsx
"use client"
import { Button, ButtonGroup, Steps } from "@chakra-ui/react"
import { useState } from "react"
export const StepsControlled = () => {
const [step, setStep] = useState(1)
return (
setStep(e.step)}
count={steps.length}
>
{steps.map((step, index) => (
{step.title}
))}
{steps.map((step, index) => (
{step.description}
))}
All steps are complete!
Prev
Next
)
}
const steps = [
{
title: "Step 1",
description: "Step 1 description",
},
{
title: "Step 2",
description: "Step 2 description",
},
{
title: "Step 3",
description: "Step 3 description",
},
]
```
### Validation
Use the `isStepValid` prop to validate each step before allowing navigation. Use
the `onStepInvalid` prop to handle invalid step transitions.
```tsx
"use client"
import { Box, Button, ButtonGroup, Input, Steps, Text } from "@chakra-ui/react"
import { useState } from "react"
export const StepsWithValidation = () => {
const [formData, setFormData] = useState({
name: "",
email: "",
password: "",
})
const [error, setError] = useState(null)
return (
stepsData[index]?.validate(formData) ?? true}
onStepInvalid={(details) => {
setError(`Step ${details.step + 1} is invalid`)
}}
>
{stepsData.map((step, index) => (
{step.title}
{step.description}
))}
{stepsData.map((step, index) => (
{step.render({ formData, setFormData, setError })}
{error && (
{error}
)}
))}
Registration complete!
Back
Next
)
}
interface FormData {
name: string
email: string
password: string
}
interface StepRenderContext {
formData: FormData
setFormData: (data: FormData) => void
setError: (error: string | null) => void
}
interface StepData {
title: string
description: string
validate: (data: FormData) => boolean
render(ctx: StepRenderContext): React.ReactNode
}
const stepsData: StepData[] = [
{
title: "Name",
description: "Enter your name",
validate(data) {
return data.name.trim().length > 0
},
render(ctx) {
return (
current step: {steps.value}
{items.map((step, index) => (
{step.title}
))}
{items.map((step, index) => (
{step.description}
))}
All steps are complete!
Prev
Next
)
}
const items = [
{
title: "Step 1",
description: "Step 1 description",
},
{
title: "Step 2",
description: "Step 2 description",
},
{
title: "Step 3",
description: "Step 3 description",
},
]
```
### Icon
Pass the `icon` prop to the `StepsItem` component to display an icon.
```tsx
import { Button, ButtonGroup, Steps } from "@chakra-ui/react"
import { LuCalendar, LuCheck, LuUser, LuWallet } from "react-icons/lu"
export const StepsWithIcon = () => {
return (
{steps.map((step, index) => (
))}
{steps.map((step, index) => (
{step.description}
))}
All steps are complete!
Prev
Next
)
}
const steps = [
{
icon:
{steps.map((step, index) => (
{step.title}
{step.description}
))}
{steps.map((step, index) => (
{step.content}
))}
All steps are complete!
Prev
Next
)
}
const steps = [
{
title: "Step 1",
content: "Step 1 content",
description: "This step",
},
{
title: "Step 2",
content: "Step 2 content",
description: "That step",
},
{
title: "Step 3",
content: "Step 3 content",
description: "Final step",
},
]
```
## Props
### Root
| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| isStepSkippable | () => false | `(index: number) => boolean` | Whether a step can be skipped during navigation.
Skippable steps are bypassed when using next/prev. |
| isStepValid | () => true | `(index: number) => boolean` | Whether a step is valid. Invalid steps block forward navigation in linear mode. |
| orientation | horizontal | `'vertical' \| 'horizontal'` | The orientation of the component |
| colorPalette | gray | `'gray' \| 'red' \| 'orange' \| 'yellow' \| 'green' \| 'teal' \| 'blue' \| 'cyan' \| 'purple' \| 'pink'` | The color palette of the component |
| variant | solid | `'solid' \| 'subtle'` | The variant of the component |
| size | md | `'xs' \| 'sm' \| 'md' \| 'lg'` | The size of the component |
| as | undefined | `React.ElementType` | The underlying element to render. |
| asChild | undefined | `boolean` | Use the provided child element as the default rendered element, combining their props and behavior. |
| unstyled | undefined | `boolean` | Whether to remove the component's style. |
| count | undefined | `number` | The total number of steps |
| defaultStep | undefined | `number` | The initial value of the stepper when rendered.
Use when you don't need to control the value of the stepper. |
| ids | undefined | `ElementIds` | The custom ids for the stepper elements |
| linear | undefined | `boolean` | If `true`, the stepper requires the user to complete the steps in order |
| onStepChange | undefined | `(details: StepChangeDetails) => void` | Callback to be called when the value changes |
| onStepComplete | undefined | `VoidFunction` | Callback to be called when a step is completed |
| onStepInvalid | undefined | `(details: StepInvalidDetails) => void` | Called when navigation is blocked due to an invalid step. |
| step | undefined | `number` | The controlled value of the stepper |
## Explorer
Explore the `Steps` component parts interactively. Click on parts in the sidebar
to highlight them in the preview.
Activate Chakra
)
}
```
## Usage
```tsx
import { Switch } from "@chakra-ui/react"
```
```tsx
```
:::info
If you prefer a closed component composition, check out the
[snippet below](#closed-component).
:::
## Shortcuts
The `Switch` component also provides a set of shortcuts for common use cases.
### SwitchControl
The `Switch.Control` renders the `Switch.Thumb` within it by default.
This works:
```tsx
```
This might be more concise, if you don't need to customize the thumb:
```tsx
{(size) => (
)}
)
}
```
### Variants
Pass the `variant` prop to the `Switch.Root` component to change the visual
style of the switch.
```tsx
import { For, HStack, Switch } from "@chakra-ui/react"
export const SwitchWithVariants = () => {
return (
{(variant) => (
)}
)
}
```
### Colors
Pass the `colorPalette` prop to the `Switch.Root` component to change the color
scheme of the component.
```tsx
import { Stack, Switch, Text } from "@chakra-ui/react"
export const SwitchWithColors = () => {
return (
{["gray","red","green","blue","teal","pink","purple","cyan","orange","yellow"].map((colorPalette) => (
{colorPalette}
))}
)
}
```
### Controlled
Use the `checked` and `onCheckedChange` prop to control the state of the switch.
```tsx
"use client"
import { Switch } from "@chakra-ui/react"
import { useState } from "react"
export const SwitchControlled = () => {
const [checked, setChecked] = useState(false)
return (
setChecked(e.checked)}
>
)
}
```
### Hook Form
Here's an example of integrating the switch with `react-hook-form`.
```tsx
"use client"
import { Button, Field, Stack, Switch } from "@chakra-ui/react"
import { standardSchemaResolver } from "@hookform/resolvers/standard-schema"
import { Controller, useForm } from "react-hook-form"
import { z } from "zod"
const formSchema = z.object({
active: z.boolean({ message: "Active is required" }),
})
type FormData = z.infer
export const SwitchWithHookForm = () => {
const {
handleSubmit,
control,
formState: { errors },
} = useForm({
resolver: standardSchemaResolver(formSchema),
})
return (
)
}
```
### Disabled
Pass the `disabled` prop to the `Switch.Root` component to disable the switch.
```tsx
import { Switch } from "@chakra-ui/react"
export const SwitchWithDisabled = () => {
return (
Activate Chakra
)
}
```
### Invalid
Pass the `invalid` prop to the `Switch.Root` component to indicate an error
state for the switch.
```tsx
import { Switch } from "@chakra-ui/react"
export const SwitchWithInvalid = () => {
return (
Activate Chakra
)
}
```
### Tooltip
Here's an example of how to compose a switch with a tooltip.
```tsx
import { Switch } from "@chakra-ui/react"
import { Tooltip } from "@/components/ui/tooltip"
import { useId } from "react"
export const SwitchWithTooltip = () => {
const id = useId()
return (
Switch with tooltip
)
}
```
### Track Indicator
Use the `Switch.Indicator` component to display different indicators based on
the checked state.
```tsx
"use client"
import { Icon, Switch } from "@chakra-ui/react"
import { FaMoon, FaSun } from "react-icons/fa"
export const SwitchWithTrackIndicator = () => {
return (
Switch me
)
}
```
### Thumb Indicator
Use the `Switch.ThumbIndicator` component to add an icon to the switch thumb.
```tsx
import { Switch } from "@chakra-ui/react"
import { HiCheck, HiX } from "react-icons/hi"
export const SwitchWithThumbIndicator = () => {
return (
Switch me
)
}
```
### Closed Component
Here's how to setup the Switch for a closed component composition.
Activate Chakra
```
## Props
### Root
| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| value | on | `string \| number` | The value of switch input. Useful for form submission. |
| colorPalette | gray | `'gray' \| 'red' \| 'orange' \| 'yellow' \| 'green' \| 'teal' \| 'blue' \| 'cyan' \| 'purple' \| 'pink'` | The color palette of the component |
| variant | solid | `'solid' \| 'raised'` | The variant of the component |
| size | md | `'xs' \| 'sm' \| 'md' \| 'lg'` | The size of the component |
| as | undefined | `React.ElementType` | The underlying element to render. |
| asChild | undefined | `boolean` | Use the provided child element as the default rendered element, combining their props and behavior. |
| unstyled | undefined | `boolean` | Whether to remove the component's style. |
| checked | undefined | `boolean` | The controlled checked state of the switch |
| disabled | undefined | `boolean` | Whether the switch is disabled. |
| ids | undefined | `Partial<{ root: string; hiddenInput: string; control: string; label: string; thumb: string }>` | The ids of the elements in the switch. Useful for composition. |
| invalid | undefined | `boolean` | If `true`, the switch is marked as invalid. |
| label | undefined | `string` | Specifies the localized strings that identifies the accessibility elements and their states |
| name | undefined | `string` | The name of the input field in a switch
(Useful for form submission). |
| onCheckedChange | undefined | `(details: CheckedChangeDetails) => void` | Function to call when the switch is clicked. |
| readOnly | undefined | `boolean` | Whether the switch is read-only |
| required | undefined | `boolean` | If `true`, the switch input is marked as required, |
## Explorer
Explore the `Switch` component parts interactively. Click on parts in the
sidebar to highlight them in the preview.
Product
Category
Price
{items.map((item) => (
{item.name}
{item.category}
{item.price}
))}
)
}
const items = [
{ id: 1, name: "Laptop", category: "Electronics", price: 999.99 },
{ id: 2, name: "Coffee Maker", category: "Home Appliances", price: 49.99 },
{ id: 3, name: "Desk Chair", category: "Furniture", price: 150.0 },
{ id: 4, name: "Smartphone", category: "Electronics", price: 799.99 },
{ id: 5, name: "Headphones", category: "Accessories", price: 199.99 },
]
```
## Usage
```jsx
import { Table } from "@chakra-ui/react"
```
```jsx
```
## Examples
### Sizes
Use the `size` prop to change the size of the table.
```tsx
import { For, Stack, Table } from "@chakra-ui/react"
export const TableWithSizes = () => {
return (
{(size) => (
Product
Category
Price
{items.map((item) => (
{item.name}
{item.category}
{item.price}
))}
)}
)
}
const items = [
{ id: 1, name: "Laptop", category: "Electronics", price: 999.99 },
{ id: 2, name: "Coffee Maker", category: "Home Appliances", price: 49.99 },
{ id: 3, name: "Desk Chair", category: "Furniture", price: 150.0 },
{ id: 4, name: "Smartphone", category: "Electronics", price: 799.99 },
{ id: 5, name: "Headphones", category: "Accessories", price: 199.99 },
]
```
### Variants
Use the `variant` prop to change the appearance of the table.
```tsx
import { For, Stack, Table } from "@chakra-ui/react"
export const TableWithVariants = () => {
return (
{(variant) => (
Product
Category
Price
{items.map((item) => (
{item.name}
{item.category}
{item.price}
))}
)}
)
}
const items = [
{ id: 1, name: "Laptop", category: "Electronics", price: 999.99 },
{ id: 2, name: "Coffee Maker", category: "Home Appliances", price: 49.99 },
{ id: 3, name: "Desk Chair", category: "Furniture", price: 150.0 },
{ id: 4, name: "Smartphone", category: "Electronics", price: 799.99 },
{ id: 5, name: "Headphones", category: "Accessories", price: 199.99 },
]
```
### Striped
Use the `striped` prop to add zebra-stripes to the table.
```tsx
import { Table } from "@chakra-ui/react"
export const TableWithStriped = () => {
return (
Product
Category
Price
{items.map((item) => (
{item.name}
{item.category}
{item.price}
))}
)
}
const items = [
{ id: 1, name: "Laptop", category: "Electronics", price: 999.99 },
{ id: 2, name: "Coffee Maker", category: "Home Appliances", price: 49.99 },
{ id: 3, name: "Desk Chair", category: "Furniture", price: 150.0 },
{ id: 4, name: "Smartphone", category: "Electronics", price: 799.99 },
{ id: 5, name: "Headphones", category: "Accessories", price: 199.99 },
]
```
### Caption
Use the `Table.Caption` component to add a caption to the table.
```tsx
import { Table } from "@chakra-ui/react"
export const TableWithCaption = () => {
return (
Product inventory and pricing information
Product
Category
Price
{items.map((item) => (
{item.name}
{item.category}
{item.price}
))}
)
}
const items = [
{ id: 1, name: "Laptop", category: "Electronics", price: 999.99 },
{ id: 2, name: "Coffee Maker", category: "Home Appliances", price: 49.99 },
{ id: 3, name: "Desk Chair", category: "Furniture", price: 150.0 },
{ id: 4, name: "Smartphone", category: "Electronics", price: 799.99 },
{ id: 5, name: "Headphones", category: "Accessories", price: 199.99 },
]
```
### Caption Top
Use the `side` prop on `Table.Caption` to position the caption at the top of the
table.
```tsx
import { Table } from "@chakra-ui/react"
export const TableWithCaptionTop = () => {
return (
Product inventory and pricing information
Product
Category
Price
{items.map((item) => (
{item.name}
{item.category}
{item.price}
))}
)
}
const items = [
{ id: 1, name: "Laptop", category: "Electronics", price: 999.99 },
{ id: 2, name: "Coffee Maker", category: "Home Appliances", price: 49.99 },
{ id: 3, name: "Desk Chair", category: "Furniture", price: 150.0 },
{ id: 4, name: "Smartphone", category: "Electronics", price: 799.99 },
{ id: 5, name: "Headphones", category: "Accessories", price: 199.99 },
]
```
### Column Border
Use the `showColumnBorder` prop to add borders between columns.
```tsx
import { Table } from "@chakra-ui/react"
export const TableWithColumnBorder = () => {
return (
Product
Category
Price
{items.map((item) => (
{item.name}
{item.category}
{item.price}
))}
)
}
const items = [
{ id: 1, name: "Laptop", category: "Electronics", price: 999.99 },
{ id: 2, name: "Coffee Maker", category: "Home Appliances", price: 49.99 },
{ id: 3, name: "Desk Chair", category: "Furniture", price: 150.0 },
{ id: 4, name: "Smartphone", category: "Electronics", price: 799.99 },
{ id: 5, name: "Headphones", category: "Accessories", price: 199.99 },
]
```
### Overflow
Render the `Table.ScrollArea` component to enable horizontal scrolling.
```tsx
import { Table } from "@chakra-ui/react"
export const TableWithOverflow = () => {
return (
Product
Category
Price
{items.map((item) => (
{item.name}
{item.category}
{item.price}
))}
)
}
const items = [
{ id: 1, name: "Laptop", category: "Electronics", price: 999.99 },
{ id: 2, name: "Coffee Maker", category: "Home Appliances", price: 49.99 },
{ id: 3, name: "Desk Chair", category: "Furniture", price: 150.0 },
{ id: 4, name: "Smartphone", category: "Electronics", price: 799.99 },
{ id: 5, name: "Headphones", category: "Accessories", price: 199.99 },
]
```
### Sticky Header
Use the `stickyHeader` prop to make the table header sticky.
```tsx
import { Table } from "@chakra-ui/react"
export const TableWithStickyHeader = () => {
return (
Product
Category
Price
{items.map((item) => (
{item.name}
{item.category}
{item.price}
))}
)
}
const items = [
{ id: 1, name: "Laptop", category: "Electronics", price: 999.99 },
{ id: 2, name: "Coffee Maker", category: "Home Appliances", price: 49.99 },
{ id: 3, name: "Desk Chair", category: "Furniture", price: 150.0 },
{ id: 4, name: "Smartphone", category: "Electronics", price: 799.99 },
{ id: 5, name: "Headphones", category: "Accessories", price: 199.99 },
]
```
### Sticky Column
Here's an example what uses `data-sticky` attributes to make table columns
sticky during horizontal scrolling.
```tsx
import { Table } from "@chakra-ui/react"
export const TableWithStickyColumn = () => {
return (
Product
Category
Price
{items.map((item) => (
{item.name}
{item.category}
{item.price}
))}
)
}
const items = [
{ id: 1, name: "Laptop", category: "Electronics", price: 999.99 },
{ id: 2, name: "Coffee Maker", category: "Home Appliances", price: 49.99 },
{ id: 3, name: "Desk Chair", category: "Furniture", price: 150.0 },
{ id: 4, name: "Smartphone", category: "Electronics", price: 799.99 },
{ id: 5, name: "Headphones", category: "Accessories", price: 199.99 },
]
```
### Sticky Header and Column
Combine `stickyHeader` with `data-sticky` attributes to create a table with both
a sticky header and sticky columns. When using both features together, ensure
the header row has a higher z-index to keep sticky column headers visible.
```tsx
import { Table } from "@chakra-ui/react"
export const TableWithStickyHeaderAndColumn = () => {
return (
Product
Category
Price
{items.map((item) => (
{item.name}
{item.category}
{item.price}
))}
)
}
const items = [
{ id: 1, name: "Headphones", category: "Electronics", price: 834.12 },
{ id: 2, name: "Desk Chair", category: "Furniture", price: 245.88 },
{ id: 3, name: "Microwave", category: "Home Appliances", price: 379.26 },
{ id: 4, name: "Backpack", category: "Accessories", price: 112.47 },
{ id: 5, name: "Football", category: "Sports", price: 95.14 },
{ id: 6, name: "Smartphone", category: "Electronics", price: 921.63 },
{ id: 7, name: "Wrist Watch", category: "Accessories", price: 418.52 },
{ id: 8, name: "T-Shirt", category: "Clothing", price: 35.29 },
{ id: 9, name: "Vacuum Cleaner", category: "Home Appliances", price: 601.22 },
{ id: 10, name: "Lamp", category: "Furniture", price: 157.88 },
{ id: 11, name: "Drone", category: "Electronics", price: 836.15 },
{ id: 12, name: "Perfume", category: "Beauty", price: 128.9 },
{ id: 13, name: "Camping Tent", category: "Outdoors", price: 458.4 },
{ id: 14, name: "Cookware Set", category: "Home Appliances", price: 292.86 },
{ id: 15, name: "Camera", category: "Electronics", price: 792.54 },
{ id: 16, name: "Sneakers", category: "Clothing", price: 154.61 },
{ id: 17, name: "Monitor", category: "Electronics", price: 348.57 },
{ id: 18, name: "Gaming Console", category: "Electronics", price: 896.01 },
{ id: 19, name: "Keyboard", category: "Electronics", price: 94.71 },
{ id: 20, name: "Sofa", category: "Furniture", price: 719.33 },
{ id: 21, name: "Tablet", category: "Electronics", price: 612.57 },
{ id: 22, name: "Action Figure", category: "Toys", price: 73.49 },
{ id: 23, name: "Smartwatch", category: "Electronics", price: 482.46 },
{ id: 24, name: "Tent", category: "Outdoors", price: 623.3 },
{ id: 25, name: "Cookware Set", category: "Home Appliances", price: 257.38 },
{ id: 26, name: "Helmet", category: "Sports", price: 88.26 },
{ id: 27, name: "Hair Dryer", category: "Beauty", price: 164.79 },
{ id: 28, name: "Lamp", category: "Furniture", price: 122.1 },
{
id: 29,
name: "Electric Kettle",
category: "Home Appliances",
price: 69.42,
},
{ id: 30, name: "Sneakers", category: "Clothing", price: 182.13 },
{ id: 31, name: "Drone", category: "Electronics", price: 934.72 },
{ id: 32, name: "Coffee Maker", category: "Home Appliances", price: 148.99 },
{ id: 33, name: "Backpack", category: "Accessories", price: 81.22 },
{ id: 34, name: "Microwave", category: "Home Appliances", price: 399.53 },
{ id: 35, name: "T-Shirt", category: "Clothing", price: 45.33 },
{
id: 36,
name: "Vacuum Cleaner",
category: "Home Appliances",
price: 552.87,
},
]
```
### Highlight on Hover
Use the `interactive` prop to highlight rows on hover.
```tsx
import { Table } from "@chakra-ui/react"
export const TableWithInteractive = () => {
return (
Product
Category
Price
{items.map((item) => (
{item.name}
{item.category}
{item.price}
))}
)
}
const items = [
{ id: 1, name: "Laptop", category: "Electronics", price: 999.99 },
{ id: 2, name: "Coffee Maker", category: "Home Appliances", price: 49.99 },
{ id: 3, name: "Desk Chair", category: "Furniture", price: 150.0 },
{ id: 4, name: "Smartphone", category: "Electronics", price: 799.99 },
{ id: 5, name: "Headphones", category: "Accessories", price: 199.99 },
]
```
### Pagination
Here's an example of how to compose a table with pagination.
```tsx
"use client"
import {
ButtonGroup,
Heading,
IconButton,
Pagination,
Stack,
Table,
} from "@chakra-ui/react"
import { LuChevronLeft, LuChevronRight } from "react-icons/lu"
export const TableWithPagination = () => {
return (
Products
Product
Category
Price
{items.map((item) => (
{item.name}
{item.category}
{item.price}
))}
(
{page.value}
)}
/>
)
}
const items = [
{ id: 1, name: "Laptop", category: "Electronics", price: 999.99 },
{ id: 2, name: "Coffee Maker", category: "Home Appliances", price: 49.99 },
{ id: 3, name: "Desk Chair", category: "Furniture", price: 150.0 },
{ id: 4, name: "Smartphone", category: "Electronics", price: 799.99 },
{ id: 5, name: "Headphones", category: "Accessories", price: 199.99 },
]
```
### Selection
Here's an example of how to add row selection with checkboxes to your table.
```tsx
"use client"
import { Checkbox, Table } from "@chakra-ui/react"
import { useState } from "react"
export const TableWithSelection = () => {
const [selection, setSelection] = useState([])
const indeterminate = selection.length > 0 && selection.length < items.length
const rows = items.map((item) => (
{
setSelection((prev) =>
changes.checked
? [...prev, item.name]
: selection.filter((name) => name !== item.name),
)
}}
>
{item.name}
{item.category}
${item.price}
))
return (
0}
onCheckedChange={(changes) => {
setSelection(
changes.checked ? items.map((item) => item.name) : [],
)
}}
>
Product
Category
Price
{rows}
)
}
const items = [
{ id: 1, name: "Laptop", category: "Electronics", price: 999.99 },
{ id: 2, name: "Coffee Maker", category: "Home Appliances", price: 49.99 },
{ id: 3, name: "Desk Chair", category: "Furniture", price: 150.0 },
{ id: 4, name: "Smartphone", category: "Electronics", price: 799.99 },
{ id: 5, name: "Headphones", category: "Accessories", price: 199.99 },
]
```
### Action Bar
Here's an example of how to compose a table with an action bar and checkboxes.
This is useful for showing actions for selected table rows.
```tsx
"use client"
import {
ActionBar,
Button,
Checkbox,
Kbd,
Portal,
Table,
} from "@chakra-ui/react"
import { useState } from "react"
export const TableWithSelectionActionBar = () => {
const [selection, setSelection] = useState([])
const hasSelection = selection.length > 0
const indeterminate = hasSelection && selection.length < items.length
const rows = items.map((item) => (
{
setSelection((prev) =>
changes.checked
? [...prev, item.name]
: selection.filter((name) => name !== item.name),
)
}}
>
{item.name}
{item.category}
${item.price}
))
return (
<>
0}
onCheckedChange={(changes) => {
setSelection(
changes.checked ? items.map((item) => item.name) : [],
)
}}
>
Product
Category
Price
{rows}
{selection.length} selected
Delete ⌫
Share T
)
}
const items = [
{ id: 1, name: "Laptop", category: "Electronics", price: 999.99 },
{ id: 2, name: "Coffee Maker", category: "Home Appliances", price: 49.99 },
{ id: 3, name: "Desk Chair", category: "Furniture", price: 150.0 },
{ id: 4, name: "Smartphone", category: "Electronics", price: 799.99 },
{ id: 5, name: "Headphones", category: "Accessories", price: 199.99 },
]
```
### Column Group
Use the `Table.ColumnGroup` component to distribute the column widths using the
html `colgroup` element.
:::warning
The only prop that works for this component is `htmlWidth`
:::
```tsx
import { Table } from "@chakra-ui/react"
export const TableWithColumnGroup = () => {
return (
Product
Category
Price
{items.map((item) => (
{item.name}
{item.category}
{item.price}
))}
)
}
const items = [
{ id: 1, name: "Laptop", category: "Electronics", price: 999.99 },
{ id: 2, name: "Coffee Maker", category: "Home Appliances", price: 49.99 },
{ id: 3, name: "Desk Chair", category: "Furniture", price: 150.0 },
{ id: 4, name: "Smartphone", category: "Electronics", price: 799.99 },
{ id: 5, name: "Headphones", category: "Accessories", price: 199.99 },
]
```
### Native Mode
Use the `native` prop to render table descendants using native HTML elements
(``, ` `, ``, ``, ` `) instead of Chakra's styled
components.
> This is a great way to improve performance for large tables by eliminating the
> runtime styling and React Context overhead.
```tsx
import { Table } from "@chakra-ui/react"
export const TableWithNative = () => {
return (
Product
Category
Price
{items.map((item) => (
{item.name}
{item.category}
{item.price}
))}
)
}
const items = [
{ id: 1, name: "Laptop", category: "Electronics", price: "$999.00" },
{ id: 2, name: "Coffee Maker", category: "Home Appliances", price: "$49.99" },
{ id: 3, name: "Desk Chair", category: "Furniture", price: "$150.00" },
{ id: 4, name: "Smartphone", category: "Electronics", price: "$799.99" },
{ id: 5, name: "Headphones", category: "Accessories", price: "$199.99" },
]
```
### TanStack Table
Chakra UI works seamlessly with
[TanStack Table](https://tanstack.com/table/latest) for advanced table features.
```tsx
"use client"
import { Table } from "@chakra-ui/react"
import {
createColumnHelper,
flexRender,
getCoreRowModel,
getPaginationRowModel,
getSortedRowModel,
useReactTable,
} from "@tanstack/react-table"
type Product = {
id: number
name: string
category: string
price: number
stock: number
}
const columnHelper = createColumnHelper()
const columns = [
columnHelper.accessor("name", {
header: "Product",
cell: (info) => info.getValue(),
}),
columnHelper.accessor("category", {
header: "Category",
cell: (info) => info.getValue(),
}),
columnHelper.accessor("price", {
header: "Price",
cell: (info) => `${info.getValue().toFixed(2)}`,
}),
columnHelper.accessor("stock", {
header: "Stock",
cell: (info) => info.getValue(),
}),
]
export const TableWithTanstack = () => {
const table = useReactTable({
data,
columns,
getCoreRowModel: getCoreRowModel(),
getSortedRowModel: getSortedRowModel(),
getPaginationRowModel: getPaginationRowModel(),
})
return (
{table.getHeaderGroups().map((headerGroup) => (
{headerGroup.headers.map((header) => (
{header.isPlaceholder
? null
: flexRender(
header.column.columnDef.header,
header.getContext(),
)}
))}
))}
{table.getRowModel().rows.map((row) => (
{row.getVisibleCells().map((cell) => (
{flexRender(cell.column.columnDef.cell, cell.getContext())}
))}
))}
)
}
const data: Product[] = [
{ id: 1, name: "Laptop", category: "Electronics", price: 999.99, stock: 50 },
{
id: 2,
name: "Coffee Maker",
category: "Home Appliances",
price: 49.99,
stock: 120,
},
{
id: 3,
name: "Desk Chair",
category: "Furniture",
price: 150.0,
stock: 30,
},
{
id: 4,
name: "Smartphone",
category: "Electronics",
price: 799.99,
stock: 75,
},
{
id: 5,
name: "Headphones",
category: "Accessories",
price: 199.99,
stock: 200,
},
]
```
## Props
### Root
| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| colorPalette | gray | `'gray' \| 'red' \| 'orange' \| 'yellow' \| 'green' \| 'teal' \| 'blue' \| 'cyan' \| 'purple' \| 'pink'` | The color palette of the component |
| variant | line | `'line' \| 'outline'` | The variant of the component |
| size | md | `'sm' \| 'md' \| 'lg'` | The size of the component |
| native | undefined | `boolean \| undefined` | If `true`, the table will style its descendants with nested selectors |
| as | undefined | `React.ElementType` | The underlying element to render. |
| asChild | undefined | `boolean` | Use the provided child element as the default rendered element, combining their props and behavior. |
| unstyled | undefined | `boolean` | Whether to remove the component's style. |
| interactive | undefined | `'true' \| 'false'` | The interactive of the component |
| stickyHeader | undefined | `'true' \| 'false'` | The stickyHeader of the component |
| striped | undefined | `'true' \| 'false'` | The striped of the component |
| showColumnBorder | undefined | `'true' \| 'false'` | The showColumnBorder of the component |
## Explorer
Explore the `Table` component parts interactively. Click on parts in the sidebar
to highlight them in the preview.
Manage your team members
Manage your projects
Manage your tasks for freelancers
)
}
```
## Usage
```jsx
import { Tabs } from "@chakra-ui/react"
```
```jsx
```
## Examples
### Variants
Use the `variant` prop to change the visual style of the tabs.
```tsx
import { For, SimpleGrid, Tabs } from "@chakra-ui/react"
import { LuFolder, LuSquareCheck, LuUser } from "react-icons/lu"
export const TabsWithVariants = () => {
return (
{(variant) => (
Manage your team members
Manage your projects
Manage your tasks for freelancers
)}
)
}
```
### Lazy Mounted
Use the `lazyMount` and/or `unmountOnExit` prop to only render the tab content
when it is active. This can be useful for performance optimization.
```tsx
"use client"
import { Tabs } from "@chakra-ui/react"
import { useEffect, useState } from "react"
export const TabsLazyMounted = () => {
return (
Tab 1
Tab 2
Tab 3
Tab 1: Content
Tab 2: Content
Tab 3: Content
)
}
const TickValue = () => {
const [value, setValue] = useState(0)
useEffect(() => {
const intervalId = window.setInterval(() => {
setValue((v) => v + 1)
}, 1000)
return () => {
window.clearInterval(intervalId)
}
}, [])
return (
{value}
)
}
```
### Indicator
Render the `Tabs.Indicator` component to display a visual indicator of the
active tab.
```tsx
import { Tabs } from "@chakra-ui/react"
import { LuFolder, LuSquareCheck, LuUser } from "react-icons/lu"
export const TabsWithIndicator = () => {
return (
Manage your team members
Manage your projects
Manage your tasks for freelancers
)
}
```
### Custom Indicator
Customize the indicator appearance using CSS variables like
`--tabs-indicator-bg` and `--tabs-indicator-shadow`.
```tsx
import { Tabs } from "@chakra-ui/react"
export const TabsWithCustomIndicator = () => {
return (
Members
Projects
Settings
Manage your team members
Manage your projects
Manage your settings
)
}
```
### Links
Pass the `asChild` to the `Tabs.Trigger` component to render a link as a tab.
When a tab is clicked, the link will be navigated to.
```tsx
import { Link, Tabs } from "@chakra-ui/react"
export const TabsWithLinks = () => {
return (
Manage your team members
Manage your projects
)
}
```
When using custom router links, you need to set the `navigate` prop on the
`Tabs.Root` component.
```tsx
"use client"
import { Tabs } from "@chakra-ui/react"
import { useNavigate } from "react-router-dom"
const Demo = () => {
const navigate = useNavigate()
return (
navigate(`/${value}`)}>
{/* ... */}
)
}
```
### Fitted
Use the `fitted` prop to make the tabs fit the width of the container.
```tsx
import { Tabs } from "@chakra-ui/react"
export const TabsWithFitted = () => {
return (
Tab 1
Tab 2
Tab 3
)
}
```
### Controlled
Use the `value` and `onValueChange` prop to control the active tab.
```tsx
"use client"
import { Tabs } from "@chakra-ui/react"
import { useState } from "react"
export const TabsControlled = () => {
const [value, setValue] = useState("first")
return (
setValue(e.value)}>
First tab
Second tab
First panel
Second panel
)
}
```
### Store
An alternative way to control the tabs is to use the `RootProvider` component
and the `useTabs` store hook.
This way you can access the tabs state and methods from outside the tabs.
```tsx
"use client"
import { Code, Stack, Tabs, useTabs } from "@chakra-ui/react"
import { LuFolder, LuSquareCheck, LuUser } from "react-icons/lu"
export const TabsWithStore = () => {
const tabs = useTabs({
defaultValue: "members",
})
return (
selected: {tabs.value}
Manage your team members
Manage your projects
Manage your tasks for freelancers
)
}
```
### Disabled Tab
Set the `disabled` prop on the `Tabs.Trigger` component to disable a tab.
```tsx
import { Tabs } from "@chakra-ui/react"
import { LuFolder, LuSquareCheck, LuUser } from "react-icons/lu"
export const TabsWithDisabledTab = () => {
return (
{/* content */}
)
}
```
### Manual activation
By default, the tabs are selected when the arrow keys are pressed. Disable this
behavior by setting the `activationBehavior` prop to `manual`.
In this mode, the tabs will only be selected when clicked or the enter key is
pressed.
```tsx
import { Tabs } from "@chakra-ui/react"
import { LuFolder, LuSquareCheck, LuUser } from "react-icons/lu"
export const TabsWithManualActivation = () => {
return (
{/* content */}
)
}
```
### Dynamic
Here's an example of how to dynamically add and remove tabs.
```tsx
"use client"
import { Button, CloseButton, Heading, Tabs, Text } from "@chakra-ui/react"
import { useState } from "react"
import { LuPlus } from "react-icons/lu"
interface Item {
id: string
title: string
content: React.ReactNode
}
const items: Item[] = [
{ id: "1", title: "Tab", content: "Tab Content" },
{ id: "2", title: "Tab", content: "Tab Content" },
{ id: "3", title: "Tab", content: "Tab Content" },
{ id: "4", title: "Tab", content: "Tab Content" },
]
const uuid = () => {
return Math.random().toString(36).substring(2, 15)
}
export const TabsWithDynamicAdd = () => {
const [tabs, setTabs] = useState(items)
const [selectedTab, setSelectedTab] = useState(items[0].id)
const addTab = () => {
const newTabs = [...tabs]
const uid = uuid()
newTabs.push({
id: uid,
title: `Tab`,
content: `Tab Body`,
})
setTabs(newTabs)
setSelectedTab(newTabs[newTabs.length - 1].id)
}
const removeTab = (id: string) => {
if (tabs.length > 1) {
const newTabs = [...tabs].filter((tab) => tab.id !== id)
setTabs(newTabs)
}
}
return (
setSelectedTab(e.value)}
>
{tabs.map((item) => (
{item.title}{" "}
{
e.stopPropagation()
removeTab(item.id)
}}
/>
))}
{tabs.map((item) => (
{item.content} {item.id}
Dolore ex esse laboris elit magna esse sunt. Pariatur in veniam
Lorem est occaecat do magna nisi mollit ipsum sit adipisicing
fugiat ex. Pariatur ullamco exercitation ea qui adipisicing. Id
cupidatat aute id ut excepteur exercitation magna pariatur. Mollit
irure irure reprehenderit pariatur eiusmod proident Lorem deserunt
duis cillum mollit.
))}
)
}
```
### Responsive Orientation
Responsive values are not supported for the `orientation` prop because it
affects keyboard navigation and `aria-orientation` behavior, not just styling.
The orientation changes how arrow keys work (horizontal uses left/right,
vertical uses up/down).
To achieve responsive orientation, use the `useBreakpointValue` hook to change
the orientation based on the screen size.
```tsx
"use client"
import { Tabs, useBreakpointValue } from "@chakra-ui/react"
export const TabsWithResponsiveOrientation = () => {
const orientation = useBreakpointValue<"horizontal" | "vertical">({
base: "horizontal",
md: "vertical",
})
return (
Members
Projects
Settings
Manage your team members and their roles here.
Manage your projects and their status here.
Manage your tasks and their progress here.
)
}
```
### Animation
Use the `_open` and `_close` conditional props to animate the tabs.
```tsx
import { Box, Tabs } from "@chakra-ui/react"
const items = [
{
title: "1",
content: "Dolore ex esse laboris elit magna esse sunt",
},
{
title: "2",
content:
"Pariatur in veniam Lorem est occaecat do magna nisi mollit ipsum sit adipisicing fugiat ex.",
},
]
export const TabsWithAnimation = () => {
return (
{items.map((item, index) => (
Tab {item.title}
))}
{items.map((item, index) => (
{item.content}
))}
)
}
```
## Guide
### Styling active tab
Use the `_selected` condition to style the active tab's text and background.
```tsx
Tab
```
## Props
### Root
| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| activationMode | automatic | `'manual' \| 'automatic'` | The activation mode of the tabs. Can be `manual` or `automatic`
- `manual`: Tabs are activated when clicked or press `enter` key.
- `automatic`: Tabs are activated when receiving focus |
| hideMode | 'display-none' | `HideMode` | How to hide content when mounted but not present.
- `'display-none'`: HTML `hidden` attribute. Effects stay alive.
- `'activity'`: React 19 ``. Effects pause. Requires React 19+. |
| loopFocus | true | `boolean` | Whether the keyboard navigation will loop from last tab to first, and vice versa. |
| orientation | horizontal | `'horizontal' \| 'vertical'` | The orientation of the tabs. Can be `horizontal` or `vertical`
- `horizontal`: only left and right arrow key navigation will work.
- `vertical`: only up and down arrow key navigation will work. |
| colorPalette | gray | `'gray' \| 'red' \| 'orange' \| 'yellow' \| 'green' \| 'teal' \| 'blue' \| 'cyan' \| 'purple' \| 'pink'` | The color palette of the component |
| size | md | `'sm' \| 'md' \| 'lg'` | The size of the component |
| variant | line | `'line' \| 'subtle' \| 'enclosed' \| 'outline' \| 'plain'` | The variant of the component |
| as | undefined | `React.ElementType` | The underlying element to render. |
| asChild | undefined | `boolean` | Use the provided child element as the default rendered element, combining their props and behavior. |
| unstyled | undefined | `boolean` | Whether to remove the component's style. |
| composite | undefined | `boolean` | Whether the tab is composite |
| defaultValue | undefined | `string` | The initial selected tab value when rendered.
Use when you don't need to control the selected tab value. |
| deselectable | undefined | `boolean` | Whether the active tab can be deselected when clicking on it. |
| id | undefined | `string` | The unique identifier of the machine. |
| ids | undefined | `Partial<{\n root: string\n trigger: (value: string) => string\n list: string\n content: (value: string) => string\n indicator: string\n}>` | The ids of the elements in the tabs. Useful for composition. |
| lazyMount | false | `boolean` | Whether to enable lazy mounting |
| navigate | undefined | `(details: NavigateDetails) => void` | Function to navigate to the selected tab when clicking on it.
Useful if tab triggers are anchor elements. |
| onFocusChange | undefined | `(details: FocusChangeDetails) => void` | Callback to be called when the focused tab changes |
| onValueChange | undefined | `(details: ValueChangeDetails) => void` | Callback to be called when the selected/active tab changes |
| translations | undefined | `IntlTranslations` | Specifies the localized strings that identifies the accessibility elements and their states |
| unmountOnExit | false | `boolean` | Whether to unmount on exit. |
| value | undefined | `string` | The controlled selected tab value |
| fitted | undefined | `'true' \| 'false'` | The fitted of the component |
| justify | undefined | `'start' \| 'center' \| 'end'` | The justify of the component |
### Trigger
| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| as | undefined | `React.ElementType` | The underlying element to render. |
| asChild | undefined | `boolean` | Use the provided child element as the default rendered element, combining their props and behavior. |
### Content
| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| as | undefined | `React.ElementType` | The underlying element to render. |
| asChild | undefined | `boolean` | Use the provided child element as the default rendered element, combining their props and behavior. |
## Explorer
Explore the `Tabs` component parts interactively. Click on parts in the sidebar
to highlight them in the preview.
Plain Tag
Closable Tag
)
}
```
## Usage
```tsx
import { Tag } from "@chakra-ui/react"
```
```tsx
Tag here
```
:::info
If you prefer a closed component composition, check out the
[snippet below](#closed-component).
:::
## Examples
### Icon
Use the `Tag.StartElement` and `Tag.EndElement` components to add an icon to the
start or end of the tag
```tsx
import { HStack, Tag } from "@chakra-ui/react"
import { LuCircleUser, LuFileBadge } from "react-icons/lu"
export const TagWithIcon = () => {
return (
Tag 1
Top Rated
Tag 2
)
}
```
### Variants
Use the `variant` prop to change the appearance of the tag.
```tsx
import { For, HStack, Stack, Tag } from "@chakra-ui/react"
import { HiCheck } from "react-icons/hi"
export const TagWithVariants = () => {
return (
{(variant) => (
Gray
Gray
Gray
)}
)
}
```
### Sizes
Use the `size` prop to change the size of the tag.
```tsx
import { For, HStack, Stack, Tag } from "@chakra-ui/react"
import { HiCheck } from "react-icons/hi"
export const TagWithSizes = () => {
return (
{(size) => (
Gray
Gray
Gray
)}
)
}
```
### Colors
Use the `colorPalette` prop to change the color of the tag.
```tsx
import { Stack, Tag, Text } from "@chakra-ui/react"
import { HiPlus } from "react-icons/hi"
export const TagWithColors = () => {
return (
{["gray","red","green","blue","teal","pink","purple","cyan","orange","yellow"].map((colorPalette) => (
{colorPalette}
Content
Content
Content
))}
)
}
```
### Closable
Use the `Tag.CloseTrigger` within the `Tag.EndElement` to make the tag closable.
```tsx
import { HStack, Tag } from "@chakra-ui/react"
import { LuActivity } from "react-icons/lu"
export const TagWithClose = () => {
return (
Tag 1
Tag 2
)
}
```
### Overflow
Use the `maxWidth` prop to control the maximum width of the tag. When the
content exceeds this width, it will be truncated with an ellipsis.
> This is particularly useful when dealing with dynamic or user-generated
> content where the length might vary.
```tsx
import { Tag } from "@chakra-ui/react"
export const TagWithOverflow = () => {
return (
Lorem ipsum dolor sit amet consectetur adipisicing elit. Quisquam
molestias, laboriosam, quod, quia quidem quae voluptatem natus
exercitationem autem quibusdam
)
}
```
### Avatar
The tag component has been designed to work well with the `Avatar` component.
> Note: Set the avatar size to `full` to ensure it's sized correctly.
```tsx
import { Avatar, For, HStack, Tag } from "@chakra-ui/react"
export const TagWithAvatar = () => {
return (
{(size) => (
Emily {size}
)}
)
}
```
### Render as button
Use the `asChild` prop to render the tag as a button.
```tsx
import { Tag } from "@chakra-ui/react"
import { LuCheck } from "react-icons/lu"
export const TagAsButton = () => {
return (
Fish
)
}
```
### Closed Component
Here's how to setup the Tag for a closed component composition.
Tags
Press Enter or Return to add tag
)
}
```
## Usage
```jsx
import { TagsInput } from "@chakra-ui/react"
```
```jsx
```
## Shortcuts
The `TagsInput` component also provides a set of shortcuts for common use cases.
### TagsInputItems
The `TagsInputItems` shortcut renders all tag items automatically based on the
current value.
This works:
```jsx
{({ value }) =>
value.map((tag, index) => (
{tag}
))
}
```
This might be more concise, if you don't need to customize the items:
```jsx
{(size) => (
Tags (size={size})
Press Enter or Return to add tag
)}
)
}
```
### Variants
Use the `variant` prop to change the visual style of the tags input.
```tsx
"use client"
import { For, Span, Stack, TagsInput } from "@chakra-ui/react"
export const TagsInputWithVariants = () => {
return (
{(variant) => (
Tags (variant={variant})
Press Enter or Return to add tag
)}
)
}
```
### Controlled
Use the `value` and `onValueChange` props to programmatically control the tags.
```tsx
"use client"
import { TagsInput } from "@chakra-ui/react"
import { useState } from "react"
export const TagsInputControlled = () => {
const [tags, setTags] = useState(["React", "Chakra"])
return (
setTags(details.value)}
>
Tags
)
}
```
### Store
An alternative way to control the tags input is to use the `RootProvider`
component and the `useTagsInput` store hook.
This way you can access the tags input state and methods from outside the
component.
> Use `RootProvider + useTagsInput` or `Root`, not both.
```tsx
"use client"
import { Button, Stack, TagsInput } from "@chakra-ui/react"
import { useTagsInput } from "@chakra-ui/react"
export const TagsInputWithStore = () => {
const tags = useTagsInput()
return (
Tags: {JSON.stringify(tags.value)}
tags.clearValue()}>
Clear All
)
}
```
### Max Tags
Pass the `max` prop to the `TagsInput.Root` component to limit the number of
tags that can be added.
```tsx
"use client"
import { Badge, Button, HStack, Span, TagsInput } from "@chakra-ui/react"
const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
const isValidEmail = (value: string) => EMAIL_REGEX.test(value)
export const TagsInputWithMax = () => {
return (
isValidEmail(e.inputValue)}
defaultValue={["sage@company.com"]}
>
Invite guests (max 3)
{({ value }) => (
You've invited {value.length} / 3 guests to your
event
Invite
)}
)
}
```
### Editable Tags
Use the `editable` prop to enable inline editing of existing tags by double
clicking or pressing `Enter` when highlighted, allowing users to quickly update
tag values.
```tsx
"use client"
import { Span, TagsInput } from "@chakra-ui/react"
export const TagsInputEditable = () => (
Edit Tags Inline
Use the arrow keys to navigate and press Enter to edit
)
```
### Validate Tag
Use the `validate` prop to implement custom validation rules. Tags will be added
when the validation passes.
```tsx
"use client"
import { TagsInput } from "@chakra-ui/react"
export const TagsInputValidation = () => (
e.inputValue.length >= 3}
>
Tags (min 3 chars)
)
```
### Disabled
Use the `disabled` prop to disable the tags input to prevent user interaction.
```tsx
"use client"
import { TagsInput } from "@chakra-ui/react"
export const TagsInputDisabled = () => (
Disabled Tags
)
```
### Readonly
Use the `readOnly` prop to make the tags input read-only. Tags input can be
focused but can't be modified.
```tsx
"use client"
import { TagsInput } from "@chakra-ui/react"
export const TagsInputReadOnly = () => (
Read Only Tags
)
```
### Invalid
Pass the `invalid` prop to the `TagsInput.Root` component to display the tags
input in an invalid state with error messages.
```tsx
"use client"
import { Field, TagsInput } from "@chakra-ui/react"
export const TagsInputInvalid = () => (
Invalid Tags
This is an error
)
```
### Field
Here's an example that composes the `TagsInput.Root` with the `Field` component
to add labels, helper text, and error messages.
```tsx
"use client"
import { Field, TagsInput } from "@chakra-ui/react"
export const TagsInputWithField = () => {
return (
Enter tags
Add emails separated by commas
)
}
```
### Form
Here's an example that composes the `TagsInput.Root` with a `form` to collect
structured data and handle submissions.
```tsx
"use client"
import { Button, Field, Input, Stack, TagsInput } from "@chakra-ui/react"
export const TagsInputWithForm = () => {
return (
)
}
```
### Paste
Pass the `addOnPaste` prop to the `TagsInput.Root` component to allow users to
paste multiple values at once, automatically splitting them into individual tags
based on a delimiter.
```tsx
"use client"
import { Box, Clipboard, IconButton, Stack, TagsInput } from "@chakra-ui/react"
export const TagsInputWithPaste = () => (
Paste Tags
)
const SampleClipboard = (props: { value: string }) => (
Copy Tags
)
```
### Blur Behavior
Use the `blurBehavior` prop to configure how the input behaves when it loses
focus, such as automatically creating a tag from the current input value.
```tsx
"use client"
import { TagsInput } from "@chakra-ui/react"
export const TagsInputWithBlurBehavior = () => (
Create Tag on Blur
)
```
### Custom Delimiter
Use the `delimiter` prop to use custom delimiters like commas, semicolons, or
spaces to create new tags as users type.
```tsx
"use client"
import { TagsInput } from "@chakra-ui/react"
const SPLIT_REGEX = /[;,]/
export const TagsInputWithDelimiter = () => (
Custom Delimiters (; ,)
)
```
### Colors
Here's an example that assigns rather color scheme to the tags based on the tag
value.
```tsx
"use client"
import { TagsInput } from "@chakra-ui/react"
export const TagsInputWithColors = () => (
Colored Tags
{({ value }) =>
value.map((tag, index) => (
{tag}
))
}
)
const randomColor = (str: string) => {
// Simple hash from string
let hash = 0
for (let i = 0; i < str.length; i++) {
hash = str.charCodeAt(i) + ((hash << 5) - hash)
}
// Generate light HSL color (H: 0-359, S: 60-80%, L: 85-94%)
const h = Math.abs(hash) % 360
const s = 60 + (Math.abs(hash) % 20) // 60% - 79%
const l = 85 + (Math.abs(hash) % 10) // 85% - 94%
return `hsl(${h},${s}%,${l}%)`
}
```
### Combobox
Here's an example that composes the `TagsInput` component with the `Combobox`
component to create a tags input that allows users to select from a list of
predefined tags.
```tsx
"use client"
import {
Combobox,
TagsInput,
useCombobox,
useFilter,
useListCollection,
useTagsInput,
} from "@chakra-ui/react"
import { useId, useRef } from "react"
export const TagsInputWithCombobox = () => {
const { contains } = useFilter({ sensitivity: "base" })
const { collection, filter } = useListCollection({
initialItems: [
"React",
"Chakra",
"TypeScript",
"Next.js",
"Ark UI",
"Zag.js",
],
filter: contains,
})
const uid = useId()
const controlRef = useRef(null)
const tags = useTagsInput({
ids: { input: `input_${uid}`, control: `control_${uid}` },
})
const comobobox = useCombobox({
ids: { input: `input_${uid}`, control: `control_${uid}` },
collection,
onInputValueChange(e) {
filter(e.inputValue)
},
value: [],
allowCustomValue: true,
onValueChange: (e) => tags.addValue(e.value[0]),
selectionBehavior: "clear",
})
return (
Tags
{tags.value.map((tag, index) => (
{tag}
))}
{collection.items.map((item) => (
{item}
))}
)
}
```
## Props
### Root
| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| delimiter | , | `string \| RegExp` | The character that serves has:
- event key to trigger the addition of a new tag
- character used to split tags when pasting into the input |
| max | Infinity | `number` | The max number of tags |
| sanitizeValue | (value) => value.trim() | `(value: string) => string` | Function to sanitize the tag value before adding.
Useful for trimming whitespace, normalizing case, or stripping special characters. |
| colorPalette | gray | `'gray' \| 'red' \| 'orange' \| 'yellow' \| 'green' \| 'teal' \| 'blue' \| 'cyan' \| 'purple' \| 'pink'` | The color palette of the component |
| size | md | `'xs' \| 'sm' \| 'md' \| 'lg'` | The size of the component |
| variant | outline | `'outline' \| 'subtle' \| 'flushed'` | The variant of the component |
| as | undefined | `React.ElementType` | The underlying element to render. |
| asChild | undefined | `boolean` | Use the provided child element as the default rendered element, combining their props and behavior. |
| unstyled | undefined | `boolean` | Whether to remove the component's style. |
| addOnPaste | false | `boolean` | Whether to add a tag when you paste values into the tag input |
| allowDuplicates | false | `boolean` | Whether to allow duplicate tags. |
| allowOverflow | undefined | `boolean` | Whether to allow tags to exceed max. In this case,
we'll attach `data-invalid` to the root |
| autoFocus | undefined | `boolean` | Whether the input should be auto-focused |
| blurBehavior | undefined | `'clear' \| 'add'` | The behavior of the tags input when the input is blurred
- `"add"`: add the input value as a new tag
- `"clear"`: clear the input value |
| defaultInputValue | undefined | `string` | The initial tag input value when rendered.
Use when you don't need to control the tag input value. |
| defaultValue | undefined | `string[]` | The initial tag value when rendered.
Use when you don't need to control the tag value. |
| disabled | undefined | `boolean` | Whether the tags input should be disabled |
| editable | false | `boolean` | Whether a tag can be edited after creation, by pressing `Enter` or double clicking. |
| form | undefined | `string` | The associate form of the underlying input element. |
| id | undefined | `string` | The unique identifier of the machine. |
| ids | undefined | `Partial<{\n root: string\n input: string\n hiddenInput: string\n clearBtn: string\n label: string\n control: string\n item: (opts: ItemProps) => string\n itemDeleteTrigger: (opts: ItemProps) => string\n itemInput: (opts: ItemProps) => string\n}>` | The ids of the elements in the tags input. Useful for composition. |
| inputValue | undefined | `string` | The controlled tag input's value |
| invalid | undefined | `boolean` | Whether the tags input is invalid |
| maxLength | undefined | `number` | The max length of the input. |
| name | undefined | `string` | The name attribute for the input. Useful for form submissions |
| onFocusOutside | undefined | `(event: FocusOutsideEvent) => void` | Function called when the focus is moved outside the component |
| onHighlightChange | undefined | `(details: HighlightChangeDetails) => void` | Callback fired when a tag is highlighted by pointer or keyboard navigation |
| onInputValueChange | undefined | `(details: InputValueChangeDetails) => void` | Callback fired when the input value is updated |
| onInteractOutside | undefined | `(event: InteractOutsideEvent) => void` | Function called when an interaction happens outside the component |
| onPointerDownOutside | undefined | `(event: PointerDownOutsideEvent) => void` | Function called when the pointer is pressed down outside the component |
| onValueChange | undefined | `(details: ValueChangeDetails) => void` | Callback fired when the tag values is updated |
| onValueInvalid | undefined | `(details: ValidityChangeDetails) => void` | Callback fired when the max tag count is reached or the `validateTag` function returns `false` |
| placeholder | undefined | `string` | The placeholder text for the input |
| readOnly | undefined | `boolean` | Whether the tags input should be read-only |
| required | undefined | `boolean` | Whether the tags input is required |
| translations | undefined | `IntlTranslations` | Specifies the localized strings that identifies the accessibility elements and their states |
| validate | undefined | `(details: ValidateArgs) => boolean` | Returns a boolean that determines whether a tag can be added.
Useful for preventing duplicates or invalid tag values. |
| value | undefined | `string[]` | The controlled tag value |
### Item
| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| index | undefined | `string \| number` | undefined |
| value | undefined | `string` | undefined |
| as | undefined | `React.ElementType` | The underlying element to render. |
| asChild | undefined | `boolean` | Use the provided child element as the default rendered element, combining their props and behavior. |
| disabled | undefined | `boolean` | undefined |
## Explorer
Explore the `TagsInput` component parts interactively. Click on parts in the
sidebar to highlight them in the preview.
Sphinx of black quartz, judge my vow.
}
```
## Usage
```jsx
import { Text } from "@chakra-ui/react"
```
```jsx
This is the text component
```
## Examples
### Sizes
Use the `fontSize` or `textStyle` prop to change the size of the text.
```tsx
import { Stack, Text } from "@chakra-ui/react"
export const TextWithSizes = () => {
return (
Chakra
Chakra
Chakra
Chakra
Chakra
Chakra
Chakra
Chakra
Chakra
Chakra
Chakra
)
}
```
### Weights
Use the `fontWeight` prop to change the weight of the text.
```tsx
import { Stack, Text } from "@chakra-ui/react"
export const TextWithWeights = () => {
return (
Sphinx of black quartz, judge my vow.
Sphinx of black quartz, judge my vow.
Sphinx of black quartz, judge my vow.
Sphinx of black quartz, judge my vow.
Sphinx of black quartz, judge my vow.
)
}
```
### Truncation
Use the `truncate` prop to truncate the text after a single line.
```tsx
import { Flex, Text } from "@chakra-ui/react"
export const TextWithTruncate = () => {
return (
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
)
}
```
### Line Clamp
Use the `lineClamp` prop to truncate the text after a certain number of lines.
```tsx
import { Flex, Text } from "@chakra-ui/react"
export const TextWithLineClamp = () => {
return (
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
commodo consequat.
)
}
```
### Ref
Here's how to access the underlying element reference
```tsx
const Demo = () => {
const ref = useRef(null)
return This is the text component
}
```
# Textarea
```tsx
import { Textarea } from "@chakra-ui/react"
export const TextareaBasic = () => {
return
}
```
## Usage
```jsx
import { Textarea } from "@chakra-ui/react"
```
```jsx
```
## Examples
### Variants
Use the `variant` prop to change the appearance of the textarea.
```tsx
import { Stack, Textarea } from "@chakra-ui/react"
export const TextareaWithVariants = () => {
return (
)
}
```
### Sizes
Use the `size` prop to change the size of the textarea.
```tsx
import { Stack, Textarea } from "@chakra-ui/react"
export const TextareaWithSizes = () => {
return (
)
}
```
### Helper Text
Pair the textarea with the `Field` component to add helper text.
```tsx
import { Field, HStack, Textarea } from "@chakra-ui/react"
export const TextareaWithHelperText = () => {
return (
Comment
Max 500 characters.
Comment
Max 500 characters.
)
}
```
### Error Text
Pair the textarea with the `Field` component to add error text.
```tsx
import { Field, HStack, Textarea } from "@chakra-ui/react"
export const TextareaWithErrorText = () => {
return (
Comment
Field is required
Comment
Field is required
)
}
```
### Field
Compose the textarea with the `Field` component to add a label, helper text, and
error text.
```tsx
import { Field, HStack, Input } from "@chakra-ui/react"
export const InputWithField = () => {
return (
Email
Email
)
}
```
### Hook Form
Here's an example of how to integrate the textarea with `react-hook-form`.
```tsx
"use client"
import { Button, Field, Input, Stack, Textarea } from "@chakra-ui/react"
import { useForm } from "react-hook-form"
interface FormValues {
username: string
bio: string
}
export const TextareaWithHookForm = () => {
const {
register,
handleSubmit,
formState: { errors },
} = useForm()
const onSubmit = handleSubmit((data) => console.log(data))
return (
)
}
```
### Resize
Use the `resize` prop to control the resize behavior of the textarea.
```tsx
import { Stack, Textarea } from "@chakra-ui/react"
export const TextareaWithResize = () => {
return (
)
}
```
To limit the maximum height (or rows) of the textarea, we recommend using the
`maxHeight` prop and setting the value to a `lh` unit.
```tsx
```
### Autoresize
Use the `autoresize` prop to make the textarea autoresize vertically as you
type.
```tsx
import { Textarea } from "@chakra-ui/react"
export const TextareaWithAutoresize = () => {
return
}
```
### Ref
Here's how to access the underlying element reference
```tsx
const Demo = () => {
const ref = useRef(null)
return
}
```
## Props
| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| colorPalette | gray | `'gray' \| 'red' \| 'orange' \| 'yellow' \| 'green' \| 'teal' \| 'blue' \| 'cyan' \| 'purple' \| 'pink'` | The color palette of the component |
| size | md | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | The size of the component |
| variant | outline | `'outline' \| 'subtle' \| 'flushed'` | The variant of the component |
| as | undefined | `React.ElementType` | The underlying element to render. |
| asChild | undefined | `boolean` | Use the provided child element as the default rendered element, combining their props and behavior. |
# Theme
```tsx
import { Button, Stack, Theme } from "@chakra-ui/react"
export const ThemeBasic = () => {
return (
Auto Button
Dark Button
Light Button
)
}
```
## Usage
```jsx
import { Theme } from "@chakra-ui/react"
```
```jsx
```
## Examples
### Nested
The theme can be nested to apply different appearances to different parts of the
tree. This is useful for applying a global appearance and then overriding some
parts of it.
> Good to know: We use native CSS selectors to achieve this.
```tsx
import { Box, Button, Theme } from "@chakra-ui/react"
export const ThemeNested = () => {
return (
Hello Normal Click me
Hello Dark Click me
Hello Light Click me
)
}
```
### Portalled
Use the `asChild` prop to force the appearance of portalled elements like the
popover and modal content.
```tsx
import { Button, Input, Popover, Portal, Text, Theme } from "@chakra-ui/react"
export const ThemeWithPortalled = () => {
return (
Click me
Naruto Form
Naruto is a Japanese manga series written and illustrated by
Masashi Kishimoto.
Click me
)
}
```
### Page Specific Color Mode
To lock a page to a specific color mode (light or dark), wrap the entire page
with the `Theme` component.
You can also combine it with the `ColorModeProvider` if you use the
`useColorMode` hook.
```tsx
import { ColorModeProvider } from "@/components/ui/color-mode"
import { Theme } from "@chakra-ui/react"
export const ForcedColorMode = ({ children }) => {
return (
{/* Rest of the page */}
)
}
```
# Timeline
```tsx
import { Text, Timeline } from "@chakra-ui/react"
import { LuCheck, LuPackage, LuShip } from "react-icons/lu"
export const TimelineBasic = () => {
return (
Product Shipped
13th May 2021
We shipped your product via FedEx and it should
arrive within 3-5 business days.
Order Confirmed
18th May 2021
Order Delivered
20th May 2021, 10:30am
)
}
```
## Usage
```tsx
import { Timeline } from "@chakra-ui/react"
```
```tsx
```
## Examples
### Sizes
Use the `size` prop to change the size of the timeline.
```tsx
import { Avatar, Badge, For, Span, Stack, Timeline } from "@chakra-ui/react"
import { LuCheck } from "react-icons/lu"
export const TimelineWithSizes = () => {
return (
{(size) => (
sage
created a new project
sage
changed status from
In progress
to{" "}
Completed
)}
)
}
```
### Variants
Use the `variant` prop to change the variant of the timeline.
```tsx
import { Avatar, Badge, For, Span, Stack, Timeline } from "@chakra-ui/react"
import { LuCheck } from "react-icons/lu"
export const TimelineWithVariants = () => {
return (
{(variant) => (
sage
created a new project
sage
changed status from In progress to{" "}
Completed
)}
)
}
```
### Content Before
Here's an example of a timeline with content before the timeline indicator.
```tsx
import { For, Stack, Timeline } from "@chakra-ui/react"
export const TimelineWithContentBefore = () => {
return (
{(size) => (
Nov 1994
1
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Nov 2010
2
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
)}
)
}
```
### Alternating Content
Here's an example of a timeline with alternating content.
```tsx
import { Timeline } from "@chakra-ui/react"
export const TimelineAlternating = () => {
return (
Placed Order
Prepared Order
Order Delivered
)
}
```
### Composition
Here's an example of how to compose the timeline with other components to create
a consistent-looking timeline.
```tsx
import {
Avatar,
Button,
Card,
Icon,
Input,
Span,
Timeline,
} from "@chakra-ui/react"
import { LuPen, LuX } from "react-icons/lu"
import LoremIpsum from "react-lorem-ipsum"
export const TimelineComposition = () => {
return (
Lucas Moras has changed
3 labels on
Jan 1, 2024
Jenna Smith removed
Enas
on Jan 12, 2024
Erica commented
on Jan 12, 2024
👏 2
)
}
```
## Props
### Root
| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| colorPalette | gray | `'gray' \| 'red' \| 'orange' \| 'yellow' \| 'green' \| 'teal' \| 'blue' \| 'cyan' \| 'purple' \| 'pink'` | The color palette of the component |
| variant | solid | `'subtle' \| 'solid' \| 'outline' \| 'plain'` | The variant of the component |
| size | md | `'sm' \| 'md' \| 'lg' \| 'xl'` | The size of the component |
| as | undefined | `React.ElementType` | The underlying element to render. |
| asChild | undefined | `boolean` | Use the provided child element as the default rendered element, combining their props and behavior. |
| unstyled | undefined | `boolean` | Whether to remove the component's style. |
| showLastSeparator | false | `'true' \| 'false'` | The showLastSeparator of the component |
## Explorer
Explore the `Timeline` component parts interactively. Click on parts in the
sidebar to highlight them in the preview.
toaster.create({
description: "File saved successfully",
type: "info",
})
}
>
Show Toast
)
}
```
## Setup
If you don't already have the snippet, run the following command to add the
`toaster` snippet
```sh
npx @chakra-ui/cli snippet add toaster
```
The snippet includes a closed component composition for the `Toast` component.
## Usage
```jsx
import { Toaster, toaster } from "@/components/ui/toaster"
```
First, render the `Toaster` component in your app.
```jsx
toaster.create({
description: "File saved successfully",
type: "info",
closable: true,
})
}
>
Show Toast
)
}
```
### External Close
Use the `toaster.dismiss` method to close a toast.
- `toaster.dismiss(id)`: Dismiss a toast by its id.
- `toaster.dismiss()`: Dismiss all toasts.
```tsx
"use client"
import { Button, HStack } from "@chakra-ui/react"
import { toaster } from "@/components/ui/toaster"
export const ToasterWithExternalClose = () => {
return (
toaster.create({
description: "File saved successfully",
type: "info",
})
}
>
Show Toast
toaster.dismiss()}>
Close Toasts
)
}
```
### Types
Here's an example of each type of toast.
```tsx
"use client"
import { Button, For, HStack } from "@chakra-ui/react"
import { toaster } from "@/components/ui/toaster"
export const ToasterWithStatus = () => {
return (
{(type) => (
toaster.create({
title: `Toast status is ${type}`,
type: type,
})
}
>
{type}
)}
)
}
```
### With Action
Use the `action` and `actionLabel` prop to add an action to the toast.
> When the action trigger is clicked, the toast will be closed.
```tsx
"use client"
import { Button } from "@chakra-ui/react"
import { toaster } from "@/components/ui/toaster"
export const ToasterWithAction = () => {
return (
toaster.success({
title: "Update successful",
description: "File saved successfully to the server",
action: {
label: "Undo",
onClick: () => console.log("Undo"),
},
})
}
>
Click me
)
}
```
### Persistent Toast
Set the `type` prop to `"loading"` to create a persistent toast.
```tsx
"use client"
import { Button } from "@chakra-ui/react"
import { toaster } from "@/components/ui/toaster"
export const ToasterPersistent = () => {
return (
toaster.create({
description: "File saved successfully",
type: "loading",
})
}
>
Show Toast
)
}
```
### Promise
Use the `toaster.promise` to create a toast that resolves when the promise is
resolved.
Next, you can define the toast options (title, description, etc.) for each state
of the promise.
```tsx
"use client"
import { Button } from "@chakra-ui/react"
import { toaster } from "@/components/ui/toaster"
export const ToasterWithPromise = () => {
return (
{
const promise = new Promise((resolve) => {
setTimeout(() => resolve(), 5000)
})
toaster.promise(promise, {
success: {
title: "Successfully uploaded!",
description: "Looks great",
},
error: {
title: "Upload failed",
description: "Something wrong with the upload",
},
loading: { title: "Uploading...", description: "Please wait" },
})
}}
>
Show Toast
)
}
```
### Update
Use `toaster.update(...)` to modify a visible toast.
```tsx
"use client"
import { Button, HStack } from "@chakra-ui/react"
import { toaster } from "@/components/ui/toaster"
export const ToasterWithUpdate = () => {
const id = "login-error-toast"
const show = () => {
if (toaster.isVisible(id)) return
toaster.loading({
id,
title: "Error Connecting...",
description: "You do not have permissions to perform this action.",
})
}
const update = () => {
toaster.update(id, {
title: "Hooray 🥳🥳🥳!!!",
description: "You now have permissions to perform this action.",
type: "success",
duration: 3000,
})
}
return (
Show Toast
Update Toast
)
}
```
### Custom Duration
Use the `duration` prop to set the duration of the toast.
```tsx
"use client"
import { Button } from "@chakra-ui/react"
import { toaster } from "@/components/ui/toaster"
export const ToasterWithDuration = () => {
return (
toaster.create({
description: "File saved successfully",
duration: 6000,
})
}
>
Show Toast
)
}
```
### Pause and Play
Use the `pause` and `resume` methods on the `toaster` object to pause and play
the toast.
Pausing a toast prevents it from timing out, while resuming it will reenable the
timeout using the remaining duration.
```tsx
"use client"
import { Button, HStack } from "@chakra-ui/react"
import { toaster } from "@/components/ui/toaster"
import { useId, useState } from "react"
import { HiPause, HiPlay } from "react-icons/hi"
export const ToasterPauseAndPlay = () => {
const id = useId()
const [paused, setPaused] = useState(false)
const [shown, setShown] = useState(false)
const show = () => {
toaster.success({
id,
title: "This is a success toast",
onStatusChange: (details) => {
if (details.status === "visible") {
setShown(true)
} else if (details.status === "dismissing") {
setShown(false)
}
},
})
}
const pause = () => {
toaster.pause(id)
setPaused(true)
}
const play = () => {
toaster.resume(id)
setPaused(false)
}
return (
Show Toast
)
}
```
### Lifecycle
Use the `onStatusChange` prop on the `toaster` function to listen for changes to
the toast's status.
```tsx
"use client"
import { Button, HStack, Stack, Text } from "@chakra-ui/react"
import { toaster } from "@/components/ui/toaster"
import { useState } from "react"
export const ToasterLifecycle = () => {
const [statusLog, setStatusLog] = useState<[number, string][]>([])
const [dismissed, setDismissed] = useState(true)
return (
toaster.create({
description: "This is a toast",
type: "info",
onStatusChange({ status }) {
setDismissed(status === "unmounted")
setStatusLog((prev) => [[Date.now(), status], ...prev])
},
})
}
>
Show Toast
{statusLog.map(([time, toastStatus], i) => {
const date = new Date(time)
return (
{date.toLocaleTimeString()}{" "}
{toastStatus}
)
})}
)
}
```
### Maximum Visible Toasts
Set the `max` prop on the `createToaster` function to define the maximum number
of toasts that can be rendered at any one time. Any extra toasts will be queued
and rendered when a toast has been dismissed.
```jsx title="@/components/ui/toaster.tsx"
const toaster = createToaster({
max: 3,
})
```
### Placement
Toasts can be displayed on all four corners of a page. We recommend picking one
desired position and configure it in the `createToaster` function.
```jsx title="@/components/ui/toaster.tsx"
const toaster = createToaster({
placement: "top-end",
})
```
### Overlapping Toasts
By default, toasts are stacked on top of each other. To make the toasts overlap
each other, set the `overlap` prop to `true` in the `createToaster` function.
```jsx title="@/components/ui/toaster.tsx"
const toaster = createToaster({
placement: "top-end",
overlap: true,
})
```
### Page Idle Behavior
Pause toast timers when the page is idle/hidden.
```tsx title="@/components/ui/toaster.tsx"
const toaster = createToaster({
pauseOnPageIdle: true,
})
```
### Offset
Set the `offsets` prop in the `createToaster` function to offset the toasts from
the edges of the screen.
```jsx title="@/components/ui/toaster.tsx"
const toaster = createToaster({
offsets: "20px",
})
```
Alternatively, you can use the `offsets` prop to set the offset for each edge of
the screen.
```jsx title="@/components/ui/toaster.tsx"
const toaster = createToaster({
offsets: { left: "20px", top: "20px", right: "20px", bottom: "20px" },
})
```
## Props
### Toaster
)
}
```
## Setup
For ease of use, create a closed component composition for the `ToggleTip`
component.
```
## Examples
### Info Tip
Use the `InfoTip` component to display an info tip. This component renders an
icon button with an info icon by default.
> Useful for landing pages to display additional information about a feature.
```tsx
import { FormatByte, HStack, Text } from "@chakra-ui/react"
import { InfoTip } from "@/components/ui/toggle-tip"
export const ToggleTipInfoTip = () => {
return (
File size:
)
}
```
### Sizes
The toggle tip supports `xs`, `sm`, `md`, and `lg` size variants. Pass the
`size` prop to both the component and the button to scale it consistently.
```tsx
import { For, HStack } from "@chakra-ui/react"
import { InfoTip } from "@/components/ui/toggle-tip"
export const ToggleTipSizes = () => {
return (
{(size) => (
)
}
```
### Arrow
Set `showArrow` to display a directional arrow pointing from the popover content
to the trigger element.
```tsx
import { Flex } from "@chakra-ui/react"
import { InfoTip } from "@/components/ui/toggle-tip"
export const ToggleTipArrow = () => {
return (
)
}
```
### Close on Escape
By default (`true`), pressing the Escape key closes the toggle tip. Set to
`false` to keep it open on Escape.
```tsx
import { Flex } from "@chakra-ui/react"
import { InfoTip } from "@/components/ui/toggle-tip"
export const ToggleTipCloseOnEscape = () => {
return (
)
}
```
### Close on Interact Outside
By default (`true`), clicking outside the toggle tip closes it. Set to `false`
to allow outside interaction without closing.
```tsx
import { Flex } from "@chakra-ui/react"
import { InfoTip } from "@/components/ui/toggle-tip"
export const ToggleTipCloseOnInteractOutside = () => {
return (
)
}
```
## Props
### Root
| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| autoFocus | true | `boolean` | Whether to automatically set focus on the first focusable
content within the popover when opened. |
| closeOnEscape | true | `boolean` | Whether to close the popover when the escape key is pressed. |
| closeOnInteractOutside | true | `boolean` | Whether to close the popover when the user clicks outside of the popover. |
| hideMode | 'display-none' | `HideMode` | How to hide content when mounted but not present.
- `'display-none'`: HTML `hidden` attribute. Effects stay alive.
- `'activity'`: React 19 ``. Effects pause. Requires React 19+. |
| portalled | true | `boolean` | Whether the popover is portalled. This will proxy the tabbing behavior regardless of the DOM position
of the popover content. |
| restoreFocus | true | `boolean` | Whether to restore focus to the element that had focus before the popover was opened. |
| size | md | `'xs' \| 'sm' \| 'md' \| 'lg'` | The size of the component |
| as | undefined | `React.ElementType` | The underlying element to render. |
| asChild | undefined | `boolean` | Use the provided child element as the default rendered element, combining their props and behavior. |
| unstyled | undefined | `boolean` | Whether to remove the component's style. |
| defaultOpen | undefined | `boolean` | The initial open state of the popover when rendered.
Use when you don't need to control the open state of the popover. |
| defaultTriggerValue | undefined | `string` | The initial trigger value when rendered.
Use when you don't need to control the trigger value. |
| finalFocusEl | undefined | `() => MaybeElement` | Element to receive focus when the popover is closed. |
| id | undefined | `string` | The unique identifier of the machine. |
| ids | undefined | `Partial<{\n anchor: string\n trigger: string \| ((value?: string \| undefined) => string)\n content: string\n title: string\n description: string\n closeTrigger: string\n positioner: string\n arrow: string\n}>` | The ids of the elements in the popover. Useful for composition. |
| immediate | undefined | `boolean` | Whether to synchronize the present change immediately or defer it to the next frame |
| initialFocusEl | undefined | `() => HTMLElement \| null` | The element to focus on when the popover is opened. |
| lazyMount | false | `boolean` | Whether to enable lazy mounting |
| modal | false | `boolean` | Whether the popover should be modal. When set to `true`:
- interaction with outside elements will be disabled
- only popover content will be visible to screen readers
- scrolling is blocked
- focus is trapped within the popover |
| onEscapeKeyDown | undefined | `(event: KeyboardEvent) => void` | Function called when the escape key is pressed |
| onExitComplete | undefined | `VoidFunction` | Function called when the animation ends in the closed state |
| onFocusOutside | undefined | `(event: FocusOutsideEvent) => void` | Function called when the focus is moved outside the component |
| onInteractOutside | undefined | `(event: InteractOutsideEvent) => void` | Function called when an interaction happens outside the component |
| onOpenChange | undefined | `(details: OpenChangeDetails) => void` | Function invoked when the popover opens or closes |
| onPointerDownOutside | undefined | `(event: PointerDownOutsideEvent) => void` | Function called when the pointer is pressed down outside the component |
| onRequestDismiss | undefined | `(event: LayerDismissEvent) => void` | Function called when this layer is closed due to a parent layer being closed |
| onTriggerValueChange | undefined | `(details: TriggerValueChangeDetails) => void` | Function called when the trigger value changes. |
| open | undefined | `boolean` | The controlled open state of the popover |
| persistentElements | undefined | `(() => Element \| null)[]` | Returns the persistent elements that:
- should not have pointer-events disabled
- should not trigger the dismiss event |
| positioning | undefined | `PositioningOptions` | The user provided options used to position the popover content |
| present | undefined | `boolean` | Whether the node is present (controlled by the user) |
| skipAnimationOnMount | false | `boolean` | Whether to allow the initial presence animation. |
| translations | undefined | `IntlTranslations` | Specifies the localized strings that identifies the accessibility elements and their states |
| triggerValue | undefined | `string` | The controlled trigger value |
| unmountOnExit | false | `boolean` | Whether to unmount on exit. |
# Tooltip
```tsx
import { Button } from "@chakra-ui/react"
import { Tooltip } from "@/components/ui/tooltip"
export const TooltipBasic = () => {
return (
Hover me
)
}
```
## Setup
For ease of use, create a closed component composition for the `Tooltip`
component.
```
## Examples
### Arrow
Use the `showArrow` prop to show an arrow on the tooltip.
```tsx
import { Button } from "@chakra-ui/react"
import { Tooltip } from "@/components/ui/tooltip"
export const TooltipWithArrow = () => {
return (
Hover me
)
}
```
### Placement
Use the `positioning.placement` prop to change the position of the tooltip.
```tsx
import { Button } from "@chakra-ui/react"
import { Tooltip } from "@/components/ui/tooltip"
export const TooltipWithPlacement = () => {
return (
Hover me
)
}
```
### Offset
Use the `positioning.offset` prop to change the offset of the tooltip.
```tsx
import { Button } from "@chakra-ui/react"
import { Tooltip } from "@/components/ui/tooltip"
export const TooltipWithOffset = () => {
return (
Hover me
)
}
```
### Delay
Use the `openDelay` and `closeDelay` prop to change the delay of the tooltip.
```tsx
import { Button } from "@chakra-ui/react"
import { Tooltip } from "@/components/ui/tooltip"
export const TooltipWithDelay = () => {
return (
Delay (open: 500ms, close: 100ms)
)
}
```
### Custom Background
Use the `--tooltip-bg` CSS variable to change the background color of the
tooltip.
```tsx
import { Button } from "@chakra-ui/react"
import { Tooltip } from "@/components/ui/tooltip"
import { FaBell } from "react-icons/fa"
export const TooltipWithCustomBg = () => (
)
```
### Controlled
Use the `open` and `onOpenChange` prop to control the visibility of the tooltip.
```tsx
"use client"
import { Button } from "@chakra-ui/react"
import { Tooltip } from "@/components/ui/tooltip"
import { useState } from "react"
export const TooltipControlled = () => {
const [open, setOpen] = useState(false)
return (
setOpen(e.open)}
>
{open ? "Hide" : "Show"} tooltip
)
}
```
### Store
An alternative way to control the tooltip is to use the `RootProvider` component
and the `useTooltip` store hook.
This way you can access the tooltip state and methods from outside the tooltip.
```tsx
"use client"
import { Button, HStack, Tooltip, useTooltip } from "@chakra-ui/react"
export const TooltipWithStore = () => {
const tooltip = useTooltip()
const toggleOpen = () => tooltip.setOpen(!tooltip.open)
return (
Toggle
Tooltip Target
This is the tooltip content
)
}
```
### Interactive
Use the `interactive` prop to keep the tooltip open when interacting with its
content.
```tsx
import { Button } from "@chakra-ui/react"
import { Tooltip } from "@/components/ui/tooltip"
export const TooltipWithInteractive = () => {
return (
Hover me
)
}
```
### Disabled
Use the `disabled` prop to disable the tooltip. When disabled, the tooltip will
not be shown.
```tsx
import { Button } from "@chakra-ui/react"
import { Tooltip } from "@/components/ui/tooltip"
export const TooltipWithDisabled = () => {
return (
Hover me
)
}
```
### With Avatar
Here's an example of how to use the `Tooltip` component with an `Avatar`
component.
```tsx
import { Avatar } from "@chakra-ui/react"
import { Tooltip } from "@/components/ui/tooltip"
import { useId } from "react"
export const TooltipWithAvatar = () => {
const id = useId()
return (
)
}
```
### With Checkbox
Here's an example of how to use the `Tooltip` component with a `Checkbox`
component.
```tsx
import { Checkbox } from "@chakra-ui/react"
import { Tooltip } from "@/components/ui/tooltip"
import { useId } from "react"
export const TooltipWithCheckbox = () => {
const id = useId()
return (
Welcome
)
}
```
### With MenuItem
Here's an example of how to use the `Tooltip` with a `MenuItem` component.
```tsx
import { Button, Menu, Portal, Show } from "@chakra-ui/react"
import { Tooltip } from "@/components/ui/tooltip"
export const TooltipWithMenuItem = () => {
return (
Open
Open tooltip
New File...
New Window
Export
)
}
const MenuItem = (props: Menu.ItemProps) => {
const { value, title, ...rest } = props
return (
)
}
```
### With MenuTrigger
Here's an example of how to use the `Tooltip` with a `MenuTrigger` component.
```tsx
"use client"
import { Button, Menu, Portal } from "@chakra-ui/react"
import { Tooltip } from "@/components/ui/tooltip"
import { useId } from "react"
export const TooltipWithMenuTrigger = () => {
const triggerId = useId()
return (
Open
Open tooltip
New File...
New Window
Export
)
}
```
### With Switch
Here's an example of how to wrap `Tooltip` around a `Switch` component.
```tsx
import { Switch } from "@chakra-ui/react"
import { Tooltip } from "@/components/ui/tooltip"
import { useId } from "react"
export const TooltipWithSwitch = () => {
const id = useId()
return (
Toggle
)
}
```
### With Tabs
Here's an example of how to wrap `Tooltip` around a `Tabs` component.
```tsx
import { Tabs } from "@chakra-ui/react"
import { Tooltip } from "@/components/ui/tooltip"
import { LuFolder, LuSquareCheck, LuUser } from "react-icons/lu"
export const TooltipWithTab = () => {
return (
{/* TODO: Remove this once Zag.js is fixed */}
Manage your team members
Manage your projects
Manage your tasks for freelancers
)
}
```
## Props
### Root
| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| closeDelay | 150 | `number` | The close delay of the tooltip. |
| closeOnClick | true | `boolean` | Whether the tooltip should close on click |
| closeOnEscape | true | `boolean` | Whether to close the tooltip when the Escape key is pressed. |
| closeOnPointerDown | true | `boolean` | Whether to close the tooltip on pointerdown. |
| closeOnScroll | true | `boolean` | Whether the tooltip should close on scroll |
| hideMode | 'display-none' | `HideMode` | How to hide content when mounted but not present.
- `'display-none'`: HTML `hidden` attribute. Effects stay alive.
- `'activity'`: React 19 ``. Effects pause. Requires React 19+. |
| lazyMount | true | `boolean` | Whether to enable lazy mounting |
| openDelay | 400 | `number` | The open delay of the tooltip. |
| unmountOnExit | true | `boolean` | Whether to unmount on exit. |
| as | undefined | `React.ElementType` | The underlying element to render. |
| asChild | undefined | `boolean` | Use the provided child element as the default rendered element, combining their props and behavior. |
| unstyled | undefined | `boolean` | Whether to remove the component's style. |
| aria-label | undefined | `string` | Custom label for the tooltip. |
| defaultOpen | undefined | `boolean` | The initial open state of the tooltip when rendered.
Use when you don't need to control the open state of the tooltip. |
| defaultTriggerValue | undefined | `string` | The initial trigger value when rendered.
Use when you don't need to control the trigger value. |
| disabled | undefined | `boolean` | Whether the tooltip is disabled |
| id | undefined | `string` | The unique identifier of the machine. |
| ids | undefined | `Partial<{\n trigger: string \| ((value?: string \| undefined) => string)\n content: string\n arrow: string\n positioner: string\n}>` | The ids of the elements in the tooltip. Useful for composition. |
| immediate | undefined | `boolean` | Whether to synchronize the present change immediately or defer it to the next frame |
| interactive | false | `boolean` | Whether the tooltip's content is interactive.
In this mode, the tooltip will remain open when user hovers over the content. |
| onExitComplete | undefined | `VoidFunction` | Function called when the animation ends in the closed state |
| onOpenChange | undefined | `(details: OpenChangeDetails) => void` | Function called when the tooltip is opened. |
| onTriggerValueChange | undefined | `(details: TriggerValueChangeDetails) => void` | Function called when the trigger value changes. |
| open | undefined | `boolean` | The controlled open state of the tooltip |
| positioning | undefined | `PositioningOptions` | The user provided options used to position the popover content |
| present | undefined | `boolean` | Whether the node is present (controlled by the user) |
| skipAnimationOnMount | false | `boolean` | Whether to allow the initial presence animation. |
| triggerValue | undefined | `string` | The controlled trigger value |
## Explorer
Explore the `Tooltip` component parts interactively. Click on parts in the
sidebar to highlight them in the preview.
Tree
{node.name}
) : (
{node.name}
)
}
/>
)
}
interface Node {
id: string
name: string
children?: Node[]
}
const collection = createTreeCollection({
nodeToValue: (node) => node.id,
nodeToString: (node) => node.name,
rootNode: {
id: "ROOT",
name: "",
children: [
{
id: "node_modules",
name: "node_modules",
children: [
{ id: "node_modules/zag-js", name: "zag-js" },
{ id: "node_modules/pandacss", name: "panda" },
{
id: "node_modules/@types",
name: "@types",
children: [
{ id: "node_modules/@types/react", name: "react" },
{ id: "node_modules/@types/react-dom", name: "react-dom" },
],
},
],
},
{
id: "src",
name: "src",
children: [
{ id: "src/app.tsx", name: "app.tsx" },
{ id: "src/index.ts", name: "index.ts" },
],
},
{ id: "panda.config", name: "panda.config.ts" },
{ id: "package.json", name: "package.json" },
{ id: "renovate.json", name: "renovate.json" },
{ id: "readme.md", name: "README.md" },
],
},
})
```
## Usage
```tsx
import { TreeView } from "@chakra-ui/react"
```
```tsx
```
> To setup the tree view, you need to use the
> [tree collection](https://ark-ui.com/docs/collections/tree-collection) to
> register the tree data.
## Shortcuts
### `TreeView.Node`
This component is a helper to manage the recursive rendering of the branch and
leaf nodes.
```tsx
nodeState.isBranch ? (
{node.name}
) : (
{node.name}
)
}
/>
```
is equivalent to:
```tsx
const TreeNode = (props: TreeView.NodeProviderProps) => {
const { node, indexPath } = props
return (
{node.children ? (
{node.name}
) : (
{node.name}
)}
)
}
```
## Examples
### Sizes
Use the `size` prop to change the size of the tree view.
```tsx
"use client"
import { For, Stack, TreeView, createTreeCollection } from "@chakra-ui/react"
import { LuFile, LuFolder } from "react-icons/lu"
export const TreeViewWithSizes = () => {
return (
{(size) => (
Tree (size={size})
{node.name}
) : (
{node.name}
)
}
/>
)}
)
}
interface Node {
id: string
name: string
children?: Node[]
}
const collection = createTreeCollection({
nodeToValue: (node) => node.id,
nodeToString: (node) => node.name,
rootNode: {
id: "ROOT",
name: "",
children: [
{
id: "node_modules",
name: "node_modules",
children: [
{ id: "node_modules/zag-js", name: "zag-js" },
{ id: "node_modules/pandacss", name: "panda" },
{
id: "node_modules/@types",
name: "@types",
children: [
{ id: "node_modules/@types/react", name: "react" },
{ id: "node_modules/@types/react-dom", name: "react-dom" },
],
},
],
},
{
id: "src",
name: "src",
children: [
{ id: "src/app.tsx", name: "app.tsx" },
{ id: "src/index.ts", name: "index.ts" },
],
},
{ id: "panda.config", name: "panda.config.ts" },
{ id: "package.json", name: "package.json" },
{ id: "renovate.json", name: "renovate.json" },
{ id: "readme.md", name: "README.md" },
],
},
})
```
### Variants
Use the `variant` prop to change the variant of the tree view.
```tsx
"use client"
import { For, Stack, TreeView, createTreeCollection } from "@chakra-ui/react"
import { LuFile, LuFolder } from "react-icons/lu"
export const TreeViewWithVariants = () => {
return (
{(variant) => (
Tree (variant={variant})
nodeState.isBranch ? (
{node.name}
) : (
{node.name}
)
}
/>
)}
)
}
interface Node {
id: string
name: string
children?: Node[]
}
const collection = createTreeCollection({
nodeToValue: (node) => node.id,
nodeToString: (node) => node.name,
rootNode: {
id: "ROOT",
name: "",
children: [
{
id: "node_modules",
name: "node_modules",
children: [
{ id: "node_modules/zag-js", name: "zag-js" },
{ id: "node_modules/pandacss", name: "panda" },
{
id: "node_modules/@types",
name: "@types",
children: [
{ id: "node_modules/@types/react", name: "react" },
{ id: "node_modules/@types/react-dom", name: "react-dom" },
],
},
],
},
{
id: "src",
name: "src",
children: [
{ id: "src/app.tsx", name: "app.tsx" },
{ id: "src/index.ts", name: "index.ts" },
],
},
{ id: "panda.config", name: "panda.config.ts" },
{ id: "package.json", name: "package.json" },
{ id: "renovate.json", name: "renovate.json" },
{ id: "readme.md", name: "README.md" },
],
},
})
```
### Colors
Use the `colorPalette` prop to change the color palette of the tree view.
```tsx
"use client"
import { For, TreeView, Wrap, createTreeCollection } from "@chakra-ui/react"
import { LuFile, LuFolder } from "react-icons/lu"
export const TreeViewWithColors = () => {
return (
{(colorPalette) => (
Tree (colorPalette={colorPalette})
nodeState.isBranch ? (
{node.name}
) : (
{node.name}
)
}
/>
)}
)
}
interface Node {
id: string
name: string
children?: Node[]
}
const collection = createTreeCollection({
nodeToValue: (node) => node.id,
nodeToString: (node) => node.name,
rootNode: {
id: "ROOT",
name: "",
children: [
{
id: "node_modules",
name: "node_modules",
children: [
{ id: "node_modules/zag-js", name: "zag-js" },
{ id: "node_modules/pandacss", name: "panda" },
{
id: "node_modules/@types",
name: "@types",
children: [
{ id: "node_modules/@types/react", name: "react" },
{ id: "node_modules/@types/react-dom", name: "react-dom" },
],
},
],
},
{
id: "src",
name: "src",
children: [
{ id: "src/app.tsx", name: "app.tsx" },
{ id: "src/index.ts", name: "index.ts" },
],
},
{ id: "panda.config", name: "panda.config.ts" },
{ id: "package.json", name: "package.json" },
{ id: "renovate.json", name: "renovate.json" },
{ id: "readme.md", name: "README.md" },
],
},
})
```
### Disabled Node
Adding the `disabled` prop to a node's property will disable the node and
prevent interaction.
```tsx
"use client"
import { TreeView, createTreeCollection } from "@chakra-ui/react"
import { LuFile, LuFolder } from "react-icons/lu"
export const TreeViewDisabledNode = () => {
return (
Tree
{node.name}
) : (
{node.name}
)
}
/>
)
}
interface Node {
id: string
name: string
disabled?: boolean
children?: Node[]
}
const collection = createTreeCollection({
nodeToValue: (node) => node.id,
nodeToString: (node) => node.name,
rootNode: {
id: "ROOT",
name: "",
children: [
{
id: "node_modules",
name: "node_modules",
children: [
{ id: "node_modules/zag-js", name: "zag-js" },
{ id: "node_modules/pandacss", name: "panda" },
{
id: "node_modules/@types",
name: "@types",
children: [
{ id: "node_modules/@types/react", name: "react" },
{ id: "node_modules/@types/react-dom", name: "react-dom" },
],
},
],
},
{
id: "src",
name: "src",
children: [
{ id: "src/app.tsx", name: "app.tsx" },
{ id: "src/index.ts", name: "index.ts" },
],
},
{ id: "panda.config", name: "panda.config.ts" },
{ id: "package.json", name: "package.json" },
{ id: "renovate.json", name: "renovate.json", disabled: true },
{ id: "readme.md", name: "README.md" },
],
},
})
```
### Controlled Expansion
Use the `expandedValue` and `onExpandedChange` props to programmatically control
node expansion behavior.
```tsx
"use client"
import { TreeView, createTreeCollection } from "@chakra-ui/react"
import { useState } from "react"
import { LuFile, LuFolder } from "react-icons/lu"
export const TreeViewControlledExpansion = () => {
const [expandedValue, setExpandedValue] = useState(["node_modules"])
return (
setExpandedValue(e.expandedValue)}
>
Tree
indentGuide={
{node.name}
) : (
{node.name}
)
}
/>
)
}
interface Node {
id: string
name: string
children?: Node[]
}
const collection = createTreeCollection({
nodeToValue: (node) => node.id,
nodeToString: (node) => node.name,
rootNode: {
id: "ROOT",
name: "",
children: [
{
id: "node_modules",
name: "node_modules",
children: [
{ id: "node_modules/zag-js", name: "zag-js" },
{ id: "node_modules/pandacss", name: "panda" },
{
id: "node_modules/@types",
name: "@types",
children: [
{ id: "node_modules/@types/react", name: "react" },
{ id: "node_modules/@types/react-dom", name: "react-dom" },
],
},
],
},
{
id: "src",
name: "src",
children: [
{ id: "src/app.tsx", name: "app.tsx" },
{ id: "src/index.ts", name: "index.ts" },
],
},
{ id: "panda.config", name: "panda.config.ts" },
{ id: "package.json", name: "package.json" },
{ id: "renovate.json", name: "renovate.json" },
{ id: "readme.md", name: "README.md" },
],
},
})
```
### Explicit Expand
Render the `TreeView.BranchTrigger` to manually control node expansion behavior.
> You might need to set `role="none"` on the `TreeView.BranchControl` to avoid
> accessibility issues.
```tsx
"use client"
import { TreeView, createTreeCollection } from "@chakra-ui/react"
import { LuChevronRight, LuFile, LuFolder } from "react-icons/lu"
export const TreeViewExplicitExpand = () => {
return (
Tree
{node.name}
) : (
{node.name}
)
}
/>
)
}
interface Node {
id: string
name: string
children?: Node[]
}
const collection = createTreeCollection({
nodeToValue: (node) => node.id,
nodeToString: (node) => node.name,
rootNode: {
id: "ROOT",
name: "",
children: [
{
id: "node_modules",
name: "node_modules",
children: [
{ id: "node_modules/zag-js", name: "zag-js" },
{ id: "node_modules/pandacss", name: "panda" },
{
id: "node_modules/@types",
name: "@types",
children: [
{ id: "node_modules/@types/react", name: "react" },
{ id: "node_modules/@types/react-dom", name: "react-dom" },
],
},
],
},
{
id: "src",
name: "src",
children: [
{ id: "src/app.tsx", name: "app.tsx" },
{ id: "src/index.ts", name: "index.ts" },
],
},
{ id: "panda.config", name: "panda.config.ts" },
{ id: "package.json", name: "package.json" },
{ id: "renovate.json", name: "renovate.json" },
{ id: "readme.md", name: "README.md" },
],
},
})
```
### Expand Icon
Use the `nodeState.expanded` prop to swap the rendered icon on the branch when
it's expanded or collapsed.
```tsx
"use client"
import { TreeView, createTreeCollection } from "@chakra-ui/react"
import { LuSquareMinus, LuSquarePlus } from "react-icons/lu"
export const TreeViewExpandIcon = () => {
return (
Tree
nodeState.isBranch ? (
{nodeState.expanded ? {node.name}
) : (
{node.name}
)
}
/>
)
}
interface Node {
id: string
name: string
children?: Node[]
}
const collection = createTreeCollection({
nodeToValue: (node) => node.id,
nodeToString: (node) => node.name,
rootNode: {
id: "ROOT",
name: "",
children: [
{
id: "node_modules",
name: "node_modules",
children: [
{ id: "node_modules/zag-js", name: "zag-js" },
{ id: "node_modules/pandacss", name: "panda" },
{
id: "node_modules/@types",
name: "@types",
children: [
{ id: "node_modules/@types/react", name: "react" },
{ id: "node_modules/@types/react-dom", name: "react-dom" },
],
},
],
},
{
id: "src",
name: "src",
children: [
{ id: "src/app.tsx", name: "app.tsx" },
{ id: "src/index.ts", name: "index.ts" },
],
},
{ id: "panda.config", name: "panda.config.ts" },
{ id: "package.json", name: "package.json" },
{ id: "renovate.json", name: "renovate.json" },
{ id: "readme.md", name: "README.md" },
],
},
})
```
### Remove Indentation
Set the css variable `--tree-indentation` to `0px` to remove the indentation of
the tree view.
```tsx
"use client"
import { TreeView, createTreeCollection } from "@chakra-ui/react"
import { LuFile, LuFolder } from "react-icons/lu"
export const TreeViewRemoveIndentation = () => {
return (
Tree
nodeState.isBranch ? (
{node.name}
) : (
{node.name}
)
}
/>
)
}
interface Node {
id: string
name: string
children?: Node[]
}
const collection = createTreeCollection({
nodeToValue: (node) => node.id,
nodeToString: (node) => node.name,
rootNode: {
id: "ROOT",
name: "",
children: [
{
id: "node_modules",
name: "node_modules",
children: [
{ id: "node_modules/zag-js", name: "zag-js" },
{ id: "node_modules/pandacss", name: "panda" },
{
id: "node_modules/@types",
name: "@types",
children: [
{ id: "node_modules/@types/react", name: "react" },
{ id: "node_modules/@types/react-dom", name: "react-dom" },
],
},
],
},
{
id: "src",
name: "src",
children: [
{ id: "src/app.tsx", name: "app.tsx" },
{ id: "src/index.ts", name: "index.ts" },
],
},
{ id: "panda.config", name: "panda.config.ts" },
{ id: "package.json", name: "package.json" },
{ id: "renovate.json", name: "renovate.json" },
{ id: "readme.md", name: "README.md" },
],
},
})
```
### Async Loading
Lazy loading is a feature that allows the tree view to load children of a node
on demand (or async). This helps to improve the initial load time and memory
usage.
To use this, you need to provide the following:
- `loadChildren` — A function that is used to load the children of a node.
- `onLoadChildrenComplete` — A callback that is called when the children of a
node are loaded. Used to update the tree collection.
- `childrenCount` — A number that indicates the number of children of a branch
node.
```tsx
"use client"
import { TreeView, createTreeCollection } from "@chakra-ui/react"
import { useState } from "react"
import { LuFile, LuFolder, LuLoaderCircle } from "react-icons/lu"
// mock api result
const response: Record = {
node_modules: [
{ id: "zag-js", name: "zag-js" },
{ id: "pandacss", name: "panda" },
{ id: "@types", name: "@types", childrenCount: 2 },
],
"node_modules/@types": [
{ id: "react", name: "react" },
{ id: "react-dom", name: "react-dom" },
],
src: [
{ id: "app.tsx", name: "app.tsx" },
{ id: "index.ts", name: "index.ts" },
],
}
// function to load children of a node
function loadChildren(
details: TreeView.LoadChildrenDetails,
): Promise {
const value = details.valuePath.join("/")
return new Promise((resolve) => {
setTimeout(() => {
resolve(response[value] ?? [])
}, 1200)
})
}
export const TreeViewAsync = () => {
const [collection, setCollection] = useState(initialCollection)
return (
setCollection(e.collection)}
>
Tree
indentGuide={
{nodeState.loading ? (
{node.name}
) : (
{node.name}
)
}
/>
)
}
interface Node {
id: string
name: string
children?: Node[]
childrenCount?: number
}
const initialCollection = createTreeCollection({
nodeToValue: (node) => node.id,
nodeToString: (node) => node.name,
rootNode: {
id: "ROOT",
name: "",
children: [
{ id: "node_modules", name: "node_modules", childrenCount: 3 },
{ id: "src", name: "src", childrenCount: 2 },
{ id: "panda.config", name: "panda.config.ts" },
{ id: "package.json", name: "package.json" },
{ id: "renovate.json", name: "renovate.json" },
{ id: "readme.md", name: "README.md" },
],
},
})
```
### Filtering
Filtering is useful when you have a large tree and you want to filter the nodes
to only show the ones that match the search query.
Here's an example that composes the `filter` method from the `TreeCollection`
and `useFilter` hook to filter the nodes.
```tsx
"use client"
import {
Highlight,
Input,
Stack,
TreeView,
createTreeCollection,
useFilter,
} from "@chakra-ui/react"
import { useState } from "react"
import { LuFile, LuFolder } from "react-icons/lu"
export const TreeViewWithFilter = () => {
const [collection, setCollection] = useState(initialCollection)
const [expanded, setExpanded] = useState([])
const [query, setQuery] = useState("")
const { contains } = useFilter({ sensitivity: "base" })
const search = (search: string) => {
setQuery(search)
const nextCollection = initialCollection.filter((node) =>
contains(node.name, search),
)
// update collection
setCollection(nextCollection)
// expand all branches
setExpanded(nextCollection.getBranchValues())
}
return (
setExpanded(details.expandedValue)}
>
Tree
{node.name}
) : (
{node.name}
)
}
/>
)
}
interface Node {
id: string
name: string
children?: Node[]
}
const initialCollection = createTreeCollection({
nodeToValue: (node) => node.id,
nodeToString: (node) => node.name,
rootNode: {
id: "ROOT",
name: "",
children: [
{
id: "node_modules",
name: "node_modules",
children: [
{ id: "node_modules/zag-js", name: "zag-js" },
{ id: "node_modules/pandacss", name: "panda" },
{
id: "node_modules/@types",
name: "@types",
children: [
{ id: "node_modules/@types/react", name: "react" },
{ id: "node_modules/@types/react-dom", name: "react-dom" },
],
},
],
},
{
id: "src",
name: "src",
children: [
{ id: "src/app.tsx", name: "app.tsx" },
{ id: "src/index.ts", name: "index.ts" },
],
},
{ id: "panda.config", name: "panda.config.ts" },
{ id: "package.json", name: "package.json" },
{ id: "renovate.json", name: "renovate.json" },
{ id: "readme.md", name: "README.md" },
],
},
})
```
### Collapse Animation
Use the `animateContent` prop to animate the tree view content expand/collapse
state.
```tsx
"use client"
import { TreeView, createTreeCollection } from "@chakra-ui/react"
import { LuFile, LuFolder } from "react-icons/lu"
export const TreeViewCollapseAnimation = () => {
return (
Tree
{node.name}
) : (
{node.name}
)
}
/>
)
}
interface Node {
id: string
name: string
children?: Node[]
}
const collection = createTreeCollection({
nodeToValue: (node) => node.id,
nodeToString: (node) => node.name,
rootNode: {
id: "ROOT",
name: "",
children: [
{
id: "node_modules",
name: "node_modules",
children: [
{ id: "node_modules/zag-js", name: "zag-js" },
{ id: "node_modules/pandacss", name: "panda" },
{
id: "node_modules/@types",
name: "@types",
children: [
{ id: "node_modules/@types/react", name: "react" },
{ id: "node_modules/@types/react-dom", name: "react-dom" },
],
},
],
},
{
id: "src",
name: "src",
children: [
{ id: "src/app.tsx", name: "app.tsx" },
{ id: "src/index.ts", name: "index.ts" },
],
},
{ id: "panda.config", name: "panda.config.ts" },
{ id: "package.json", name: "package.json" },
{ id: "renovate.json", name: "renovate.json" },
{ id: "readme.md", name: "README.md" },
],
},
})
```
### Expand/Collapse All
Provide controls to expand or collapse all nodes at once.
```tsx
"use client"
import {
Button,
ButtonGroup,
HStack,
TreeView,
createTreeCollection,
useTreeViewContext,
} from "@chakra-ui/react"
import { isEqual } from "es-toolkit"
import { useMemo } from "react"
import { LuFile, LuFolder } from "react-icons/lu"
const ExpandCollapseAll = () => {
const tree = useTreeViewContext()
const isAllExpanded = useMemo(
() => isEqual(tree.expandedValue, tree.collection.getBranchValues()),
[tree.expandedValue, tree.collection],
)
return (
tree.expand()}
hidden={isAllExpanded}
>
Expand all
tree.collapse()}
hidden={!isAllExpanded}
>
Collapse all
)
}
export const TreeViewExpandCollapseAll = () => {
return (
Tree
{node.name}
) : (
{node.name}
)
}
/>
)
}
interface Node {
id: string
name: string
children?: Node[]
}
const collection = createTreeCollection({
nodeToValue: (node) => node.id,
nodeToString: (node) => node.name,
rootNode: {
id: "ROOT",
name: "",
children: [
{
id: "node_modules",
name: "node_modules",
children: [
{ id: "node_modules/zag-js", name: "zag-js" },
{ id: "node_modules/pandacss", name: "panda" },
{
id: "node_modules/@types",
name: "@types",
children: [
{ id: "node_modules/@types/react", name: "react" },
{ id: "node_modules/@types/react-dom", name: "react-dom" },
],
},
],
},
{
id: "src",
name: "src",
children: [
{ id: "src/app.tsx", name: "app.tsx" },
{ id: "src/index.ts", name: "index.ts" },
],
},
{ id: "panda.config", name: "panda.config.ts" },
{ id: "package.json", name: "package.json" },
{ id: "renovate.json", name: "renovate.json" },
{ id: "readme.md", name: "README.md" },
],
},
})
```
### Store
Use the `useTreeView` hook to create the tree view store and pass it to the
`TreeView.RootProvider` component. This allows you to have maximum control over
the tree view programmatically.
```tsx
"use client"
import { TreeView, createTreeCollection, useTreeView } from "@chakra-ui/react"
import { LuFile, LuFolder } from "react-icons/lu"
export const TreeViewWithStore = () => {
const store = useTreeView({
collection,
defaultExpandedValue: [],
})
return (
Tree
{JSON.stringify(store.expandedValue)}
indentGuide={
{node.name}
) : (
{node.name}
)
}
/>
)
}
interface Node {
id: string
name: string
children?: Node[]
}
const collection = createTreeCollection({
nodeToValue: (node) => node.id,
nodeToString: (node) => node.name,
rootNode: {
id: "ROOT",
name: "",
children: [
{
id: "node_modules",
name: "node_modules",
children: [
{ id: "node_modules/zag-js", name: "zag-js" },
{ id: "node_modules/pandacss", name: "panda" },
{
id: "node_modules/@types",
name: "@types",
children: [
{ id: "node_modules/@types/react", name: "react" },
{ id: "node_modules/@types/react-dom", name: "react-dom" },
],
},
],
},
{
id: "src",
name: "src",
children: [
{ id: "src/app.tsx", name: "app.tsx" },
{ id: "src/index.ts", name: "index.ts" },
],
},
{ id: "panda.config", name: "panda.config.ts" },
{ id: "package.json", name: "package.json" },
{ id: "renovate.json", name: "renovate.json" },
{ id: "readme.md", name: "README.md" },
],
},
})
```
### Links
Render the tree items as links by leveraging the `asChild` prop on the
`TreeView.Item` component.
```tsx
"use client"
import { TreeView, createTreeCollection } from "@chakra-ui/react"
import { LuChevronRight, LuExternalLink, LuFile } from "react-icons/lu"
export const TreeViewWithLinks = () => {
return (
nodeState.isBranch ? (
{node.name}
) : (
{node.name}
{node.href?.startsWith("http") && (
)
}
/>
)
}
interface Node {
id: string
name: string
href?: string
children?: Node[]
}
const collection = createTreeCollection({
nodeToValue: (node) => node.id,
nodeToString: (node) => node.name,
rootNode: {
id: "ROOT",
name: "",
children: [
{
id: "docs",
name: "Documentation",
children: [
{
id: "docs/getting-started",
name: "Getting Started",
href: "/docs/getting-started",
},
{
id: "docs/installation",
name: "Installation",
href: "/docs/installation",
},
{
id: "docs/components",
name: "Components",
children: [
{
id: "docs/components/accordion",
name: "Accordion",
href: "/docs/components/accordion",
},
{
id: "docs/components/dialog",
name: "Dialog",
href: "/docs/components/dialog",
},
{
id: "docs/components/menu",
name: "Menu",
href: "/docs/components/menu",
},
],
},
],
},
{
id: "examples",
name: "Examples",
children: [
{
id: "examples/react",
name: "React Examples",
href: "/examples/react",
},
{ id: "examples/vue", name: "Vue Examples", href: "/examples/vue" },
{
id: "examples/solid",
name: "Solid Examples",
href: "/examples/solid",
},
],
},
{
id: "external",
name: "External Links",
children: [
{
id: "external/github",
name: "GitHub Repository",
href: "https://github.com/chakra-ui/zag",
},
{
id: "external/npm",
name: "NPM Package",
href: "https://www.npmjs.com/package/@zag-js/core",
},
{
id: "external/docs",
name: "Official Docs",
href: "https://zagjs.com",
},
],
},
{ id: "readme.md", name: "README.md", href: "/readme" },
{ id: "license", name: "LICENSE", href: "/license" },
],
},
})
```
### Multi Select
Add the `selectionMode="multiple"` prop to the `TreeView.Root` component to
enable multi-select functionality.
:::info
This mode requires a modifier key to be pressed to select multiple items.
- Hold `Ctrl` or `⌘` on macOS and click the items.
- Click an item, then hold `Shift` while clicking on another item.
:::
```tsx
"use client"
import { TreeView, createTreeCollection } from "@chakra-ui/react"
import { LuFile, LuFolder } from "react-icons/lu"
export const TreeViewMultiSelect = () => {
return (
Tree
indentGuide={
{node.name}
) : (
{node.name}
)
}
/>
)
}
interface Node {
id: string
name: string
children?: Node[]
}
const collection = createTreeCollection({
nodeToValue: (node) => node.id,
nodeToString: (node) => node.name,
rootNode: {
id: "ROOT",
name: "",
children: [
{
id: "node_modules",
name: "node_modules",
children: [
{ id: "node_modules/zag-js", name: "zag-js" },
{ id: "node_modules/pandacss", name: "panda" },
{
id: "node_modules/@types",
name: "@types",
children: [
{ id: "node_modules/@types/react", name: "react" },
{ id: "node_modules/@types/react-dom", name: "react-dom" },
],
},
],
},
{
id: "src",
name: "src",
children: [
{ id: "src/app.tsx", name: "app.tsx" },
{ id: "src/index.ts", name: "index.ts" },
],
},
{ id: "panda.config", name: "panda.config.ts" },
{ id: "package.json", name: "package.json" },
{ id: "renovate.json", name: "renovate.json" },
{ id: "readme.md", name: "README.md" },
],
},
})
```
### Checkbox Tree
Add checkboxes to tree nodes for selection functionality.
```tsx
"use client"
import {
Checkmark,
TreeView,
createTreeCollection,
useTreeViewNodeContext,
} from "@chakra-ui/react"
import { LuFile, LuFolder } from "react-icons/lu"
const TreeNodeCheckbox = (props: TreeView.NodeCheckboxProps) => {
const nodeState = useTreeViewNodeContext()
return (
)
}
export const TreeViewCheckbox = () => {
return (
Tree
nodeState.isBranch ? (
{node.name}
) : (
{node.name}
)
}
/>
)
}
interface Node {
id: string
name: string
children?: Node[]
}
const collection = createTreeCollection({
nodeToValue: (node) => node.id,
nodeToString: (node) => node.name,
rootNode: {
id: "ROOT",
name: "",
children: [
{
id: "node_modules",
name: "node_modules",
children: [
{ id: "node_modules/zag-js", name: "zag-js" },
{ id: "node_modules/pandacss", name: "panda" },
{
id: "node_modules/@types",
name: "@types",
children: [
{ id: "node_modules/@types/react", name: "react" },
{ id: "node_modules/@types/react-dom", name: "react-dom" },
],
},
],
},
{
id: "src",
name: "src",
children: [
{ id: "src/app.tsx", name: "app.tsx" },
{ id: "src/index.ts", name: "index.ts" },
],
},
{ id: "panda.config", name: "panda.config.ts" },
{ id: "package.json", name: "package.json" },
{ id: "renovate.json", name: "renovate.json" },
{ id: "readme.md", name: "README.md" },
],
},
})
```
### Mutation
Here's an example of how to design add/remove nodes in the tree view.
```tsx
"use client"
import {
HStack,
IconButton,
TreeView,
createTreeCollection,
useTreeViewContext,
} from "@chakra-ui/react"
import { useState } from "react"
import { LuFile, LuFolder, LuPlus, LuTrash } from "react-icons/lu"
export const TreeViewMutation = () => {
const [collection, setCollection] = useState(initialCollection)
const removeNode = (props: TreeNodeProps) => {
setCollection(collection.remove([props.indexPath]))
}
const addNode = (props: TreeNodeProps) => {
const { node, indexPath } = props
if (!collection.isBranchNode(node)) return
const children = [
{
id: `untitled-${Date.now()}`,
name: `untitled-${node.children?.length}.tsx`,
},
...(node.children || []),
]
setCollection(collection.replace(indexPath, { ...node, children }))
}
return (
Tree
{node.name}
) : (
{node.name}
)
}
/>
)
}
interface TreeNodeProps extends TreeView.NodeProviderProps {
onRemove?: (props: TreeView.NodeProviderProps) => void
onAdd?: (props: TreeView.NodeProviderProps) => void
}
const TreeNodeActions = (props: TreeNodeProps) => {
const { onRemove, onAdd, node } = props
const tree = useTreeViewContext()
const isBranch = tree.collection.isBranchNode(node)
return (
{
e.stopPropagation()
onRemove?.(props)
}}
>
{isBranch && (
{
e.stopPropagation()
onAdd?.(props)
tree.expand([node.id])
}}
>
)}
)
}
interface Node {
id: string
name: string
children?: Node[]
childrenCount?: number
}
const initialCollection = createTreeCollection({
nodeToValue: (node) => node.id,
nodeToString: (node) => node.name,
rootNode: {
id: "ROOT",
name: "",
children: [
{
id: "node_modules",
name: "node_modules",
children: [
{ id: "node_modules/zag-js", name: "zag-js" },
{ id: "node_modules/pandacss", name: "panda" },
{
id: "node_modules/@types",
name: "@types",
children: [
{ id: "node_modules/@types/react", name: "react" },
{ id: "node_modules/@types/react-dom", name: "react-dom" },
],
},
],
},
{
id: "src",
name: "src",
children: [
{ id: "src/app.tsx", name: "app.tsx" },
{ id: "src/index.ts", name: "index.ts" },
],
},
{ id: "panda.config", name: "panda.config.ts" },
{ id: "package.json", name: "package.json" },
{ id: "renovate.json", name: "renovate.json" },
{ id: "readme.md", name: "README.md" },
],
},
})
```
### Custom Icon
Here's an example of how to render a custom icon for the tree view based on its
data.
```tsx
"use client"
import { TreeView, createTreeCollection } from "@chakra-ui/react"
import { RxFrame, RxImage, RxSquare, RxText } from "react-icons/rx"
export const TreeViewCustomIcon = () => {
return (
Tree
nodeState.isBranch ? (
{node.name}
) : (
{node.name}
)
}
/>
)
}
const TreeViewNodeIcon = (props: { type: Node["type"] }) => {
switch (props.type) {
case "text":
return ({
nodeToValue: (node) => node.id,
nodeToString: (node) => node.name,
rootNode: {
id: "ROOT",
name: "",
type: "frame",
children: [
{
id: "page",
name: "Page",
type: "frame",
children: [
{
id: "header",
name: "Header",
type: "frame",
children: [
{ id: "logo", name: "Logo", type: "image" },
{ id: "nav", name: "Navigation", type: "text" },
],
},
],
},
{ id: "footer", name: "Footer", type: "text" },
{
id: "main",
name: "Main",
type: "frame",
children: [
{ id: "hero", name: "Hero Section", type: "text" },
{ id: "features", name: "Features", type: "text" },
],
},
],
},
})
```
## Props
### Root
| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| collection | undefined | `TreeCollection` | The collection of tree nodes |
| expandOnClick | true | `boolean` | Whether clicking on a branch should open it or not |
| hideMode | 'display-none' | `HideMode` | How to hide content when mounted but not present.
- `'display-none'`: HTML `hidden` attribute. Effects stay alive.
- `'activity'`: React 19 ``. Effects pause. Requires React 19+. |
| selectionMode | single | `'multiple' \| 'single'` | Whether the tree supports multiple selection
- "single": only one node can be selected
- "multiple": multiple nodes can be selected |
| typeahead | true | `boolean` | Whether the tree supports typeahead search |
| colorPalette | gray | `'gray' \| 'red' \| 'orange' \| 'yellow' \| 'green' \| 'teal' \| 'blue' \| 'cyan' \| 'purple' \| 'pink'` | The color palette of the component |
| size | md | `'md' \| 'sm' \| 'xs'` | The size of the component |
| variant | subtle | `'subtle' \| 'solid'` | The variant of the component |
| as | undefined | `React.ElementType` | The underlying element to render. |
| asChild | undefined | `boolean` | Use the provided child element as the default rendered element, combining their props and behavior. |
| unstyled | undefined | `boolean` | Whether to remove the component's style. |
| canRename | undefined | `(node: T, indexPath: IndexPath) => boolean` | Function to determine if a node can be renamed |
| checkedValue | undefined | `string[]` | The controlled checked node value |
| defaultCheckedValue | undefined | `string[]` | The initial checked node value when rendered.
Use when you don't need to control the checked node value. |
| defaultExpandedValue | undefined | `string[]` | The initial expanded node ids when rendered.
Use when you don't need to control the expanded node value. |
| defaultFocusedValue | undefined | `string` | The initial focused node value when rendered.
Use when you don't need to control the focused node value. |
| defaultSelectedValue | undefined | `string[]` | The initial selected node value when rendered.
Use when you don't need to control the selected node value. |
| expandedValue | undefined | `string[]` | The controlled expanded node ids |
| focusedValue | undefined | `string` | The value of the focused node |
| ids | undefined | `Partial<{ root: string; tree: string; label: string; node: (value: string) => string }>` | The ids of the tree elements. Useful for composition. |
| lazyMount | false | `boolean` | Whether to enable lazy mounting |
| loadChildren | undefined | `(details: LoadChildrenDetails) => Promise` | Function to load children for a node asynchronously.
When provided, branches will wait for this promise to resolve before expanding. |
| onBeforeRename | undefined | `(details: RenameCompleteDetails) => boolean` | Called before a rename is completed. Return false to prevent the rename. |
| onCheckedChange | undefined | `(details: CheckedChangeDetails) => void` | Called when the checked value changes |
| onExpandedChange | undefined | `(details: ExpandedChangeDetails) => void` | Called when the tree is opened or closed |
| onFocusChange | undefined | `(details: FocusChangeDetails) => void` | Called when the focused node changes |
| onLoadChildrenComplete | undefined | `(details: LoadChildrenCompleteDetails) => void` | Called when a node finishes loading children |
| onLoadChildrenError | undefined | `(details: LoadChildrenErrorDetails) => void` | Called when loading children fails for one or more nodes |
| onRenameComplete | undefined | `(details: RenameCompleteDetails) => void` | Called when a node label rename is completed |
| onRenameStart | undefined | `(details: RenameStartDetails) => void` | Called when a node starts being renamed |
| onSelectionChange | undefined | `(details: SelectionChangeDetails) => void` | Called when the selection changes |
| scrollToIndexFn | undefined | `(details: ScrollToIndexDetails) => void` | Function to scroll to a specific index.
Useful for virtualized tree views. |
| selectedValue | undefined | `string[]` | The controlled selected node value |
| translations | undefined | `IntlTranslations` | Specifies the localized strings that identifies the accessibility elements and their states |
| unmountOnExit | false | `boolean` | Whether to unmount on exit. |
| animateContent | undefined | `'true' \| 'false'` | The animateContent of the component |
### Node
| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| render | undefined | `(props` | undefined |
| indentGuide | undefined | `React.ReactElement` | undefined |
| renderBranch | undefined | `(props` | undefined |
| branchProps | undefined | `TreeViewBranchProps` | undefined |
| branchContentProps | undefined | `TreeViewBranchContentProps` | undefined |
| as | undefined | `React.ElementType` | The underlying element to render. |
| asChild | undefined | `boolean` | Use the provided child element as the default rendered element, combining their props and behavior. |
## Explorer
Explore the `TreeView` component parts interactively. Click on parts in the
sidebar to highlight them in the preview.
Notifications
)
}
```
## Usage
```jsx
import { VisuallyHidden } from "@chakra-ui/react"
```
```jsx
Hidden content
```
## Examples
### Input
Using the `asChild` prop, you can pass a child element to the `VisuallyHidden`
component.
```tsx
import { HStack, VisuallyHidden } from "@chakra-ui/react"
export const VisuallyHiddenWithInput = () => {
return (
The input is hidden
)
}
```
# Wrap
```tsx
import { Badge, Wrap } from "@chakra-ui/react"
export const WrapBasic = () => (
Badge 1
Badge 2
Badge 3
)
```
## Usage
By default, `Wrap` applies `display: flex`, `flex-wrap: wrap`, and `gap: 8px` to
its children.
```tsx
import { Wrap, WrapItem } from "@chakra-ui/react"
```
```tsx
```
## Examples
### Gap or Spacing
Pass the `gap` prop to apply a consistent spacing between each child, even if it
wraps.
```tsx
import { Wrap } from "@chakra-ui/react"
import { Box } from "@chakra-ui/react"
export const WrapWithGap = () => (
{Array.from({ length: 10 }).map((_, index) => (
)
```
### Alignment
Pass the `align` prop to change the alignment of the child along the cross axis.
```tsx
import { Center, Wrap, WrapItem } from "@chakra-ui/react"
export const WrapWithAlign = () => (
{Array.from({ length: 5 }).map((_, index) => (
Box {index + 1}
))}
)
```
### Justify
Pass the `justify` prop to change the alignment of the child along the main
axis.
```tsx
import { Center, Wrap, WrapItem } from "@chakra-ui/react"
export const WrapWithJustify = () => (
{Array.from({ length: 5 }).map((_, index) => (
Box {index + 1}
))}
)
```
### Row and Column Gap
Pass the `rowGap` and `columnGap` props to apply a consistent spacing between
the rows and columns.
```tsx
import { Wrap } from "@chakra-ui/react"
import { Box } from "@chakra-ui/react"
export const WrapWithRowColumnGap = () => (
{Array.from({ length: 10 }).map((_, index) => (
)
```
### Responsive
Use responsive values for the `gap`, `rowGap`, and `columnGap` props to apply
responsive spacing between each child.
```tsx
import { Wrap } from "@chakra-ui/react"
import { Box } from "@chakra-ui/react"
export const WrapResponsive = () => (
)
```
# CLI
The Chakra UI CLI can be used to generate typings for your custom theme tokens,
like colors, semantic tokens, recipe variants, etc. You can also add community
snippets and premium Pro blocks to your project.
## Installation
In order to use the CLI, you need to install it as a dev dependency in your
project:
:::code-group
```bash [npm]
npm i -D @chakra-ui/cli
```
```bash [pnpm]
pnpm add -D @chakra-ui/cli
```
```bash [bun]
bun add -d @chakra-ui/cli
```
:::
:::warning
To use the CLI tool, please ensure that the version of Node.js is `>= 20.6.0`.
:::
## Usage
Use the Chakra CLI to run any of the commands listed below with your preferred
package manager.
```bash
Usage: npx chakra [options] [command]
The official CLI for Chakra UI projects
Options:
-V, --version output the version number
-h, --help display help for command
Commands:
typegen [options] Generate theme and recipe typings
snippet Add snippets to your project for better DX
blocks Add Chakra UI Pro blocks to your project
eject [options] Take control over the default theme tokens and recipes
help [command] display help for command
```
## `chakra typegen`
Generates theme and recipe typings for your custom theme. This helps to provide
autocompletion and type safety in your project.
```bash
# Generate typings
chakra typegen src/theme.ts
# Watch for changes and rebuild
chakra typegen src/theme.ts --watch
# Generate strict types for props variant and size
chakra typegen src/theme.ts --strict
```
### When to run typegen
The `typegen` command works in both **development** and **CI/CD**. It is not
limited to local use—run it everywhere your project is built or installed so
generated types stay up to date.
### Is typegen required?
Run `typegen` if all of these are true:
- You use TypeScript
- You customize the Chakra system (tokens, semantic tokens, recipes, slot
recipes, etc.)
- You want type-safe autocompletion and strict token validation
If you're using JavaScript only, or TypeScript without custom Chakra theme
types, `typegen` is optional.
### Workflow integration
Add `typegen` to the `postinstall` or `prepare` script of the frontend
application that uses Chakra UI. This keeps types generated:
- After `npm install` / `pnpm install` / `bun install` (local development)
- During CI/CD when dependencies are installed before build
- In production builds when running `npm ci` or similar
```json
{
"scripts": {
"postinstall": "chakra typegen src/theme.ts",
"prepare": "chakra typegen src/theme.ts"
}
}
```
:::tip
Use `postinstall` if you want types after every install. Use `prepare` if you
also want it to run when the package is packed (for publishing). Pick one to
avoid running `typegen` twice.
:::
### CI/CD strategy
Run `typegen` before type-checking and build steps in CI.
```json
{
"scripts": {
"typegen": "chakra typegen src/theme.ts",
"typecheck": "npm run typegen && tsc --noEmit",
"build": "npm run typegen && your-build-command"
}
}
```
This prevents CI failures caused by stale or missing Chakra types.
### Monorepo setup
In a monorepo (e.g. pnpm workspaces), run `typegen` **in the package that
depends on Chakra UI**—typically your frontend application—not at the monorepo
root.
1. Install `@chakra-ui/cli` as a dev dependency in the frontend package.
2. Add the `postinstall` or `prepare` script to that package's `package.json`.
```json
// packages/frontend/package.json
{
"scripts": {
"postinstall": "chakra typegen src/theme.ts"
},
"dependencies": {
"@chakra-ui/react": "..."
},
"devDependencies": {
"@chakra-ui/cli": "..."
}
}
```
When you run `pnpm install` at the root, that frontend package's `postinstall`
runs and generates types in the right place.
### Should generated types be committed?
By default, no. The CLI writes generated files to Chakra's installed package
types directory (`node_modules/@chakra-ui/react/types/styled-system/generated`),
which should not be committed.
If you use a custom `--outdir` inside your repository, follow your team's
codegen policy. In most cases, regenerating in CI is better than committing
generated files.
## `chakra snippet`
Generates useful component compositions that boost your development speed.
```bash
# Add all snippets
chakra snippet add --all
# Add a specific snippet
chakra snippet add button
# List all available snippets
chakra snippet list
# Specify a custom directory
chakra snippet add dialog --outdir ./components/custom
```
## `chakra blocks`
Add premium blocks from Chakra UI Pro to your project. These are professionally
designed, fully responsive components that you can customize for your needs.
```bash
# Interactive block selection
chakra blocks add
# Add all variants of a specific block
chakra blocks add hero
# Add a specific variant of a block
chakra blocks add hero --variant "simple"
# List available blocks
chakra blocks list
# List blocks in a specific category
chakra blocks list --category "marketing"
# Preview blocks without downloading
chakra blocks add --dry-run --category "marketing"
# Specify output directory
chakra blocks add --outdir ./components/blocks
```
### Pro API Key Setup
To use Pro blocks, you need a Chakra UI Pro subscription and API key:
1. Get your API key from [Chakra UI Pro](https://pro.chakra-ui.com)
2. Set the environment variable:
```bash
export CHAKRA_UI_PRO_API_KEY="your-api-key"
```
Or create a `.env` file in your project root:
```env
CHAKRA_UI_PRO_API_KEY=your-api-key
```
3. Add it to your shell profile (`.bashrc`, `.zshrc`, etc.) for persistence if
using environment variables
### Available Options
- `--variant `: Add a specific variant instead of all variants
- `--outdir `: Specify output directory for blocks
- `--force`: Overwrite existing files
- `--dry-run`: Preview what will be downloaded without writing files
- `--tsx`: Force TypeScript JSX format (auto-detected by default)
## `chakra eject`
Generates the file(s) that contain the default theme tokens and recipes so you
can have full control over them.
```bash
# Copy the tokens and recipes to your project
chakra eject --outdir src/theme
```
## FAQ
### Is typegen only for local development?
No. The `typegen` command works in both development and CI/CD. Add it to
`postinstall` or `prepare` so it runs after installs—locally and in your CI
pipeline.
### Does strictTokens require typegen?
Yes. If you enable `strictTokens`, run `typegen` in local and CI workflows so
token types stay in sync with your theme.
### Autocomplete for custom tokens not working?
After generating the typings, you need to "Restart TS Server" for the
autocomplete to show up.
Alternatively, you can install the `@chakra-ui/cli` package locally as a dev
dependency and run the `chakra typegen` command to generate the typings.
# Contributing to Chakra UI
Thanks for showing interest to contribute to Chakra UI 💖, you rock!
## Overview
Here are a few ways you can help improve Chakra UI
- **Improve the documentation**: Add new demos, fix typos, or add missing
information.
- **Add new demos**: Add new component demos to the website and storybook. Open
a PR to `apps/compositions/src/examples`
- **Fix bugs**: Report bugs, fix bugs, or add missing features.
- **Contribute to the code**: Propose new features by opening a Github
Discussion, or find existing bugs to work on.
- **Improve the code**: Improve the code, fix bugs, or add missing features.
:::info
We welcome all contributions, no matter how big or small.
:::
## Architecture
Chakra v3.x is a composition of two projects in the Chakra ecosystem, Ark UI and
Zag.js. The goal is to maintain as little code as possible in Chakra UI, and
delegate the heavy lifting to these projects.
:::card-group