# ColorSwatch · HeroUI

> A visual preview of a color value with accessibility support

- Page: https://jiguang132.com/systems/heroui/docs/components/color-swatch
- Based on: HeroUI documentation (Apache-2.0) @ 60edd8ed751b1d2a270623fbb182bbcfa8baa9af

## Import

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

### Usage


> Example `color-swatch-basic`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/color-swatch


### Sizes


> Example `color-swatch-sizes`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/color-swatch


### Shapes


> Example `color-swatch-shapes`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/color-swatch


### Transparency


> Example `color-swatch-transparency`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/color-swatch


### Custom Styles with Render Props

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


> Example `color-swatch-custom-styles`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/color-swatch


### Accessibility

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


> Example `color-swatch-accessibility`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/color-swatch


### Custom Render Function


> Example `color-swatch-custom-render-function`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/color-swatch


## Styling

### Passing Tailwind CSS classes

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

function CustomColorSwatch() {
  return (
    <ColorSwatch
      className="size-12 rounded-lg"
      color="#0485F7"
    />
  );
}
```

### 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<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

---

Index of all JGuang resources: https://jiguang132.com/llms.txt