---
title: ColorSwatch
description: A visual preview of a color value with accessibility support
links:
  rac: ColorSwatch
  source: color-swatch/color-swatch.tsx
  styles: color-swatch.css
  storybook: Components/Colors/ColorSwatch
---

## Usage

```tsx
import { ColorSwatch } from '@heroui/react';
```

<ComponentPreview
  name="color-swatch-basic"
/>

## Examples

### Sizes

<ComponentPreview
  name="color-swatch-sizes"
/>

### Shapes

<ComponentPreview
  name="color-swatch-shapes"
/>

### Transparency

<ComponentPreview
  name="color-swatch-transparency"
/>

### Render Function

You can use the `style` render props to access the color value and create custom visual effects.

<ComponentPreview
  name="color-swatch-render-function"
/>

### Accessibility

Use `colorName` to provide a custom accessible name for the color, and `aria-label` to add context about how the color is used.

<ComponentPreview
  name="color-swatch-accessibility"
/>

## Customization

### Tailwind CSS

<ComponentPreview name="color-swatch-custom-styles" />

### Global CSS

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;
  }
}
```

## Styling Reference

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 [!toc]
- `.color-swatch` - Base swatch styles with checkered background for transparency

#### Shape Classes [!toc]
- `.color-swatch--circle` - Circular shape (default)
- `.color-swatch--square` - Square shape with rounded corners

#### Size Classes [!toc]
- `.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

| 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<keyof React.JSX.IntrinsicElements, ColorSwatchRenderProps>` | - | 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
<ColorSwatch
  color="#0485F7"
  style={({ color }) => ({
    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

## Related Components

<RelatedComponents component="color-swatch" />
