# ColorArea · HeroUI

> A 2D color picker that allows users to select colors from a gradient area

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

## Import

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

### Usage


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


### Anatomy

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

export default () => (
  <ColorArea>
    <ColorArea.Thumb />
  </ColorArea>
);
```

### With Dots


> Example `color-area-with-dots`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/color-area


### Controlled


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


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


> Example `color-area-space-and-channels`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/color-area


### Disabled


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


### Custom Render Function


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


## Styling

### Passing Tailwind CSS classes

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

function CustomColorArea() {
  return (
    <ColorArea className="max-w-72 rounded-3xl">
      <ColorArea.Thumb />
    </ColorArea>
  );
}
```

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

---

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