# ButtonGroup
**Category**: react
**URL**: https://v3.heroui.com/en/docs/react/components/button-group
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(buttons)/button-group.mdx
> Group related buttons together with consistent styling and spacing
## Import
```tsx
import { ButtonGroup, Button } from '@heroui/react';
```
### Usage
```tsx
import {
ChevronDown,
ChevronLeft,
ChevronRight,
CodeFork,
Ellipsis,
Picture,
Pin,
QrCode,
Star,
TextAlignCenter,
TextAlignJustify,
TextAlignLeft,
TextAlignRight,
ThumbsDown,
ThumbsUp,
Video,
} from "@gravity-ui/icons";
import {Button, ButtonGroup, Chip, Description, Dropdown, Label} from "@heroui/react";
export function Basic() {
return (
{/* Single button with dropdown */}
All commits from this branch will be added to the base branch
The 14 commits from this branch will be combined into one commit in the base
branch
The 14 commits from this branch will be rebased and added to the base branch
{/* Individual buttons */}
{/* Previous/Next Button Group */}
{/* Content Selection Button Group */}
{/* Text Alignment Button Group */}
{/* Icon-Only Alignment Button Group */}
);
}
```
### Anatomy
Import the ButtonGroup component and access all parts using dot notation.
```tsx
import { ButtonGroup, Button } from '@heroui/react';
export default () => (
);
```
> **ButtonGroup** wraps multiple Button components together, applying consistent styling, spacing, and automatic border radius handling. It uses React Context to pass `size`, `variant`, and `isDisabled` props to all child buttons.
### Variants
```tsx
import {Button, ButtonGroup} from "@heroui/react";
export function Variants() {
return (
Primary
Secondary
Tertiary
Outline
Ghost
Danger
);
}
```
### Sizes
```tsx
import {Button, ButtonGroup} from "@heroui/react";
export function Sizes() {
return (
Small
Medium (default)
Large
);
}
```
### Orientation
Use the `orientation` prop to arrange buttons horizontally or vertically.
```tsx
import {TextAlignCenter, TextAlignJustify, TextAlignLeft, TextAlignRight} from "@gravity-ui/icons";
import {Button, ButtonGroup} from "@heroui/react";
export function Orientation() {
return (
Horizontal
Vertical
);
}
```
### With Icons
```tsx
import {Globe, Plus, TrashBin} from "@gravity-ui/icons";
import {Button, ButtonGroup} from "@heroui/react";
export function WithIcons() {
return (
With icons
Icon only buttons
);
}
```
### Full Width
```tsx
import {TextAlignCenter, TextAlignLeft, TextAlignRight} from "@gravity-ui/icons";
import {Button, ButtonGroup} from "@heroui/react";
export function FullWidth() {
return (
);
}
```
### Disabled State
```tsx
import {Button, ButtonGroup} from "@heroui/react";
export function Disabled() {
return (
All buttons disabled
Group disabled, but one button overrides
);
}
```
### Without Separator
Simply omit the `` component from your buttons.
```tsx
import {Button, ButtonGroup} from "@heroui/react";
export function WithoutSeparator() {
return (
);
}
```
## Related Components
* **Button**: Allows a user to perform an action
* **Dropdown**: Context menu with actions and options
* **Chip**: Compact elements for tags and filters
## Styling
### Passing Tailwind CSS classes
```tsx
import { ButtonGroup, Button } from '@heroui/react';
function CustomButtonGroup() {
return (
);
}
```
### Customizing the component classes
To customize the ButtonGroup component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
```css
@layer components {
.button-group {
@apply gap-2 rounded-lg;
}
.button-group__separator {
@apply opacity-25;
}
}
```
HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
### CSS Classes
The ButtonGroup component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/button-group.css)):
#### Base Classes
* `.button-group` - Base button group container
* `.button-group--full-width` - Full width modifier
* `.button-group__separator` - Separator element between buttons
The ButtonGroup component automatically applies border radius to buttons:
* First button gets rounded left/start edge
* Last button gets rounded right/end edge
* Middle buttons have no border radius
* Single button gets full border radius on all edges
Add `` inside each Button (except the first) to show dividers between buttons.
## API Reference
### ButtonGroup Props
| Prop | Type | Default | Description |
| ------------- | --------------------------------------------------------------- | -------------- | --------------------------------------------------------------------------------------- |
| `variant` | `'primary' \| 'secondary' \| 'tertiary' \| 'ghost' \| 'danger'` | - | Visual style variant applied to all buttons in the group |
| `size` | `'sm' \| 'md' \| 'lg'` | - | Size applied to all buttons in the group |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | The orientation of the button group |
| `fullWidth` | `boolean` | `false` | Whether the button group should take full width of its container |
| `isDisabled` | `boolean` | `false` | Whether all buttons in the group are disabled (can be overridden on individual buttons) |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Button components to group together |
### ButtonGroup.Separator Props
| Prop | Type | Default | Description |
| ----------- | -------- | ------- | ---------------------- |
| `className` | `string` | - | Additional CSS classes |
### Notes
* ButtonGroup uses React Context to pass `size`, `variant`, and `isDisabled` props to all child Button components
* **Only direct child buttons receive the ButtonGroup props** - Buttons nested inside other components (like Modal, Dropdown, etc.) will not inherit the group's props even if they are descendants of the ButtonGroup
* Individual Button components can override the group's `isDisabled` prop by setting `isDisabled={false}`
* The component automatically handles border radius between buttons
* Add `` inside each Button (except the first) to show dividers between buttons
* Buttons in a group have their active/pressed scale transform removed for a more cohesive appearance
# Button
**Category**: react
**URL**: https://v3.heroui.com/en/docs/react/components/button
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(buttons)/button.mdx
> A clickable button component with multiple variants and states
## Import
```tsx
import { Button } from '@heroui/react';
```
### Usage
```tsx
"use client";
import {Button} from "@heroui/react";
export function Basic() {
return ;
}
```
### Variants
```tsx
import {Button} from "@heroui/react";
export function Variants() {
return (
);
}
```
### With Icons
```tsx
import {Envelope, Globe, Plus, TrashBin} from "@gravity-ui/icons";
import {Button} from "@heroui/react";
export function WithIcons() {
return (
);
}
```
### Icon Only
```tsx
import {Ellipsis, Gear, TrashBin} from "@gravity-ui/icons";
import {Button} from "@heroui/react";
export function IconOnly() {
return (
);
}
```
### Loading
```tsx
"use client";
import {Button, Spinner} from "@heroui/react";
import React from "react";
export function Loading() {
return (
);
}
```
### Loading State
```tsx
"use client";
import {Paperclip} from "@gravity-ui/icons";
import {Button, Spinner} from "@heroui/react";
import React, {useState} from "react";
export function LoadingState() {
const [isLoading, setLoading] = useState(false);
const handlePress = () => {
setLoading(true);
setTimeout(() => setLoading(false), 2000);
};
return (
);
}
```
### Sizes
```tsx
import {Button} from "@heroui/react";
export function Sizes() {
return (
);
}
```
### Full Width
```tsx
import {Plus} from "@gravity-ui/icons";
import {Button} from "@heroui/react";
export function FullWidth() {
return (
);
}
```
### Disabled State
```tsx
import {Button} from "@heroui/react";
export function Disabled() {
return (
);
}
```
### Social Buttons
```tsx
import {Button} from "@heroui/react";
import {Icon} from "@iconify/react";
export function Social() {
return (
);
}
```
### Custom Render Function
```tsx
"use client";
import {Button} from "@heroui/react";
export function CustomRenderFunction() {
return (
);
}
```
## Related Components
* **Popover**: Displays content in context with a trigger
* **Tooltip**: Contextual information on hover or focus
* **Form**: Form validation and submission handling
## Styling
### Passing Tailwind CSS classes
```tsx
import { Button } from '@heroui/react';
function CustomButton() {
return (
);
}
```
### Customizing the component classes
To customize the Button component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
```css
@layer components {
.button {
@apply bg-purple-500 text-white hover:bg-purple-600;
}
.button--icon-only {
@apply rounded-lg bg-blue-500;
}
}
```
HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
### Adding custom variants
You can extend HeroUI components by wrapping them and adding your own custom variants.
```tsx
import type {ButtonProps} from "@heroui/react";
import type {VariantProps} from "tailwind-variants";
import {Button, buttonVariants} from "@heroui/react";
import {tv} from "tailwind-variants";
const myButtonVariants = tv({
base: "text-md font-semibold shadow-md text-shadow-lg data-[pending=true]:opacity-40",
defaultVariants: {
radius: "full",
variant: "primary",
},
extend: buttonVariants,
variants: {
radius: {
full: "rounded-full",
lg: "rounded-lg",
md: "rounded-md",
sm: "rounded-sm",
},
size: {
lg: "h-12 px-8",
md: "h-11 px-6",
sm: "h-10 px-4",
xl: "h-13 px-10",
},
variant: {
primary: "text-white dark:bg-white/10 dark:text-white dark:hover:bg-white/15",
},
},
});
type MyButtonVariants = VariantProps;
export type MyButtonProps = Omit &
MyButtonVariants & {className?: string};
function CustomButton({className, radius, variant, ...props}: MyButtonProps) {
return ;
}
export function CustomVariants() {
return Custom Button;
}
```
### Adding Ripple Effect
The Button component supports ripple effects through composition, allowing you to nest ripple components as children. This example uses [m3-ripple](https://github.com/saltyaom/m3-ripple).
```tsx
"use client";
import {Button} from "@heroui/react";
import {Ripple} from "m3-ripple";
import "m3-ripple/ripple.css";
export function RippleEffect() {
return (
);
}
```
### CSS Classes
The Button component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/button.css)):
#### Base & Size Classes
* `.button` - Base button styles
* `.button--sm` - Small size variant
* `.button--md` - Medium size variant
* `.button--lg` - Large size variant
#### Variant Classes
* `.button--primary`
* `.button--secondary`
* `.button--tertiary`
* `.button--outline`
* `.button--ghost`
* `.button--danger`
#### Modifier Classes
* `.button--icon-only`
* `.button--icon-only.button--sm`
* `.button--icon-only.button--lg`
### Interactive States
The button supports both CSS pseudo-classes and data attributes for flexibility:
* **Hover**: `:hover` or `[data-hovered="true"]`
* **Active/Pressed**: `:active` or `[data-pressed="true"]` (includes scale transform)
* **Focus**: `:focus-visible` or `[data-focus-visible="true"]` (shows focus ring)
* **Disabled**: `:disabled` or `[aria-disabled="true"]` (reduced opacity, no pointer events)
* **Pending**: `[data-pending]` (no pointer events during loading)
## API Reference
### Button Props
| Prop | Type | Default | Description |
| ------------ | ---------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------- |
| `variant` | `'primary' \| 'secondary' \| 'tertiary' \| 'outline' \| 'ghost' \| 'danger'` | `'primary'` | Visual style variant |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size of the button |
| `fullWidth` | `boolean` | `false` | Whether the button should take full width of its container |
| `isDisabled` | `boolean` | `false` | Whether the button is disabled |
| `isPending` | `boolean` | `false` | Whether the button is in a loading state |
| `isIconOnly` | `boolean` | `false` | Whether the button contains only an icon |
| `onPress` | `(e: PressEvent) => void` | - | Handler called when the button is pressed |
| `children` | `React.ReactNode \| (values: ButtonRenderProps) => React.ReactNode` | - | Button content or render prop |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
### ButtonRenderProps
When using the render prop pattern, these values are provided:
| Prop | Type | Description |
| ---------------- | --------- | ---------------------------------------------- |
| `isPending` | `boolean` | Whether the button is in a loading state |
| `isPressed` | `boolean` | Whether the button is currently pressed |
| `isHovered` | `boolean` | Whether the button is hovered |
| `isFocused` | `boolean` | Whether the button is focused |
| `isFocusVisible` | `boolean` | Whether the button should show focus indicator |
| `isDisabled` | `boolean` | Whether the button is disabled |
# CloseButton
**Category**: react
**URL**: https://v3.heroui.com/en/docs/react/components/close-button
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(buttons)/close-button.mdx
> Button component for closing dialogs, modals, or dismissing content
## Import
```tsx
import { CloseButton } from "@heroui/react";
```
### Usage
```tsx
import {CloseButton} from "@heroui/react";
export function Default() {
return ;
}
```
### With Custom Icon
```tsx
import {CircleXmark, Xmark} from "@gravity-ui/icons";
import {CloseButton} from "@heroui/react";
export function WithCustomIcon() {
return (
Custom Icon
Alternative Icon
);
}
```
### Interactive
```tsx
"use client";
import {CloseButton} from "@heroui/react";
import {useState} from "react";
export function Interactive() {
const [count, setCount] = useState(0);
return (
setCount(count + 1)}
/>
Clicked: {count} times
);
}
```
## Related Components
* **Alert**: Display important messages and notifications
* **AlertDialog**: Critical confirmations requiring user attention
* **Chip**: Compact elements for tags and filters
## Styling
### Passing Tailwind CSS classes
```tsx
import {CloseButton} from "@heroui/react";
function CustomCloseButton() {
return Close;
}
```
### Customizing the component classes
To customize the CloseButton component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
```css
@layer components {
.close-button {
@apply bg-red-100 text-red-800 hover:bg-red-200;
}
.close-button--custom {
@apply rounded-full border-2 border-red-300;
}
}
```
HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
### CSS Classes
The CloseButton component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/close-button.css)):
#### Base Classes
* `.close-button` - Base component styles
#### Variant Classes
* `.close-button--default` - Default variant
### Interactive States
The component supports both CSS pseudo-classes and data attributes for flexibility:
* **Hover**: `:hover` or `[data-hovered="true"]`
* **Active/Pressed**: `:active` or `[data-pressed="true"]`
* **Focus**: `:focus-visible` or `[data-focus-visible="true"]`
* **Disabled**: `:disabled` or `[aria-disabled="true"]`
## API Reference
### CloseButton Props
| Prop | Type | Default | Description |
| ------------ | ----------------------- | --------------- | ------------------------------------------- |
| `variant` | `"default"` | `"default"` | Visual variant of the button |
| `children` | `ReactNode \| function` | `` | Content to display (defaults to close icon) |
| `onPress` | `() => void` | - | Handler called when the button is pressed |
| `isDisabled` | `boolean` | `false` | Whether the button is disabled |
### React Aria Button Props
CloseButton extends all React Aria Button props. Common props include:
| Prop | Type | Description |
| ------------------ | -------- | --------------------------------------- |
| `aria-label` | `string` | Accessible label for screen readers |
| `aria-labelledby` | `string` | ID of element that labels the button |
| `aria-describedby` | `string` | ID of element that describes the button |
### RenderProps
When using the render prop pattern, these values are provided:
| Prop | Type | Description |
| ------------ | --------- | ------------------------------ |
| `isHovered` | `boolean` | Whether the button is hovered |
| `isPressed` | `boolean` | Whether the button is pressed |
| `isFocused` | `boolean` | Whether the button is focused |
| `isDisabled` | `boolean` | Whether the button is disabled |
# ToggleButtonGroup
**Category**: react
**URL**: https://v3.heroui.com/en/docs/react/components/toggle-button-group
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(buttons)/toggle-button-group.mdx
> Groups multiple ToggleButtons into a unified control, allowing users to select one or multiple options.
## Import
```tsx
import { ToggleButtonGroup, ToggleButton } from '@heroui/react';
```
### Usage
```tsx
import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons";
import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
export function Basic() {
return (
);
}
```
### Anatomy
Import the ToggleButtonGroup component and access all parts using dot notation.
```tsx
import { ToggleButtonGroup, ToggleButton } from '@heroui/react';
export default () => (
First
Second
Third
);
```
### Sizes
```tsx
import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons";
import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
export function Sizes() {
return (
Small
Medium (default)
Large
);
}
```
### Orientation
```tsx
import {Bold, Italic, Underline} from "@gravity-ui/icons";
import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
export function Orientation() {
return (
Horizontal
Vertical
);
}
```
### Detached
Use `isDetached` to separate buttons with gaps instead of connecting them.
```tsx
import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons";
import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
export function Attached() {
return (
Attached (default)
Detached
);
}
```
### Full Width
```tsx
import {
Bold,
Italic,
Strikethrough,
TextAlignCenter,
TextAlignLeft,
TextAlignRight,
Underline,
} from "@gravity-ui/icons";
import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
export function FullWidth() {
return (
Left
Center
Right
);
}
```
### Selection Mode
Use `selectionMode="single"` for mutually exclusive choices or `selectionMode="multiple"` for independent toggles.
```tsx
import {
Bold,
Italic,
Strikethrough,
TextAlignCenter,
TextAlignLeft,
TextAlignRight,
Underline,
} from "@gravity-ui/icons";
import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
export function SelectionMode() {
return (
Single selection
Left
Center
Right
Multiple selection
);
}
```
### Controlled
```tsx
"use client";
import type {Key} from "@heroui/react";
import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons";
import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
import {useState} from "react";
export function Controlled() {
const [selectedKeys, setSelectedKeys] = useState(new Set(["bold"]));
return (
);
}
```
### Anatomy
Import the ListBox component and access all parts using dot notation.
```tsx
import { ListBox, Label, Description, Header } from '@heroui/react';
export default () => (
)
```
### With Sections
```tsx
"use client";
import {Pencil, SquarePlus, TrashBin} from "@gravity-ui/icons";
import {Description, Header, Kbd, Label, ListBox, Separator, Surface} from "@heroui/react";
export function WithSections() {
return (
alert(`Selected item: ${key}`)}
>
Actions
Create a new file
N
Make changes
EDanger zone
Move to trash
D
);
}
```
### Multi Select
```tsx
import {Avatar, Description, Label, ListBox, Surface} from "@heroui/react";
export function MultiSelect() {
return (
B
bob@heroui.com
F
fred@heroui.com
M
martha@heroui.com
);
}
```
### With Disabled Items
```tsx
"use client";
import {Pencil, SquarePlus, TrashBin} from "@gravity-ui/icons";
import {Description, Header, Kbd, Label, ListBox, Separator, Surface} from "@heroui/react";
export function WithDisabledItems() {
return (
alert(`Selected item: ${key}`)}
>
Actions
Create a new file
N
Make changes
EDanger zone
Move to trash
D
);
}
```
### Custom Check Icon
```tsx
"use client";
import {Check} from "@gravity-ui/icons";
import {Avatar, Description, Label, ListBox, Surface} from "@heroui/react";
export function CustomCheckIcon() {
return (
B
bob@heroui.com
{({isSelected}) =>
isSelected ? : null
}
F
fred@heroui.com
{({isSelected}) =>
isSelected ? : null
}
M
martha@heroui.com
{({isSelected}) =>
isSelected ? : null
}
);
}
```
### Controlled
```tsx
"use client";
import type {Selection} from "@heroui/react";
import {Check} from "@gravity-ui/icons";
import {Avatar, Description, Label, ListBox, Surface} from "@heroui/react";
import {useState} from "react";
export function Controlled() {
const [selected, setSelected] = useState(new Set(["1"]));
const selectedItems = Array.from(selected);
return (
list.setSelectedKeys(keys)}
>
No team members}
>
{(user) => (
{user.fallback}
{user.name}
)}
Select team members for your project
{list.selectedKeys !== "all" && Array.from(list.selectedKeys).length > 0 && (
Selected:
{Array.from(list.selectedKeys).map((key) => {
const user = list.getItem(key);
if (!user) return null;
return (
{user.fallback}{user.name}
);
})}
)}
);
}
```
### Custom Render Function
```tsx
"use client";
import {PlanetEarth, Rocket, ShoppingBag, SquareArticle} from "@gravity-ui/icons";
import {Tag, TagGroup} from "@heroui/react";
export function CustomRenderFunction() {
return (
}
selectionMode="single"
>
News
Travel
Gaming
Shopping
);
}
```
## Related Components
* **Label**: Accessible label for form controls
* **Description**: Helper text for form fields
* **ErrorMessage**: Displays validation error messages for components with validation support
## Styling
### Passing Tailwind CSS classes
```tsx
import { TagGroup, Tag, Label } from '@heroui/react';
function CustomTagGroup() {
return (
Custom Styled
);
}
```
### Customizing the component classes
To customize the TagGroup component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
```css
@layer components {
.tag-group {
@apply flex flex-col gap-2;
}
.tag-group__list {
@apply flex flex-wrap gap-2;
}
.tag {
@apply rounded-full px-3 py-1;
}
.tag__remove-button {
@apply ml-1;
}
}
```
HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
### CSS Classes
The TagGroup component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/tag-group.css) and [tag.css](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/tag.css)):
#### Base Classes
* `.tag-group` - Base tag group container
* `.tag-group__list` - Container for the list of tags
* `.tag` - Base tag styles
* `.tag__remove-button` - Remove button trigger
#### Slot Classes
* `.tag-group [slot="description"]` - Description slot styles
* `.tag-group [slot="errorMessage"]` - ErrorMessage slot styles
#### Size Classes
* `.tag--sm` - Small size tag
* `.tag--md` - Medium size tag (default)
* `.tag--lg` - Large size tag
#### Variant Classes
* `.tag--default` - Default variant
* `.tag--surface` - Surface variant with surface background
#### State Classes
* `.tag[data-selected="true"]` - Selected tag state
* `.tag[data-disabled="true"]` - Disabled tag state
* `.tag[data-hovered="true"]` - Hovered tag state
* `.tag[data-pressed="true"]` - Pressed tag state
* `.tag[data-focus-visible="true"]` - Focused tag state (keyboard focus)
### Interactive States
The component supports both CSS pseudo-classes and data attributes for flexibility:
* **Hover**: `:hover` or `[data-hovered="true"]` on tag
* **Focus**: `:focus-visible` or `[data-focus-visible="true"]` on tag
* **Pressed**: `:active` or `[data-pressed="true"]` on tag
* **Selected**: `[data-selected="true"]` or `[aria-selected="true"]` on tag
* **Disabled**: `:disabled` or `[data-disabled="true"]` on tag
## API Reference
### TagGroup Props
| Prop | Type | Default | Description |
| --------------------- | ----------------------------------------------------------------- | ----------- | ---------------------------------------------------------------- |
| `selectionMode` | `"none" \| "single" \| "multiple"` | `"none"` | The type of selection that is allowed |
| `selectedKeys` | `Selection` | - | The currently selected keys (controlled) |
| `defaultSelectedKeys` | `Selection` | - | The initial selected keys (uncontrolled) |
| `onSelectionChange` | `(keys: Selection) => void` | - | Handler called when the selection changes |
| `disabledKeys` | `Iterable` | - | Keys of disabled tags |
| `isDisabled` | `boolean` | - | Whether the tag group is disabled |
| `onRemove` | `(keys: Set) => void` | - | Handler called when tags are removed |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size of the tags in the group |
| `variant` | `"default" \| "surface"` | `"default"` | Visual variant of the tags |
| `className` | `string` | - | Additional CSS classes |
| `children` | `ReactNode \| RenderFunction` | - | TagGroup content or render function |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
### TagGroup.List Props
| Prop | Type | Default | Description |
| ------------------ | -------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------- |
| `items` | `Iterable` | - | The items to display in the tag list |
| `renderEmptyState` | `() => ReactNode` | - | Function to render when the list is empty |
| `className` | `string` | - | Additional CSS classes |
| `children` | `ReactNode \| RenderFunction` | - | TagList content or render function |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
### Tag Props
| Prop | Type | Default | Description |
| ------------ | ---------------------------------------------------------------------- | ------- | -------------------------------------------------------------------- |
| `id` | `Key` | - | The unique identifier for the tag |
| `textValue` | `string` | - | A string representation of the tag's content, used for accessibility |
| `isDisabled` | `boolean` | - | Whether the tag is disabled |
| `className` | `string` | - | Additional CSS classes |
| `children` | `ReactNode \| RenderFunction` | - | Tag content or render function |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
**Note**: `size`, `variant` are inherited from the parent `TagGroup` component and cannot be set directly on individual `Tag` components.
### Tag.RemoveButton Props
| Prop | Type | Default | Description |
| ----------- | ----------- | ------- | ----------------------------------------------------- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `ReactNode` | - | Custom remove button content (defaults to close icon) |
**Note**: The `Tag.RemoveButton` component supports customization similar to `SearchField.ClearButton`. When `onRemove` is provided to `TagGroup`:
* **Auto-rendering**: If no custom `Tag.RemoveButton` is included in the `Tag` children, a default remove button is automatically rendered.
* **Custom button**: If a custom `Tag.RemoveButton` is provided as a child of `Tag`, it will be used instead of the auto-rendered button.
* **Custom icon**: You can pass custom content (like icons) to `Tag.RemoveButton` children to customize the appearance.
**Example - Auto-rendered (default)**:
```tsx
News
{/* Remove button is automatically rendered */}
```
**Example - Custom RemoveButton with icon**:
```tsx
News
```
**Example - Custom RemoveButton in render props**:
```tsx
{(renderProps) => (
<>
News
{!!renderProps.allowsRemoving && (
)}
)}
```
### RenderProps
When using render functions with TagGroup.List, these values are provided:
| Prop | Type | Description |
| ---------------- | --------- | ---------------------------------- |
| `isSelected` | `boolean` | Whether the tag is selected |
| `isDisabled` | `boolean` | Whether the tag is disabled |
| `isHovered` | `boolean` | Whether the tag is hovered |
| `isPressed` | `boolean` | Whether the tag is pressed |
| `isFocused` | `boolean` | Whether the tag is focused |
| `isFocusVisible` | `boolean` | Whether the tag has keyboard focus |
# ColorArea
**Category**: react
**URL**: https://v3.heroui.com/en/docs/react/components/color-area
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(colors)/color-area.mdx
> A 2D color picker that allows users to select colors from a gradient area
## Import
```tsx
import { ColorArea } from '@heroui/react';
```
### Usage
```tsx
import {ColorArea} from "@heroui/react";
export function ColorAreaBasic() {
return (
);
}
```
### Anatomy
```tsx
import { ColorArea } from '@heroui/react';
export default () => (
);
```
### With Dots
```tsx
import {ColorArea} from "@heroui/react";
export function ColorAreaWithDots() {
return (
);
}
```
### Controlled
```tsx
"use client";
import type {Color} from "@heroui/react";
import {ColorArea, ColorSwatch, parseColor} from "@heroui/react";
import {useState} from "react";
export function ColorAreaControlled() {
const [color, setColor] = useState(parseColor("#9B80FF"));
return (
Current color:{" "}
{color ? color.toString("hex") : "(empty)"}
);
}
```
### Color Space & Channels
Use `colorSpace` to set the color space (RGB, HSL, HSB) and `xChannel`/`yChannel` props to customize which color channels are displayed on each axis.
```tsx
"use client";
import type {ColorSpace, Key} from "@heroui/react";
import {ColorArea, Label, ListBox, Select, parseColor} from "@heroui/react";
import {useState} from "react";
type ColorChannel = "hue" | "saturation" | "brightness" | "lightness" | "red" | "green" | "blue";
interface ChannelOption {
id: ColorChannel;
name: string;
}
const colorSpaces: Array<{id: ColorSpace; name: string}> = [
{id: "rgb", name: "RGB"},
{id: "hsl", name: "HSL"},
{id: "hsb", name: "HSB"},
];
const channelsBySpace: Record = {
hsb: [
{id: "hue", name: "Hue"},
{id: "saturation", name: "Saturation"},
{id: "brightness", name: "Brightness"},
],
hsl: [
{id: "hue", name: "Hue"},
{id: "saturation", name: "Saturation"},
{id: "lightness", name: "Lightness"},
],
rgb: [
{id: "red", name: "Red"},
{id: "green", name: "Green"},
{id: "blue", name: "Blue"},
],
};
export function ColorAreaSpaceAndChannels() {
const [colorSpace, setColorSpace] = useState("hsb");
const [color, setColor] = useState(() => parseColor("hsb(219, 58%, 93%)"));
const channels = channelsBySpace[colorSpace];
const defaultX = colorSpace === "rgb" ? "blue" : "saturation";
const defaultY =
colorSpace === "rgb" ? "green" : colorSpace === "hsl" ? "lightness" : "brightness";
const [xChannel, setXChannel] = useState(defaultX);
const [yChannel, setYChannel] = useState(defaultY);
const handleColorSpaceChange = (newSpace: Key | null) => {
if (!newSpace) return;
const space = newSpace as ColorSpace;
setColorSpace(space);
// Reset channels to appropriate defaults for the new color space
if (space === "rgb") {
setXChannel("blue");
setYChannel("green");
} else if (space === "hsl") {
setXChannel("saturation");
setYChannel("lightness");
} else {
setXChannel("saturation");
setYChannel("brightness");
}
};
// Filter out the other channel from options (can't have same channel on both axes)
const xChannelOptions = channels.filter((c) => c.id !== yChannel);
const yChannelOptions = channels.filter((c) => c.id !== xChannel);
return (
{/* Controls */}
{/* Color Space Select */}
{/* X Channel Select */}
{/* Y Channel Select */}
{/* Color Area */}
{/* Color Value Display */}
{color.toString(colorSpace)}
);
}
```
### Disabled
```tsx
import {ColorArea} from "@heroui/react";
export function ColorAreaDisabled() {
return (
);
}
```
### Custom Render Function
```tsx
"use client";
import {ColorArea} from "@heroui/react";
export function CustomRenderFunction() {
return (
}
>
} />
);
}
```
## Related Components
* **ColorSwatch**: Visual preview of a color value
* **ColorSwatchPicker**: Color swatch selection from a list of colors
* **ColorField**: Input for entering color values with hex format
## Styling
### Passing Tailwind CSS classes
```tsx
import { ColorArea } from '@heroui/react';
function CustomColorArea() {
return (
);
}
```
### Customizing the component classes
To customize the ColorArea component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
```css
@layer components {
.color-area {
@apply rounded-3xl;
}
.color-area__thumb {
@apply size-5 border-4;
}
}
```
HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
### CSS Classes
The ColorArea component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-area.css)):
#### Base Classes
* `.color-area` - Base styles with gradient background and inner shadow
* `.color-area--show-dots` - Adds dot grid overlay for precision picking
#### Element Classes
* `.color-area__thumb` - Draggable thumb indicator
### Interactive States
The component supports both CSS pseudo-classes and data attributes for flexibility:
* **Disabled**: `[data-disabled="true"]`
* **Focus**: `[data-focus-visible="true"]`
* **Dragging**: `[data-dragging="true"]` (thumb only)
## API Reference
### ColorArea Props
Inherits from [React Aria ColorArea](https://react-spectrum.adobe.com/react-aria/ColorArea.html).
| Prop | Type | Default | Description |
| -------------- | ---------------------------------------------------------------------------- | -------------- | ---------------------------------------------------------------- |
| `value` | `string \| Color` | - | The current color value (controlled) |
| `defaultValue` | `string \| Color` | - | The default color value (uncontrolled) |
| `onChange` | `(color: Color) => void` | - | Handler called when the color changes while dragging |
| `onChangeEnd` | `(color: Color) => void` | - | Handler called when the user stops dragging |
| `xChannel` | `ColorChannel` | `"saturation"` | Color channel for the horizontal axis |
| `yChannel` | `ColorChannel` | `"brightness"` | Color channel for the vertical axis |
| `colorSpace` | `ColorSpace` | - | The color space for the channels |
| `isDisabled` | `boolean` | `false` | Whether the color area is disabled |
| `showDots` | `boolean` | `false` | Whether to show the dot grid overlay |
| `className` | `string` | - | Additional CSS classes |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
### ColorArea.Thumb Props
| Prop | Type | Default | Description |
| ----------- | ----------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------- |
| `className` | `string` | - | Additional CSS classes |
| `style` | `CSSProperties \| ((renderProps) => CSSProperties)` | - | Inline styles or render props function |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
# ColorField
**Category**: react
**URL**: https://v3.heroui.com/en/docs/react/components/color-field
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(colors)/color-field.mdx
> Color input field with labels, descriptions, and validation built on React Aria ColorField
## Import
```tsx
import { ColorField, parseColor } from '@heroui/react';
```
### Usage
```tsx
"use client";
import type {Color} from "@heroui/react";
import {ColorField, ColorSwatch, Label, parseColor} from "@heroui/react";
import {useState} from "react";
export function Basic() {
const [color, setColor] = useState(parseColor("#0485F7"));
return (
);
}
```
### Anatomy
```tsx
import {ColorField, Label, ColorSwatch, Description, FieldError, parseColor} from '@heroui/react';
export default () => (
)
```
> **ColorField** combines label, color input, description, and error into a single accessible component.
### With Description
```tsx
import {ColorField, Description, Label} from "@heroui/react";
export function WithDescription() {
return (
Enter your brand's primary colorUsed for highlights and CTAs
);
}
```
### Required Field
```tsx
import {ColorField, Description, Label} from "@heroui/react";
export function Required() {
return (
Required field
);
}
```
### Validation
Use `isInvalid` together with `FieldError` to surface validation messages.
```tsx
import {ColorField, FieldError, Label} from "@heroui/react";
export function Invalid() {
return (
Please enter a valid hex colorInvalid color format. Use hex (e.g., #FF5733)
);
}
```
### Channel Editing
ColorField supports editing individual color channels (hue, saturation, lightness, red, green, blue, alpha) by setting the `colorSpace` and `channel` props.
```tsx
"use client";
import type {Color} from "@heroui/react";
import {ColorField, ColorSwatch, Label, parseColor} from "@heroui/react";
import {useState} from "react";
export function ChannelEditing() {
const [color, setColor] = useState(parseColor("#7F007F"));
return (
);
}
```
### Controlled
Control the value to synchronize with other components or state management.
```tsx
"use client";
import type {Color} from "@heroui/react";
import {Button, ColorField, ColorSwatch, Description, Label, parseColor} from "@heroui/react";
import {useState} from "react";
export function Controlled() {
const [value, setValue] = useState(parseColor("#0485F7"));
return (
Current value: {value ? value.toString("hex") : "(empty)"}
);
}
```
### Disabled State
```tsx
"use client";
import {ColorField, Description, Label} from "@heroui/react";
export function Disabled() {
return (
This color field is disabledThis color field is disabled
);
}
```
### Full Width
```tsx
import {ColorField, Label} from "@heroui/react";
export function FullWidth() {
return (
);
}
```
### Variants
The ColorField.Group component supports two visual variants:
* **`primary`** (default) - Standard styling with shadow, suitable for most use cases
* **`secondary`** - Lower emphasis variant without shadow, suitable for use in Surface components
```tsx
import {ColorField, Label} from "@heroui/react";
export function Variants() {
return (
);
}
```
### On Surface
When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` on ColorField.Group to apply the lower emphasis variant suitable for surface backgrounds.
```tsx
import {ColorField, Description, Label, Surface} from "@heroui/react";
export function OnSurface() {
return (
Select your theme color
);
}
```
### Form Example
Complete form example with validation and submission handling.
```tsx
"use client";
import type {Color} from "@heroui/react";
import {Button, ColorField, ColorSwatch, Description, Form, Label} from "@heroui/react";
import {useState} from "react";
export function FormExample() {
const [value, setValue] = useState(null);
const [isSubmitting, setIsSubmitting] = useState(false);
const handleSubmit = (e: React.FormEvent) => {
e.preventDefault();
if (!value) {
return;
}
setIsSubmitting(true);
// Simulate API call
setTimeout(() => {
console.log("Color submitted:", {color: value.toString("hex")});
setValue(null);
setIsSubmitting(false);
}, 1500);
};
return (
);
}
```
### Custom Render Function
```tsx
"use client";
import type {Color} from "@heroui/react";
import {ColorField, ColorSwatch, Label, parseColor} from "@heroui/react";
import {useState} from "react";
export function CustomRenderFunction() {
const [color, setColor] = useState(parseColor("#0485F7"));
return (
}
value={color}
onChange={setColor}
>
}>
);
}
```
## Related Components
* **ColorSwatch**: Visual preview of a color value
* **ColorSwatchPicker**: Color swatch selection from a list of colors
* **ColorPicker**: Composable color picker with popover
## Styling
### Passing Tailwind CSS classes
```tsx
import {ColorField, Label, ColorSwatch, Description} from '@heroui/react';
function CustomColorField() {
return (
Select your brand's primary color.
);
}
```
### Customizing the component classes
ColorField has minimal default styling. Override the `.color-field` class to customize the container styling.
```css
@layer components {
.color-field {
@apply flex flex-col gap-1;
&[data-invalid="true"],
&[aria-invalid="true"] {
[data-slot="description"] {
@apply hidden;
}
}
[data-slot="label"] {
@apply w-fit;
}
[data-slot="description"] {
@apply px-1;
}
}
}
```
### CSS Classes
* `.color-field` – Root container with minimal styling (`flex flex-col gap-1`)
> **Note:** Child components ([Label](/docs/components/label), [Description](/docs/components/description), [FieldError](/docs/components/field-error)) have their own CSS classes and styling. See their respective documentation for customization options. ColorField.Group styling is documented below in the API Reference section.
### Interactive States
ColorField automatically manages these data attributes based on its state:
* **Invalid**: `[data-invalid="true"]` or `[aria-invalid="true"]` - Automatically hides the description slot when invalid
* **Required**: `[data-required="true"]` - Applied when `isRequired` is true
* **Disabled**: `[data-disabled="true"]` - Applied when `isDisabled` is true
* **Focus Within**: `[data-focus-within="true"]` - Applied when any child input is focused
## API Reference
### ColorField Props
ColorField inherits all props from React Aria's [ColorField](https://react-aria.adobe.com/ColorField.md) component.
#### Base Props
| Prop | Type | Default | Description |
| ----------- | ------------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------- |
| `children` | `React.ReactNode \| (values: ColorFieldRenderProps) => React.ReactNode` | - | Child components (Label, ColorField.Group, etc.) or render function. |
| `className` | `string \| (values: ColorFieldRenderProps) => string` | - | CSS classes for styling, supports render props. |
| `style` | `React.CSSProperties \| (values: ColorFieldRenderProps) => React.CSSProperties` | - | Inline styles, supports render props. |
| `fullWidth` | `boolean` | `false` | Whether the color field should take full width of its container |
| `id` | `string` | - | The element's unique identifier. |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
#### Value Props
| Prop | Type | Default | Description |
| -------------- | -------------------------------- | ------- | -------------------------------------- |
| `value` | `Color \| null` | - | Current value (controlled). |
| `defaultValue` | `Color \| null` | - | Default value (uncontrolled). |
| `onChange` | `(color: Color \| null) => void` | - | Handler called when the value changes. |
#### Channel Props
| Prop | Type | Default | Description |
| ------------ | -------------- | ------- | ---------------------------------------------------------------------------- |
| `colorSpace` | `ColorSpace` | - | The color space that the color field operates in when `channel` is provided. |
| `channel` | `ColorChannel` | - | The color channel to edit. If not provided, edits hex value. |
#### Validation Props
| Prop | Type | Default | Description |
| -------------------- | ---------------------------------------------------------------- | ---------- | -------------------------------------------------------------- |
| `isRequired` | `boolean` | `false` | Whether user input is required before form submission. |
| `isInvalid` | `boolean` | - | Whether the value is invalid. |
| `validate` | `(value: Color) => ValidationError \| true \| null \| undefined` | - | Custom validation function. |
| `validationBehavior` | `'native' \| 'aria'` | `'native'` | Whether to use native HTML form validation or ARIA attributes. |
#### State Props
| Prop | Type | Default | Description |
| ----------------- | --------- | ------- | -------------------------------------------------- |
| `isDisabled` | `boolean` | - | Whether the input is disabled. |
| `isReadOnly` | `boolean` | - | Whether the input can be selected but not changed. |
| `isWheelDisabled` | `boolean` | - | Whether to disable changing the value with scroll. |
#### Form Props
| Prop | Type | Default | Description |
| ----------- | --------- | ------- | ---------------------------------------------------- |
| `name` | `string` | - | Name of the input element, for HTML form submission. |
| `autoFocus` | `boolean` | - | Whether the element should receive focus on render. |
#### Accessibility Props
| Prop | Type | Default | Description |
| ------------------ | -------- | ------- | ----------------------------------------------------- |
| `aria-label` | `string` | - | Accessibility label when no visible label is present. |
| `aria-labelledby` | `string` | - | ID of elements that label this field. |
| `aria-describedby` | `string` | - | ID of elements that describe this field. |
| `aria-details` | `string` | - | ID of elements with additional details. |
### Composition Components
ColorField works with these separate components that should be imported and used directly:
* **Label** - Field label component from `@heroui/react`
* **ColorField.Group** - Color input group component (documented below)
* **ColorField.Input** - Input element within ColorField.Group
* **ColorField.Prefix** / **ColorField.Suffix** - Prefix and suffix slots for the input group
* **ColorSwatch** - Color preview component from `@heroui/react`
* **Description** - Helper text component from `@heroui/react`
* **FieldError** - Validation error message from `@heroui/react`
Each of these components has its own props API. Use them directly within ColorField for composition:
```tsx
import {ColorField, Label, ColorSwatch, Description, FieldError, parseColor} from '@heroui/react';
Select your brand's primary color.Please enter a valid color.
```
### Color Types
ColorField uses `Color` objects from React Aria Components:
```tsx
import {parseColor} from '@heroui/react';
// Parse from hex string
const color = parseColor('#3B82F6');
// Get hex string from color
const hex = color.toString('hex'); // "#3b82f6"
// Get RGB values
const rgb = color.toString('rgb'); // "rgb(59, 130, 246)"
// Use in ColorField
{/* ... */}
```
### ColorFieldRenderProps
When using render props with `className`, `style`, or `children`, these values are available:
| Prop | Type | Description |
| ---------------- | --------- | ----------------------------------------------- |
| `isDisabled` | `boolean` | Whether the field is disabled. |
| `isInvalid` | `boolean` | Whether the field is currently invalid. |
| `isReadOnly` | `boolean` | Whether the field is read-only. |
| `isRequired` | `boolean` | Whether the field is required. |
| `isFocused` | `boolean` | Whether the field is currently focused. |
| `isFocusWithin` | `boolean` | Whether any child element is focused. |
| `isFocusVisible` | `boolean` | Whether focus is visible (keyboard navigation). |
### ColorField.Group Props
ColorField.Group accepts all props from React Aria's `Group` component plus the following:
| Prop | Type | Default | Description |
| ----------- | ------------------------------------------------------------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `className` | `string` | - | Tailwind classes merged with the component styles. |
| `fullWidth` | `boolean` | `false` | Whether the color input group should take full width of its container |
| `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the component. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
### ColorField.Input Props
ColorField.Input accepts all props from React Aria's `Input` component plus the following:
| Prop | Type | Default | Description |
| ------------- | -------- | ------- | -------------------------------------------------- |
| `className` | `string` | - | Tailwind classes merged with the component styles. |
| `placeholder` | `string` | - | Placeholder text shown when empty. |
### ColorField.Prefix Props
ColorField.Prefix accepts standard HTML `div` attributes:
| Prop | Type | Default | Description |
| ----------- | ----------- | ------- | -------------------------------------------------- |
| `className` | `string` | - | Tailwind classes merged with the component styles. |
| `children` | `ReactNode` | - | Content to display in the prefix slot. |
### ColorField.Suffix Props
ColorField.Suffix accepts standard HTML `div` attributes:
| Prop | Type | Default | Description |
| ----------- | ----------- | ------- | -------------------------------------------------- |
| `className` | `string` | - | Tailwind classes merged with the component styles. |
| `children` | `ReactNode` | - | Content to display in the suffix slot. |
## ColorField.Group Styling
### Customizing the component classes
The base classes power every instance. Override them once with `@layer components`.
```css
@layer components {
.color-input-group {
@apply inline-flex h-9 items-center overflow-hidden rounded-field border bg-field text-sm text-field-foreground shadow-field outline-none;
&:hover,
&[data-hovered="true"] {
@apply bg-field-hover;
}
&[data-focus-within="true"],
&:focus-within {
@apply status-focused-field;
}
&[data-invalid="true"] {
@apply status-invalid-field;
}
&[data-disabled="true"],
&[aria-disabled="true"] {
@apply status-disabled;
}
}
.color-input-group__input {
@apply flex flex-1 items-center rounded-none border-0 bg-transparent px-3 py-2 shadow-none outline-none;
}
.color-input-group__prefix,
.color-input-group__suffix {
@apply shrink-0 text-field-placeholder flex items-center;
}
}
```
### ColorField.Group CSS Classes
* `.color-input-group` – Root container styling
* `.color-input-group__input` – Input wrapper styling
* `.color-input-group__prefix` – Prefix element styling
* `.color-input-group__suffix` – Suffix element styling
### ColorField.Group Interactive States
* **Hover**: `:hover` or `[data-hovered="true"]`
* **Focus Within**: `[data-focus-within="true"]` or `:focus-within`
* **Invalid**: `[data-invalid="true"]` (also syncs with `aria-invalid`)
* **Disabled**: `[data-disabled="true"]` or `[aria-disabled="true"]`
# ColorPicker
**Category**: react
**URL**: https://v3.heroui.com/en/docs/react/components/color-picker
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(colors)/color-picker.mdx
> A composable color picker that synchronizes color value between multiple color components
## Import
```tsx
import {
ColorPicker,
ColorArea,
ColorSlider,
ColorSwatch,
ColorField,
ColorSwatchPicker,
} from '@heroui/react';
```
### Usage
```tsx
import {ColorArea, ColorPicker, ColorSlider, ColorSwatch, Label} from "@heroui/react";
export function Basic() {
return (
);
}
```
### Anatomy
The ColorPicker is a composable component that combines multiple color components:
```tsx
import { ColorPicker, ColorArea, ColorSlider, ColorSwatch, Label } from '@heroui/react';
export default () => (
);
```
### Controlled
```tsx
"use client";
import {
Button,
ColorArea,
ColorField,
ColorPicker,
ColorSlider,
ColorSwatch,
ColorSwatchPicker,
Label,
parseColor,
} from "@heroui/react";
import {Icon} from "@iconify/react";
import {useState} from "react";
export function Controlled() {
const [color, setColor] = useState(parseColor("#325578"));
const colorPresets = [
"#ef4444",
"#f97316",
"#eab308",
"#22c55e",
"#06b6d4",
"#3b82f6",
"#8b5cf6",
"#ec4899",
"#f43f5e",
];
const shuffleColor = () => {
const randomHue = Math.floor(Math.random() * 360);
const randomSaturation = 50 + Math.floor(Math.random() * 50); // 50-100%
const randomLightness = 40 + Math.floor(Math.random() * 30); // 40-70%
setColor(parseColor(`hsl(${randomHue}, ${randomSaturation}%, ${randomLightness}%)`));
};
return (
{colorPresets.map((preset) => (
))}
Selected: {color.toString("hex")}
);
}
```
### With Swatches
```tsx
import {
ColorArea,
ColorPicker,
ColorSlider,
ColorSwatch,
ColorSwatchPicker,
Label,
} from "@heroui/react";
export function WithSwatches() {
const presets = [
"#ef4444",
"#f97316",
"#eab308",
"#22c55e",
"#06b6d4",
"#3b82f6",
"#8b5cf6",
"#ec4899",
"#f43f5e",
];
return (
{presets.map((preset) => (
))}
);
}
```
### With Fields
Use `ColorField` to allow users to edit individual color channel values with a `Select` to switch between color spaces.
```tsx
"use client";
import type {ColorChannel, ColorSpace} from "@heroui/react";
import {
ColorArea,
ColorField,
ColorPicker,
ColorSlider,
ColorSwatch,
Label,
ListBox,
Select,
} from "@heroui/react";
import {useState} from "react";
export function WithFields() {
const [colorSpace, setColorSpace] = useState("hsl");
const colorChannelsByColorSpace: Record = {
hsb: ["hue", "saturation", "brightness"],
hsl: ["hue", "saturation", "lightness"],
rgb: ["red", "green", "blue"],
};
return (
);
}
```
### With Sliders
Use multiple `ColorSlider` components to adjust each channel of a color value.
```tsx
"use client";
import type {ColorChannel, ColorSpace} from "@heroui/react";
import {ColorPicker, ColorSlider, ColorSwatch, Label, ListBox, Select} from "@heroui/react";
import {useState} from "react";
export function WithSliders() {
const [colorSpace, setColorSpace] = useState("hsl");
const colorChannelsByColorSpace: Record = {
hsb: ["hue", "saturation", "brightness", "alpha"],
hsl: ["hue", "saturation", "lightness", "alpha"],
rgb: ["red", "green", "blue", "alpha"],
};
return (
{colorChannelsByColorSpace[colorSpace].map((channel: ColorChannel) => (
// @ts-expect-error - TypeScript can't correlate dynamic colorSpace with channel type
))}
);
}
```
## Related Components
* **ColorArea**: 2D color picker for selecting colors from a gradient area
* **ColorSlider**: Slider for adjusting individual color channel values
* **ColorSwatch**: Visual preview of a color value
## Styling
### Passing Tailwind CSS classes
```tsx
import { ColorPicker, ColorArea, ColorSlider, ColorSwatch, Label } from '@heroui/react';
function CustomColorPicker() {
return (
);
}
```
### Customizing the component classes
To customize the ColorPicker component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
```css
@layer components {
.color-picker {
@apply inline-flex;
}
.color-picker__trigger {
@apply inline-flex items-center gap-4 rounded-lg;
}
.color-picker__popover {
@apply p-4 rounded-xl;
}
}
```
HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
### CSS Classes
The ColorPicker component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-picker.css)):
#### Base Classes
* `.color-picker` - Base container
* `.color-picker__trigger` - Trigger button
* `.color-picker__popover` - Popover container
### Interactive States
The component supports both CSS pseudo-classes and data attributes for flexibility:
* **Focus**: `:focus-visible` or `[data-focus-visible="true"]`
* **Disabled**: `:disabled` or `[data-disabled="true"]`
## API Reference
### ColorPicker Props
Inherits from [React Aria ColorPicker](https://react-spectrum.adobe.com/react-aria/ColorPicker.html).
| Prop | Type | Default | Description |
| -------------- | ------------------------ | ------- | ---------------------------------------------------- |
| `value` | `string \| Color` | - | The current color value (controlled) |
| `defaultValue` | `string \| Color` | - | The default color value (uncontrolled) |
| `onChange` | `(color: Color) => void` | - | Handler called when the color changes |
| `children` | `React.ReactNode` | - | Content of the color picker (Trigger, Popover, etc.) |
| `className` | `string` | - | Additional CSS classes |
### ColorPicker.Trigger Props
| Prop | Type | Default | Description |
| ----------- | ------------------------------------------------------- | ------- | ------------------------------ |
| `children` | `React.ReactNode \| ((renderProps) => React.ReactNode)` | - | Trigger content or render prop |
| `className` | `string` | - | Additional CSS classes |
### ColorPicker.Popover Props
| Prop | Type | Default | Description |
| ----------- | ----------------- | --------------- | ------------------------ |
| `placement` | `Placement` | `"bottom left"` | Placement of the popover |
| `children` | `React.ReactNode` | - | Popover content |
| `className` | `string` | - | Additional CSS classes |
### Related Types
#### Color
Represents a color value. See [React Aria Color](https://react-spectrum.adobe.com/react-aria/ColorPicker.html#color) for full API.
| Method | Description |
| ---------------------------------- | ---------------------------------------------------------------------------- |
| `toString(format)` | Converts the color to a string in the given format (hex, rgb, hsl, hsb, css) |
| `toFormat(format)` | Converts the color to the given format and returns a new Color object |
| `getChannelValue(channel)` | Returns the numeric value for a given channel |
| `withChannelValue(channel, value)` | Sets the numeric value for a channel and returns a new Color |
#### parseColor
```tsx
import { parseColor } from 'react-aria-components';
// Parse from string
const color = parseColor('#ff0000');
const hslColor = parseColor('hsl(0, 100%, 50%)');
```
# ColorSlider
**Category**: react
**URL**: https://v3.heroui.com/en/docs/react/components/color-slider
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(colors)/color-slider.mdx
> A color slider allows users to adjust an individual channel of a color value
## Import
```tsx
import { ColorSlider, Label } from '@heroui/react';
```
### Usage
```tsx
import {ColorSlider, Label} from "@heroui/react";
export function Basic() {
return (
);
}
```
### Anatomy
Import the ColorSlider component and access all parts using dot notation.
```tsx
import { ColorSlider, Label } from '@heroui/react';
export default () => (
)
```
### Vertical
```tsx
import {ColorSlider} from "@heroui/react";
export function Vertical() {
return (
);
}
```
### Disabled
```tsx
import {ColorSlider, Label} from "@heroui/react";
export function Disabled() {
return (
);
}
```
### Controlled
```tsx
"use client";
import {ColorSlider, ColorSwatch, Label} from "@heroui/react";
import {useState} from "react";
import {parseColor} from "react-aria-components";
export function Controlled() {
const [color, setColor] = useState(parseColor("hsl(200, 100%, 50%)"));
return (
Current color: {color.toString("hsl")}
);
}
```
### HSL Channels
Use multiple ColorSliders to control different channels of a color value. The sliders can share the same color value to create a complete color picker.
```tsx
"use client";
import {ColorSlider, ColorSwatch, Label} from "@heroui/react";
import {useState} from "react";
import {parseColor} from "react-aria-components";
export function Channels() {
const [color, setColor] = useState(parseColor("hsl(0, 100%, 50%)"));
return (
Current color: {color.toString("hsl")}
);
}
```
### Alpha Channel
The alpha channel slider shows a transparency checkerboard pattern to help visualize the transparency level.
```tsx
import {ColorSlider, Label} from "@heroui/react";
export function AlphaChannel() {
return (
);
}
```
### RGB Channels
You can also use RGB color space with red, green, and blue channels.
```tsx
"use client";
import {ColorSlider, ColorSwatch, Label} from "@heroui/react";
import {useState} from "react";
import {parseColor} from "react-aria-components";
export function RGBChannels() {
const [color, setColor] = useState(parseColor("rgb(255, 100, 50)"));
return (
Current color: {color.toString("rgb")}
);
}
```
### Custom Render Function
```tsx
"use client";
import {ColorSlider, Label} from "@heroui/react";
export function CustomRenderFunction() {
return (
}
>
);
}
```
## Related Components
* **ColorSwatch**: Visual preview of a color value
* **ColorSwatchPicker**: Color swatch selection from a list of colors
* **ColorPicker**: Composable color picker with popover
## Styling
### Passing Tailwind CSS classes
```tsx
import { ColorSlider, Label } from '@heroui/react';
function CustomColorSlider() {
return (
);
}
```
### Customizing the component classes
To customize the ColorSlider component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
```css
@layer components {
.color-slider {
@apply flex flex-col gap-2;
}
.color-slider__output {
@apply text-muted text-sm;
}
.color-slider__track {
@apply relative h-5 w-full rounded-full;
}
.color-slider__thumb {
@apply size-4 rounded-full border-3 border-white shadow-overlay;
}
}
```
HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
### CSS Classes
The ColorSlider component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-slider.css)):
#### Base Classes
* `.color-slider` - Base slider container
* `.color-slider__output` - Output element displaying current value
* `.color-slider__track` - Track element with color gradient
* `.color-slider__thumb` - Thumb element showing current color
#### State Classes
* `.color-slider[data-disabled="true"]` - Disabled slider state
* `.color-slider[data-orientation="vertical"]` - Vertical orientation
* `.color-slider__thumb[data-dragging="true"]` - Thumb being dragged
* `.color-slider__thumb[data-focus-visible="true"]` - Thumb keyboard focused
* `.color-slider__thumb[data-disabled="true"]` - Disabled thumb state
### Interactive States
The component supports both CSS pseudo-classes and data attributes for flexibility:
* **Hover**: `:hover` or `[data-hovered="true"]` on thumb
* **Focus**: `:focus-visible` or `[data-focus-visible="true"]` on thumb
* **Dragging**: `[data-dragging="true"]` on thumb
* **Disabled**: `:disabled` or `[data-disabled="true"]` on slider or thumb
## API Reference
### ColorSlider Props
Inherits from [React Aria ColorSlider](https://react-spectrum.adobe.com/react-aria/ColorSlider.html).
| Prop | Type | Default | Description |
| -------------- | ------------------------------------------------------------------------------ | -------------- | --------------------------------------------------------------------------------------------------------------- |
| `channel` | `ColorChannel` | - | The color channel that the slider manipulates (hue, saturation, lightness, brightness, alpha, red, green, blue) |
| `colorSpace` | `ColorSpace` | - | The color space (hsl, hsb, rgb). Defaults to the color space of the value |
| `value` | `string \| Color` | - | The current color value (controlled) |
| `defaultValue` | `string \| Color` | - | The default color value (uncontrolled) |
| `onChange` | `(value: Color) => void` | - | Handler called when the value changes during dragging |
| `onChangeEnd` | `(value: Color) => void` | - | Handler called when dragging ends |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | The orientation of the slider |
| `isDisabled` | `boolean` | - | Whether the slider is disabled |
| `name` | `string` | - | The name of the input element for form submission |
| `aria-label` | `string` | - | Accessibility label for the slider |
| `className` | `string` | - | Additional CSS classes |
| `children` | `ReactNode \| RenderFunction` | - | Slider content or render function |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
### ColorSlider.Output Props
| Prop | Type | Default | Description |
| ----------- | ----------------------------- | ------- | --------------------------------- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `ReactNode \| RenderFunction` | - | Output content or render function |
### ColorSlider.Track Props
| Prop | Type | Default | Description |
| ----------- | --------------------------------- | ------- | -------------------------------- |
| `className` | `string` | - | Additional CSS classes |
| `style` | `CSSProperties \| RenderFunction` | - | Inline styles or render function |
| `children` | `ReactNode \| RenderFunction` | - | Track content or render function |
### ColorSlider.Thumb Props
| Prop | Type | Default | Description |
| ----------- | --------------------------------- | ------- | -------------------------------- |
| `className` | `string` | - | Additional CSS classes |
| `style` | `CSSProperties \| RenderFunction` | - | Inline styles or render function |
| `children` | `ReactNode \| RenderFunction` | - | Thumb content or render function |
### RenderProps
When using render functions, these values are provided:
| Prop | Type | Description |
| ------------- | ---------------------------- | ------------------------------ |
| `state` | `ColorSliderState` | The state of the color slider |
| `color` | `Color` | The current color value |
| `orientation` | `"horizontal" \| "vertical"` | The orientation of the slider |
| `isDisabled` | `boolean` | Whether the slider is disabled |
## Accessibility
The ColorSlider component implements the ARIA slider pattern and provides:
* Full keyboard navigation support (Arrow keys, Home, End, Page Up/Down)
* Screen reader announcements for value changes
* Proper focus management
* Support for disabled states
* HTML form integration via hidden input elements
* Internationalization support with locale-aware value formatting
For more information, see the [React Aria ColorSlider documentation](https://react-spectrum.adobe.com/react-aria/ColorSlider.html).
# ColorSwatchPicker
**Category**: react
**URL**: https://v3.heroui.com/en/docs/react/components/color-swatch-picker
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(colors)/color-swatch-picker.mdx
> A list of color swatches that allows users to select a color from a predefined palette.
## Import
```tsx
import { ColorSwatchPicker, parseColor } from '@heroui/react';
```
### Usage
```tsx
import {ColorSwatchPicker} from "@heroui/react";
const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];
export function Basic() {
return (
{colors.map((color) => (
))}
);
}
```
### Anatomy
Import the ColorSwatchPicker component and access all parts using dot notation.
```tsx
import { ColorSwatchPicker } from '@heroui/react';
export default () => (
);
```
### Variants
```tsx
import {ColorSwatchPicker} from "@heroui/react";
const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];
export function Variants() {
return (
);
}
```
### Disabled
```tsx
import {ColorSwatchPicker} from "@heroui/react";
const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];
export function Disabled() {
return (
{colors.map((color) => (
))}
);
}
```
### Custom Indicator
```tsx
import {HeartFill} from "@gravity-ui/icons";
import {ColorSwatchPicker} from "@heroui/react";
export function CustomIndicator() {
const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];
return (
{colors.map((color) => (
))}
);
}
```
### Custom Render Function
```tsx
"use client";
import {ColorSwatchPicker} from "@heroui/react";
const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];
export function CustomRenderFunction() {
return (
}>
{colors.map((color) => (
))}
);
}
```
## Related Components
* **ColorSwatch**: Visual preview of a color value
* **ColorField**: Input for entering color values with hex format
* **ColorArea**: 2D color picker for selecting colors from a gradient area
## Styling
### Passing Tailwind CSS classes
You can customize the ColorSwatchPicker using className props:
```tsx
import { ColorSwatchPicker } from '@heroui/react';
function CustomColorSwatchPicker() {
return (
);
}
```
### Customizing the component classes
To customize the ColorSwatchPicker component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
```css
@layer components {
.color-swatch-picker {
@apply gap-4;
}
.color-swatch-picker__item {
@apply shadow-md;
}
.color-swatch-picker__swatch {
@apply border-2 border-white;
}
}
```
HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
### CSS Classes
The ColorSwatchPicker component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-swatch-picker.css)):
#### Base & Structure
* `.color-swatch-picker` - Base container (flex layout)
* `.color-swatch-picker__item` - Individual swatch item wrapper
* `.color-swatch-picker__swatch` - The color swatch visual element
#### Size Classes
* `.color-swatch-picker--xs` - Extra small (16px)
* `.color-swatch-picker--sm` - Small (24px)
* `.color-swatch-picker--md` - Medium (32px, default)
* `.color-swatch-picker--lg` - Large (36px)
* `.color-swatch-picker--xl` - Extra large (40px)
#### Shape Variants
* `.color-swatch-picker--circle` - Circle shape (default)
* `.color-swatch-picker--square` - Square shape with rounded corners
#### Layout Classes
* `.color-swatch-picker--grid` - Horizontal wrapping layout (default)
* `.color-swatch-picker--stack` - Vertical stacked layout
### Interactive States
The component supports both CSS pseudo-classes and data attributes for flexibility:
* **Hover**: `:hover` or `[data-hovered="true"]` - Scale up to 1.1 (only when not selected)
* **Focus**: `:focus-visible` or `[data-focus-visible="true"]` - Focus ring
* **Selected**: `[data-selected="true"]` - Inner border with same color as swatch
* **Disabled**: `[data-disabled="true"]` - Reduced opacity
## API Reference
### ColorSwatchPicker Props
Inherits from [React Aria ColorSwatchPicker](https://react-spectrum.adobe.com/react-aria/ColorSwatchPicker.html).
| Prop | Type | Default | Description |
| -------------- | ------------------------------------------------------------------------------------ | ---------- | ---------------------------------------------------------------- |
| `value` | `string \| Color` | - | The current selected color (controlled) |
| `defaultValue` | `string \| Color` | - | The default selected color (uncontrolled) |
| `onChange` | `(value: Color) => void` | - | Handler called when selection changes |
| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Size of the swatches |
| `variant` | `"circle" \| "square"` | `"circle"` | Shape of the swatches |
| `layout` | `"grid" \| "stack"` | `"grid"` | Layout direction |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | ColorSwatchPicker.Item elements |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
### ColorSwatchPicker.Item Props
| Prop | Type | Default | Description |
| ------------ | ---------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------- |
| `color` | `string \| Color` | **Required** | The color of the swatch |
| `isDisabled` | `boolean` | `false` | Whether the item is disabled |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | ColorSwatchPicker.Swatch element |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
### ColorSwatchPicker.Swatch Props
| Prop | Type | Default | Description |
| ----------- | -------- | ------- | ---------------------- |
| `className` | `string` | - | Additional CSS classes |
### parseColor
The `parseColor` function is re-exported from React Aria Components for convenience:
```tsx
import { parseColor } from '@heroui/react';
// Parse hex color
const red = parseColor('#ff0000');
// Parse RGB
const green = parseColor('rgb(0, 255, 0)');
// Parse HSL
const blue = parseColor('hsl(240, 100%, 50%)');
```
# ColorSwatch
**Category**: react
**URL**: https://v3.heroui.com/en/docs/react/components/color-swatch
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(colors)/color-swatch.mdx
> A visual preview of a color value with accessibility support
## Import
```tsx
import { ColorSwatch } from '@heroui/react';
```
### Usage
```tsx
import {ColorSwatch} from "@heroui/react";
export function ColorSwatchBasic() {
return (
);
}
```
### Sizes
```tsx
import {ColorSwatch} from "@heroui/react";
export function ColorSwatchSizes() {
return (
);
}
```
### Shapes
```tsx
import {ColorSwatch} from "@heroui/react";
export function ColorSwatchShapes() {
return (
);
}
```
### Transparency
```tsx
import {ColorSwatch} from "@heroui/react";
export function ColorSwatchTransparency() {
return (
);
}
```
### Custom Styles with Render Props
You can use the `style` render props to access the color value and create custom visual effects.
```tsx
"use client";
import {ColorSwatch} from "@heroui/react";
export function ColorSwatchCustomStyles() {
const colors = ["#0485F7", "#EF4444", "#F59E0B", "#10B981", "#D946EF"];
return (
);
}
```
### Accessibility
Use `colorName` to provide a custom accessible name for the color, and `aria-label` to add context about how the color is used.
```tsx
import {ColorSwatch} from "@heroui/react";
export function ColorSwatchAccessibility() {
return (
);
}
```
### Custom Render Function
```tsx
"use client";
import {ColorSwatch} from "@heroui/react";
export function CustomRenderFunction() {
return (
}
/>
}
/>
}
/>
}
/>
}
/>
);
}
```
## Related Components
* **ColorSwatchPicker**: Color swatch selection from a list of colors
* **ColorField**: Input for entering color values with hex format
* **ColorArea**: 2D color picker for selecting colors from a gradient area
## Styling
### Passing Tailwind CSS classes
```tsx
import {ColorSwatch} from '@heroui/react';
function CustomColorSwatch() {
return (
);
}
```
### Customizing the component classes
To customize the ColorSwatch component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
```css
@layer components {
.color-swatch {
@apply border-2 border-white;
}
}
```
HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
### CSS Classes
The ColorSwatch component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-swatch.css)):
#### Base Classes
* `.color-swatch` - Base swatch styles with checkered background for transparency
#### Shape Classes
* `.color-swatch--circle` - Circular shape (default)
* `.color-swatch--square` - Square shape with rounded corners
#### Size Classes
* `.color-swatch--xs` - Extra small (16px)
* `.color-swatch--sm` - Small (24px)
* `.color-swatch--md` - Medium (32px, default)
* `.color-swatch--lg` - Large (36px)
* `.color-swatch--xl` - Extra large (40px)
## API Reference
### ColorSwatch Props
| Prop | Type | Default | Description |
| ------------ | ------------------------------------------------------------------------------ | ---------- | -------------------------------------------------------------------- |
| `color` | `string \| Color` | - | The color value to display (hex, rgb, hsl, etc.) |
| `colorName` | `string` | - | Accessible name for the color (overrides auto-generated description) |
| `className` | `string` | - | Additional CSS classes |
| `shape` | `"circle" \| "square"` | `"circle"` | Shape of the swatch |
| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Size of the swatch |
| `style` | `CSSProperties \| ((renderProps) => CSSProperties)` | - | Inline styles or render props function with access to color |
| `aria-label` | `string` | - | Accessible label for the swatch |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
### Style Render Props
When using the `style` prop as a function, you receive render props with access to the color:
```tsx
({
boxShadow: `0 4px 14px ${color.toString("css")}80`,
})}
/>
```
The `color` object provides methods like:
* `color.toString("css")` - Returns CSS color string
* `color.toString("hex")` - Returns hex color string
* `color.getChannelValue("alpha")` - Returns alpha channel value
# Slider
**Category**: react
**URL**: https://v3.heroui.com/en/docs/react/components/slider
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(controls)/slider.mdx
> A slider allows a user to select one or more values within a range
## Import
```tsx
import { Slider } from '@heroui/react';
```
### Usage
```tsx
import {Label, Slider} from "@heroui/react";
export function Default() {
return (
);
}
```
### Anatomy
Import the Slider component and access all parts using dot notation.
```tsx
import { Slider, Label } from '@heroui/react';
export default () => (
)
```
### Range Slider Anatomy
```tsx
import { Slider, Label } from '@heroui/react';
export default () => (
{({state}) => (
<>
{state.values.map((_, i) => (
))}
)}
)
```
### Vertical
```tsx
import {Label, Slider} from "@heroui/react";
export function Vertical() {
return (
);
}
```
### Range
```tsx
"use client";
import {Label, Slider} from "@heroui/react";
export function Range() {
return (
{({state}) => (
<>
{state.values.map((_, i) => (
))}
)}
);
}
```
### Disabled
```tsx
import {Label, Slider} from "@heroui/react";
export function Disabled() {
return (
);
}
```
### Custom Render Function
```tsx
"use client";
import {Label, Slider} from "@heroui/react";
export function CustomRenderFunction() {
return (
}
>
);
}
```
## Related Components
* **Label**: Accessible label for form controls
* **Form**: Form validation and submission handling
* **Description**: Helper text for form fields
## Styling
### Passing Tailwind CSS classes
```tsx
import { Slider, Label } from '@heroui/react';
function CustomSlider() {
return (
);
}
```
### Customizing the component classes
To customize the Slider component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
```css
@layer components {
.slider {
@apply flex flex-col gap-2;
}
.slider__output {
@apply text-muted-fg text-sm;
}
.slider-track {
@apply relative h-2 w-full rounded-full bg-surface-secondary;
}
.slider-fill {
@apply absolute h-full rounded-full bg-accent;
}
.slider-thumb {
@apply size-4 rounded-full bg-accent border-2 border-background;
}
}
```
HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
### CSS Classes
The Slider component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/slider.css)):
#### Base Classes
* `.slider` - Base slider container
* `.slider__output` - Output element displaying current value(s)
* `.slider-track` - Track element containing fill and thumbs
* `.slider-fill` - Fill element showing selected range
* `.slider-thumb` - Individual thumb element
#### State Classes
* `.slider[data-disabled="true"]` - Disabled slider state
* `.slider[data-orientation="vertical"]` - Vertical orientation
* `.slider-thumb[data-dragging="true"]` - Thumb being dragged
* `.slider-thumb[data-focus-visible="true"]` - Thumb keyboard focused
* `.slider-thumb[data-disabled="true"]` - Disabled thumb state
* `.slider-track[data-fill-start="true"]` - Fill starts at beginning
* `.slider-track[data-fill-end="true"]` - Fill ends at end
### Interactive States
The component supports both CSS pseudo-classes and data attributes for flexibility:
* **Hover**: `:hover` or `[data-hovered="true"]` on thumb
* **Focus**: `:focus-visible` or `[data-focus-visible="true"]` on thumb
* **Dragging**: `[data-dragging="true"]` on thumb
* **Disabled**: `:disabled` or `[data-disabled="true"]` on slider or thumb
## API Reference
### Slider Props
| Prop | Type | Default | Description |
| ----------------- | ------------------------------------------------------------------------- | -------------- | ---------------------------------------------------------------- |
| `value` | `number \| number[]` | - | The current value (controlled) |
| `defaultValue` | `number \| number[]` | - | The default value (uncontrolled) |
| `onChange` | `(value: number \| number[]) => void` | - | Handler called when the value changes |
| `onChangeEnd` | `(value: number \| number[]) => void` | - | Handler called when dragging ends |
| `minValue` | `number` | `0` | The slider's minimum value |
| `maxValue` | `number` | `100` | The slider's maximum value |
| `step` | `number` | `1` | The slider's step value |
| `formatOptions` | `Intl.NumberFormatOptions` | - | The display format of the value label |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | The orientation of the slider |
| `isDisabled` | `boolean` | - | Whether the slider is disabled |
| `aria-label` | `string` | - | Accessibility label for the slider |
| `aria-labelledby` | `string` | - | ID of element that labels the slider |
| `className` | `string` | - | Additional CSS classes |
| `children` | `ReactNode \| RenderFunction` | - | Slider content or render function |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
### Slider.Output Props
| Prop | Type | Default | Description |
| ----------- | ------------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `ReactNode \| RenderFunction` | - | Output content or render function |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
### Slider.Track Props
| Prop | Type | Default | Description |
| ----------- | ------------------------------------------------------------------------------ | ------- | ---------------------------------------------------------------- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `ReactNode \| RenderFunction` | - | Track content or render function |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
### Slider.Fill Props
| Prop | Type | Default | Description |
| ----------- | --------------- | ------- | ---------------------- |
| `className` | `string` | - | Additional CSS classes |
| `style` | `CSSProperties` | - | Inline styles |
### Slider.Thumb Props
| Prop | Type | Default | Description |
| ------------ | ------------------------------------------------------------------------------ | ------- | ---------------------------------------------------------------- |
| `index` | `number` | `0` | Index of the thumb within the slider |
| `isDisabled` | `boolean` | - | Whether this thumb is disabled |
| `name` | `string` | - | The name of the input element, used when submitting an HTML form |
| `className` | `string` | - | Additional CSS classes |
| `children` | `ReactNode \| RenderFunction` | - | Thumb content or render function |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
### RenderProps
When using render functions with Slider.Output or Slider.Track, these values are provided:
| Prop | Type | Description |
| -------------------- | ---------------------------- | -------------------------------------------------------- |
| `state` | `SliderState` | The state of the slider |
| `values` | `number[]` | Values managed by the slider by thumb index |
| `getThumbValueLabel` | `(index: number) => string` | Returns the string label for the specified thumb's value |
| `orientation` | `"horizontal" \| "vertical"` | The orientation of the slider |
| `isDisabled` | `boolean` | Whether the slider is disabled |
## Examples
### Basic Usage
```tsx
import { Slider, Label } from '@heroui/react';
```
### Range Slider
```tsx
import { Slider, Label } from '@heroui/react';
{({state}) => (
<>
{state.values.map((_, i) => (
))}
)}
```
### Controlled Value
```tsx
import { Slider, Label } from '@heroui/react';
import { useState } from 'react';
function ControlledSlider() {
const [value, setValue] = useState(25);
return (
<>
Current value: {value}
);
}
```
### Custom Value Formatting
```tsx
import { Slider, Label } from '@heroui/react';
```
### Vertical Orientation
```tsx
import { Slider, Label } from '@heroui/react';
```
### Custom Output Display
```tsx
import { Slider, Label } from '@heroui/react';
{({state}) =>
state.values.map((_, i) => state.getThumbValueLabel(i)).join(' – ')
}
{({state}) => (
<>
{state.values.map((_, i) => (
))}
)}
```
## Accessibility
The Slider component implements the ARIA slider pattern and provides:
* Full keyboard navigation support (Arrow keys, Home, End, Page Up/Down)
* Screen reader announcements for value changes
* Proper focus management
* Support for disabled states
* HTML form integration via hidden input elements
* Internationalization support with locale-aware value formatting
* Right-to-left (RTL) language support
For more information, see the [React Aria Slider documentation](https://react-spectrum.adobe.com/react-aria/Slider.html).
# Switch
**Category**: react
**URL**: https://v3.heroui.com/en/docs/react/components/switch
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(controls)/switch.mdx
> A toggle switch component for boolean states
## Import
```tsx
import { Switch, SwitchGroup, Label } from '@heroui/react';
```
### Usage
```tsx
import {Switch} from "@heroui/react";
export function Basic() {
return (
Enable notifications
);
}
```
### Anatomy
Import the Switch component and access all parts using dot notation.
```tsx
import { Switch, Description, FieldError } from '@heroui/react';
export default () => (
{/* Optional */}
Label {/* plain text — the clickable label + accessible name */}
{/* Optional — field-level help text */}
{/* Optional — validation message */}
);
```
For grouping multiple switches, use the `SwitchGroup` component:
```tsx
import { Switch, SwitchGroup, Label } from '@heroui/react';
export default () => (
Option 1
Option 2
);
```
### Disabled
```tsx
import {Switch} from "@heroui/react";
export function Disabled() {
return (
Enable notifications
);
}
```
### Default Selected
```tsx
import {Switch} from "@heroui/react";
export function DefaultSelected() {
return (
Enable notifications
);
}
```
### Controlled
```tsx
"use client";
import {Switch} from "@heroui/react";
import React from "react";
export function Controlled() {
const [isSelected, setIsSelected] = React.useState(false);
return (
Enable notifications
Switch is {isSelected ? "on" : "off"}
);
}
```
### Without Label
```tsx
import {Switch} from "@heroui/react";
export function WithoutLabel() {
return (
);
}
```
### Sizes
```tsx
import {Switch} from "@heroui/react";
export function Sizes() {
return (
Small
Medium
Large
);
}
```
### Label Position
```tsx
import {Switch} from "@heroui/react";
export function LabelPosition() {
return (
Label after
Label before
);
}
```
### With Icons
```tsx
"use client";
import {
BellFill,
BellSlash,
Check,
Microphone,
MicrophoneSlash,
Moon,
Power,
Sun,
VolumeFill,
VolumeSlashFill,
} from "@gravity-ui/icons";
import {Switch} from "@heroui/react";
export function WithIcons() {
const icons = {
check: {
off: Power,
on: Check,
selectedControlClass: "bg-green-500/80",
},
darkMode: {
off: Moon,
on: Sun,
selectedControlClass: "",
},
microphone: {
off: Microphone,
on: MicrophoneSlash,
selectedControlClass: "bg-red-500/80",
},
notification: {
off: BellSlash,
on: BellFill,
selectedControlClass: "bg-purple-500/80",
},
volume: {
off: VolumeFill,
on: VolumeSlashFill,
selectedControlClass: "bg-blue-500/80",
},
};
return (
);
}
```
### With Description
```tsx
import {Description, Switch} from "@heroui/react";
export function WithDescription() {
return (
Public profile
Allow others to see your profile information
);
}
```
### Group
```tsx
import {Switch, SwitchGroup} from "@heroui/react";
export function Group() {
return (
Allow Notifications
Marketing emails
Social media updates
);
}
```
### Group Horizontal
```tsx
import {Switch, SwitchGroup} from "@heroui/react";
export function GroupHorizontal() {
return (
Notifications
Marketing
Social
);
}
```
### Render Props
```tsx
"use client";
import {Switch} from "@heroui/react";
export function RenderProps() {
return (
{({isSelected}) => (
{isSelected ? "Enabled" : "Disabled"}
)}
);
}
```
### Form Integration
```tsx
"use client";
import {Button, Switch, SwitchGroup} from "@heroui/react";
import React from "react";
export function Form() {
const handleSubmit = (e: React.FormEvent) => {
e.preventDefault();
const formData = new FormData(e.target as HTMLFormElement);
alert(
`Form submitted with:\n${Array.from(formData.entries())
.map(([key, value]) => `${key}: ${value}`)
.join("\n")}`,
);
};
return (
);
}
```
### Custom Styles
```tsx
"use client";
import {Check, Power} from "@gravity-ui/icons";
import {Switch} from "@heroui/react";
export function CustomStyles() {
return (
{({isSelected}) => (
<>
{isSelected ? (
) : (
)}
)}
);
}
```
### Custom Render Function
```tsx
"use client";
import {Switch} from "@heroui/react";
export function CustomRenderFunction() {
return (
}>
Enable notifications
);
}
```
## Related Components
* **Label**: Accessible label for form controls
* **Description**: Helper text for form fields
* **Button**: Allows a user to perform an action
## Styling
### Passing Tailwind CSS classes
You can customize individual Switch components:
```tsx
import { Switch, Label } from '@heroui/react';
function CustomSwitch() {
return (
{({isSelected}) => (
<>
Custom Switch
)}
);
}
```
Or customize the SwitchGroup layout:
```tsx
import { Switch, SwitchGroup, Label } from '@heroui/react';
function CustomSwitchGroup() {
return (
Option 1
Option 2
);
}
```
### Customizing the component classes
To customize the Switch component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
```css
@layer components {
.switch {
@apply inline-flex gap-3 items-center;
}
.switch__control {
@apply h-5 w-8 bg-gray-400 data-[selected=true]:bg-blue-500;
}
.switch__thumb {
@apply bg-white shadow-sm;
}
.switch__content {
@apply items-center gap-3;
}
.switch__icon {
@apply h-3 w-3 text-current;
}
}
```
HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
### CSS Classes
#### Switch Classes
The Switch component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/switch.css)):
* `.switch` - Base switch container (the field)
* `.switch__content` - Clickable label wrapping the control and label text
* `.switch__control` - Switch control track
* `.switch__thumb` - Switch thumb that moves
* `.switch__icon` - Optional icon inside the thumb
* `.switch--sm` - Small size variant
* `.switch--md` - Medium size variant (default)
* `.switch--lg` - Large size variant
#### SwitchGroup Classes
The SwitchGroup component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/switch-group.css)):
* `.switch-group` - Switch group container
* `.switch-group__items` - Container for switch items
* `.switch-group--horizontal` - Horizontal layout
* `.switch-group--vertical` - Vertical layout (default)
### Interactive States
The switch supports both CSS pseudo-classes and data attributes for flexibility:
* **Selected**: `[data-selected="true"]` (thumb position and background color change)
* **Hover**: `:hover` or `[data-hovered="true"]` on `Switch.Control` (button)
* **Focus**: `:focus-visible` or `[data-focus-visible="true"]` on the button (shows focus ring on track)
* **Disabled**: `[data-disabled="true"]` on the field (reduced opacity, including help text)
* **Pressed**: `:active` or `[data-pressed="true"]`
## API Reference
### Switch Props
Inherits from [React Aria SwitchField](https://react-spectrum.adobe.com/react-aria/Switch.html).
| Prop | Type | Default | Description |
| -------------------- | ------------------------------------------------------------------------------ | ---------- | ----------------------------------------------------------------- |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | The size of the switch |
| `isSelected` | `boolean` | `false` | Whether the switch is on |
| `defaultSelected` | `boolean` | `false` | Whether the switch is on by default (uncontrolled) |
| `isDisabled` | `boolean` | `false` | Whether the switch is disabled |
| `isInvalid` | `boolean` | `false` | Whether the switch is invalid |
| `isReadOnly` | `boolean` | `false` | Whether the switch is read only |
| `isRequired` | `boolean` | `false` | Whether the switch must be selected |
| `validate` | `(value: boolean) => ValidationError \| true \| null \| undefined` | - | Custom validation function |
| `validationBehavior` | `'native' \| 'aria'` | `'native'` | Whether to use native HTML form validation or ARIA |
| `name` | `string` | - | The name of the input element, used when submitting an HTML form |
| `value` | `string` | - | The value of the input element, used when submitting an HTML form |
| `onChange` | `(isSelected: boolean) => void` | - | Handler called when the switch value changes |
| `onPress` | `(e: PressEvent) => void` | - | Handler called when the switch is pressed |
| `children` | `React.ReactNode \| (values: SwitchFieldRenderProps) => React.ReactNode` | - | Switch content or field render prop |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
### Switch.Content Props
The clickable `
# Badge
**Category**: react
**URL**: https://v3.heroui.com/en/docs/react/components/badge
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(data-display)/badge.mdx
> Displays a small indicator positioned relative to another element, commonly used for notification counts, status dots, and labels
## Import
```tsx
import { Badge } from '@heroui/react';
```
## Anatomy
Badge is designed to be positioned relative to another element using `Badge.Anchor`. Plain-text children are automatically wrapped in ``.
> For standalone label usage, use the [Chip](/docs/react/components/chip) component instead.
```tsx
5
```
### Usage
```tsx
import {Avatar, Badge} from "@heroui/react";
const GREEN_AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg";
const ORANGE_AVATAR_URL =
"https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg";
const BLUE_AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg";
export function BadgeBasic() {
return (
);
}
```
### Sizes
```tsx
import {Avatar, Badge} from "@heroui/react";
const AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg";
export function BadgeSizes() {
const sizes = ["sm", "md", "lg"] as const;
return (
{sizes.map((size) => (
JD
5
))}
);
}
```
### Variants
```tsx
import {Avatar, Badge, Separator} from "@heroui/react";
import React from "react";
const AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg";
export function BadgeVariants() {
const variants = ["primary", "secondary", "soft"] as const;
const colors = ["accent", "default", "success", "warning", "danger"] as const;
return (
{variants.map((variant, index) => (
{variant}
{colors.map((color) => (
JD
5
))}
{index < variants.length - 1 && }
))}
);
}
```
### Placements
```tsx
import {Avatar, Badge} from "@heroui/react";
const AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg";
export function BadgePlacements() {
const placements = ["top-right", "top-left", "bottom-right", "bottom-left"] as const;
return (
{placements.map((placement) => (
JD{placement}
))}
);
}
```
### With Content
Badge supports text, numbers, and icons as content. When no children are provided, it renders as a dot indicator.
```tsx
import {Bell} from "@gravity-ui/icons";
import {Avatar, Badge} from "@heroui/react";
const AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg";
export function BadgeWithContent() {
return (
JD
5
JD
New
JD
99+
JD
);
}
```
### Dot Badge
Empty badges act as status indicators — useful for online/offline states or activity signals.
```tsx
import {Avatar, Badge} from "@heroui/react";
const AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg";
export function BadgeDot() {
const colors = ["accent", "success", "warning", "danger"] as const;
return (
{colors.map((color) => (
JD
))}
);
}
```
## Related Components
* **Avatar**: Display user profile images
* **Chip**: Compact elements for tags and filters
## Styling
### Passing Tailwind CSS classes
You can style the root container and individual slots:
```tsx
import {Badge, Avatar} from '@heroui/react';
function CustomBadge() {
return (
99+
);
}
```
### Customizing the component classes
To customize the Badge component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
```css
@layer components {
.badge {
@apply rounded-full text-xs;
}
.badge__label {
@apply font-semibold;
}
.badge--accent {
@apply shadow-sm;
}
}
```
HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
### CSS Classes
The Badge component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/badge.css)):
#### Base Classes
* `.badge` - Base badge container styles
* `.badge__label` - Label text slot styles
* `.badge-anchor` - Positioning wrapper for the anchored element
#### Color Classes
* `.badge--accent` - Accent color variant
* `.badge--danger` - Danger color variant
* `.badge--default` - Default color variant
* `.badge--success` - Success color variant
* `.badge--warning` - Warning color variant
#### Variant Classes
* `.badge--primary` - Primary variant with filled background
* `.badge--secondary` - Secondary variant with default background
* `.badge--soft` - Soft variant with lighter background
#### Size Classes
* `.badge--sm` - Small size
* `.badge--md` - Medium size (default)
* `.badge--lg` - Large size
#### Placement Classes
* `.badge--top-right` - Position at top-right corner (default)
* `.badge--top-left` - Position at top-left corner
* `.badge--bottom-right` - Position at bottom-right corner
* `.badge--bottom-left` - Position at bottom-left corner
#### Compound Variant Classes
Badges support combining variant and color classes (e.g., `.badge--primary.badge--accent`). The following combinations have default styles defined:
**Primary Variants:**
* `.badge--primary.badge--accent` - Primary accent with filled background
* `.badge--primary.badge--default` - Primary default with filled background
* `.badge--primary.badge--success` - Primary success with filled background
* `.badge--primary.badge--warning` - Primary warning with filled background
* `.badge--primary.badge--danger` - Primary danger with filled background
**Soft Variants:**
* `.badge--soft.badge--accent` - Soft accent with lighter background
* `.badge--soft.badge--default` - Soft default with lighter background
* `.badge--soft.badge--success` - Soft success with lighter background
* `.badge--soft.badge--warning` - Soft warning with lighter background
* `.badge--soft.badge--danger` - Soft danger with lighter background
## API Reference
### Badge Props
| Prop | Type | Default | Description |
| ----------- | -------------------------------------------------------------- | ------------- | -------------------------------------------------------------------------------------------- |
| `children` | `React.ReactNode` | - | Content to display inside the badge (text, number, or icon). When omitted, renders as a dot. |
| `className` | `string` | - | Additional CSS classes for the root element |
| `color` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"default"` | Color variant of the badge |
| `variant` | `"primary" \| "secondary" \| "soft"` | `"primary"` | Visual style variant |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size of the badge |
| `placement` | `"top-right" \| "top-left" \| "bottom-right" \| "bottom-left"` | `"top-right"` | Position of the badge relative to its anchor |
### Badge.Anchor Props
| Prop | Type | Default | Description |
| ----------- | ----------------- | ------- | --------------------------------------------------------- |
| `children` | `React.ReactNode` | - | The element to anchor the badge to, plus the Badge itself |
| `className` | `string` | - | Additional CSS classes for the anchor wrapper |
### Badge.Label Props
| Prop | Type | Default | Description |
| ----------- | ----------------- | ------- | ----------------------------------------- |
| `children` | `React.ReactNode` | - | Label text content |
| `className` | `string` | - | Additional CSS classes for the label slot |
# Chip
**Category**: react
**URL**: https://v3.heroui.com/en/docs/react/components/chip
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(data-display)/chip.mdx
> Small informational badges for displaying labels, statuses, and categories
## Import
```tsx
import { Chip } from '@heroui/react';
```
## Anatomy
Import the Chip component and access all parts using dot notation.
> Plain-text children are automatically wrapped in ``.
```tsx
Label text
```
### Usage
```tsx
import {Chip} from "@heroui/react";
export function ChipBasic() {
return (
DefaultAccentSuccessWarningDanger
);
}
```
### Variants
```tsx
import {CircleDashed} from "@gravity-ui/icons";
import {Chip, Separator} from "@heroui/react";
import React from "react";
export function ChipVariants() {
const sizes = ["lg", "md", "sm"] as const;
const variants = ["primary", "secondary", "tertiary", "soft"] as const;
const colors = ["accent", "default", "success", "warning", "danger"] as const;
return (
{sizes.map((size, index) => (
{size}
{/* Color labels header */}
{colors.map((color) => (
{color}
))}
{variants.map((variant) => (
{variant}
{colors.map((color) => (
Label
))}
))}
{index < sizes.length - 1 && }
))}
);
}
```
### With Icons
```tsx
import {ChevronDown, CircleCheckFill, CircleFill, Clock, Xmark} from "@gravity-ui/icons";
import {Chip} from "@heroui/react";
export function ChipWithIcon() {
return (
InformationCompletedPendingFailedLabel
);
}
```
### Statuses
```tsx
import {Ban, Check, CircleFill, CircleInfo, TriangleExclamation} from "@gravity-ui/icons";
import {Chip} from "@heroui/react";
export function ChipStatuses() {
return (
DefaultActivePendingInactive
New FeatureAvailableBetaDeprecated
);
}
```
## Related Components
* **Avatar**: Display user profile images
* **CloseButton**: Button for dismissing overlays
* **Separator**: Visual divider between content
## Styling
### Passing Tailwind CSS classes
You can style the root container and individual slots:
```tsx
import {Chip} from '@heroui/react';
function CustomChip() {
return (
Custom Styled
);
}
```
### Customizing the component classes
To customize the Chip component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
```css
@layer components {
.chip {
@apply rounded-full text-xs;
}
.chip__label {
@apply font-medium;
}
.chip--accent {
@apply border-accent/20;
}
.chip--accent .chip__label {
@apply text-accent;
}
}
```
HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
### CSS Classes
The Chip component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/chip.css)):
#### Base Classes
* `.chip` - Base chip container styles
* `.chip__label` - Label text slot styles
#### Color Classes
* `.chip--accent` - Accent color variant
* `.chip--danger` - Danger color variant
* `.chip--default` - Default color variant
* `.chip--success` - Success color variant
* `.chip--warning` - Warning color variant
#### Variant Classes
* `.chip--primary` - Primary variant with filled background
* `.chip--secondary` - Secondary variant with border
* `.chip--tertiary` - Tertiary variant with transparent background
* `.chip--soft` - Soft variant with lighter background
#### Size Classes
* `.chip--sm` - Small size
* `.chip--md` - Medium size (default)
* `.chip--lg` - Large size
#### Compound Variant Classes
Chips support combining variant and color classes (e.g., `.chip--secondary.chip--accent`). The following combinations have default styles defined:
**Primary Variants:**
* `.chip--primary.chip--accent` - Primary accent combination with filled background
* `.chip--primary.chip--success` - Primary success combination with filled background
* `.chip--primary.chip--warning` - Primary warning combination with filled background
* `.chip--primary.chip--danger` - Primary danger combination with filled background
**Soft Variants:**
* `.chip--accent.chip--soft` - Soft accent combination with lighter background
* `.chip--success.chip--soft` - Soft success combination with lighter background
* `.chip--warning.chip--soft` - Soft warning combination with lighter background
* `.chip--danger.chip--soft` - Soft danger combination with lighter background
**Note:** You can apply custom styles to any variant-color combination (e.g., `.chip--secondary.chip--accent`, `.chip--tertiary.chip--success`) using the `@layer components` directive in your CSS.
## API Reference
### Chip Props
| Prop | Type | Default | Description |
| ----------- | ------------------------------------------------------------- | ------------- | ------------------------------------------- |
| `children` | `React.ReactNode` | - | Content to display inside the chip |
| `className` | `string` | - | Additional CSS classes for the root element |
| `color` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"default"` | Color variant of the chip |
| `variant` | `"primary" \| "secondary" \| "tertiary" \| "soft"` | `"secondary"` | Visual style variant |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size of the chip |
### Chip.Label Props
| Prop | Type | Default | Description |
| ----------- | ----------------- | ------- | ----------------------------------------- |
| `children` | `React.ReactNode` | - | Label text content |
| `className` | `string` | - | Additional CSS classes for the label slot |
# Table
**Category**: react
**URL**: https://v3.heroui.com/en/docs/react/components/table
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(data-display)/table.mdx
> Tables display structured data in rows and columns with support for sorting, selection, column resizing, and infinite scrolling.
## Import
```tsx
import { Table } from '@heroui/react';
```
### Usage
```tsx
import {Table} from "@heroui/react";
export function Basic() {
return (
);
}
```
### Anatomy
Import the Table component and access all parts using dot notation.
```tsx
import { Table } from '@heroui/react';
export default () => (