# ColorSwatchPicker **Category**: react **URL**: https://www.heroui.com/docs/react/components/color-swatch-picker **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/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 (
Circle (default) {colors.map((color) => ( ))}
Square {colors.map((color) => ( ))}
); } ``` ### Sizes ```tsx import {ColorSwatchPicker} from "@heroui/react"; const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"]; const sizes = ["xs", "sm", "md", "lg", "xl"] as const; export function Sizes() { return (
{sizes.map((size) => (
{size} {colors.map((color) => ( ))}
))}
); } ``` ### Stack Layout ```tsx import {ColorSwatchPicker} from "@heroui/react"; const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"]; export function StackLayout() { return ( {colors.map((color) => ( ))} ); } ``` ### Default Value ```tsx import {ColorSwatchPicker} from "@heroui/react"; const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"]; export function DefaultValue() { return ( {colors.map((color) => ( ))} ); } ``` ### Controlled ```tsx "use client"; import {ColorSwatchPicker, parseColor} from "@heroui/react"; import {useState} from "react"; const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"]; export function Controlled() { const [value, setValue] = useState(parseColor("#F43F5E")); return (
{colors.map((color) => ( ))}

Selected: {value.toString("hex")}

); } ``` ### 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%)'); ```