Usage

import { ColorSwatchPicker, parseColor } from '@heroui/react';

Anatomy

import { ColorSwatchPicker } from '@heroui/react';

export default () => (
  <ColorSwatchPicker>
    <ColorSwatchPicker.Item color="#F43F5E">
      <ColorSwatchPicker.Swatch />
      <ColorSwatchPicker.Indicator />
    </ColorSwatchPicker.Item>
    <ColorSwatchPicker.Item color="#D946EF">
      <ColorSwatchPicker.Swatch />
      <ColorSwatchPicker.Indicator />
    </ColorSwatchPicker.Item>
    <ColorSwatchPicker.Item color="#8B5CF6">
      <ColorSwatchPicker.Swatch />
      <ColorSwatchPicker.Indicator />
    </ColorSwatchPicker.Item>
  </ColorSwatchPicker>
);

Examples

Variants

Circle (default)

Square

Sizes

Disabled

Stack Layout

Default Value

Controlled

Selected: #F43F5E

Custom Indicator

Render Function

Customization

Tailwind CSS

Global CSS

To customize the ColorSwatchPicker component classes, you can use the @layer components directive. Learn more.

@layer components {
  .color-swatch-picker {
    @apply gap-4;
  }

  .color-swatch-picker__item {
    @apply shadow-md;
  }

  .color-swatch-picker__swatch {
    @apply border-2 border-white;
  }
}

Styling Reference

HeroUI follows the BEM 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):

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

Inherits from React Aria ColorSwatchPicker.

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<keyof React.JSX.IntrinsicElements, ColorSwatchPickerRenderProps>`	-	Overrides the default DOM element with a custom render function.

ColorSwatchPicker.Item

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<keyof React.JSX.IntrinsicElements, ColorSwatchPickerItemRenderProps>`	-	Overrides the default DOM element with a custom render function.

ColorSwatchPicker.Swatch

Prop	Type	Default	Description
`className`	`string`	-	Additional CSS classes

parseColor

The parseColor function is re-exported from React Aria Components for convenience:

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

ColorField

ColorArea

ColorSwatchPicker

On this page