---
title: "Color Area"
description: "A two-dimensional area for selecting color values in a specific color space."
canonical_url: "https://vinicunca.dev/akar/components/color-area"
---
# Color Area

> A two-dimensional area for selecting color values in a specific color space.

`````vue [index.vue]
<script setup lang="ts">
import {
  ColorAreaArea,
  ColorAreaRoot,
  ColorAreaThumb,
} from 'akar'
import { ref } from 'vue'
import './styles.css'

const color = ref('#56d799')
</script>

<template>
  <div class="akar-demo akar-demo-ColorArea">
    <div class="ColorAreaDemo">
        <div class="ColorAreaValue">
          Current: {{ color }}
        </div>

        <ColorAreaRoot
          v-slot="{ style }"
          v-model="color"
          class="ColorAreaRoot"
        >
          <ColorAreaArea
            class="ColorAreaArea"
            :style="style"
          >
            <ColorAreaThumb class="ColorAreaThumb" />
          </ColorAreaArea>
        </ColorAreaRoot>
      </div>
  </div>
</template>
```

```css [styles.css]
@import '../_colors/black-alpha.css';
@import '../_colors/grass.css';
@import '../_colors/mauve.css';

@scope (.akar-demo-ColorArea) {
.ColorAreaDemo {
  display: flex;
  flex-direction: column;
  gap: 16px;
}

.ColorAreaValue {
  color: var(--mauve-11);
  font-size: 14px;
}

.ColorAreaRoot {
  position: relative;
}

.ColorAreaArea {
  position: relative;
  width: 200px;
  height: 200px;
  overflow: hidden;
  border-radius: 8px;
}

.ColorAreaArea:focus {
  outline: none;
  box-shadow: 0 0 0 2px var(--grass-7);
}

.ColorAreaThumb {
  display: block;
  width: 16px;
  height: 16px;
  cursor: pointer;
  background-color: white;
  border: 2px solid var(--mauve-8);
  border-radius: 9999px;
  box-shadow: 0 2px 10px var(--black-a7);
}
}
```

## Features

- Supports HSL, HSB, and RGB color spaces.
- Configurable channels for horizontal (x) and vertical (y) axes.
- Full keyboard navigation support.
- Pointer/touch interaction for value selection.
- Preserves hue information when saturation is 0.
- Form integration with hidden inputs.

## Installation

Install the component from your command line.

```bash [pnpm]
pnpm add akar
```

```bash [yarn]
yarn add akar
```

```bash [npm]
npm install akar
```

```bash [bun]
bun add akar
```

> [!TIP]
> 
> Looking for a complete color picker? Check out the [Color Picker example](https://vinicunca.dev/examples/color-picker) that combines Color Area, Color Slider, Color Field, and Color Swatch components.

## Anatomy

Import all parts and piece them together.

```vue
<script setup>
import {
  ColorAreaArea,
  ColorAreaRoot,
  ColorAreaThumb,
} from 'akar';
</script>

<template>
  <ColorAreaRoot v-slot="{ style }">
    <ColorAreaArea :style="style">
      <ColorAreaThumb />
    </ColorAreaArea>
  </ColorAreaRoot>
</template>
```

## API Reference

### ColorAreaRoot

The root component that provides the color area context and state management.

**Props**

| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| `as` | `"div"` | `AsTag \| Component` | The element or component this component should render as. Can be overwritten by `asChild`. |
| `asChild` |  | `boolean` | Change the default rendered element for the one passed as a child, merging their props and behavior.<br><br>Read our [Composition](/akar/guides/composition) guide for more details. |
| `colorSpace` | `"hsl"` | `"hsl" \| "rgb" \| "hsb"` | The color space to operate in. |
| `defaultValue` | `"#ff0000"` | `string \| Color` | The default color value (uncontrolled). |
| `disabled` | `false` | `boolean` | When `true`, prevents the user from interacting with the area. |
| `modelValue` |  | `string \| Color` | The color value (controlled). Can be a hex string or Color object. |
| `name` |  | `string` | The name of the field. Submitted with its owning form as part of a name/value pair. |
| `required` |  | `boolean` | When `true`, indicates that the user must set the value before the owning form can be submitted. |
| `xChannel` | `"hue"` | `"hue" \| "saturation" \| "red" \| "green" \| "blue" \| "alpha" \| "lightness" \| "brightness"` | Color channel for the horizontal (x) axis. |
| `xName` |  | `string` | The name of the x channel input element for form submission. |
| `yChannel` | `"saturation"` | `"hue" \| "saturation" \| "red" \| "green" \| "blue" \| "alpha" \| "lightness" \| "brightness"` | Color channel for the vertical (y) axis. |
| `yName` |  | `string` | The name of the y channel input element for form submission. |

**Events**

| Event | Payload | Description |
| --- | --- | --- |
| `change` | `value: string` |  |
| `changeEnd` | `value: string` |  |
| `update:color` | `value: Color` |  |
| `update:modelValue` | `value: string` |  |

**Slots**

| Slot | Payload | Description |
| --- | --- | --- |
| `style` | `CSSProperties` | CSS styles for the color area background gradient |

[ColorAreaRoot.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/ColorArea/ColorAreaRoot.vue)

### ColorAreaArea

The interactive area component where users can select color values by clicking or dragging.

**Props**

| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| `as` | `"div"` | `AsTag \| Component` | The element or component this component should render as. Can be overwritten by `asChild`. |
| `asChild` |  | `boolean` | Change the default rendered element for the one passed as a child, merging their props and behavior.<br><br>Read our [Composition](/akar/guides/composition) guide for more details. |

[ColorAreaArea.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/ColorArea/ColorAreaArea.vue)

### ColorAreaThumb

The draggable thumb component that indicates the current position in the color area.

**Props**

| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| `as` | `"span"` | `AsTag \| Component` | The element or component this component should render as. Can be overwritten by `asChild`. |
| `asChild` |  | `boolean` | Change the default rendered element for the one passed as a child, merging their props and behavior.<br><br>Read our [Composition](/akar/guides/composition) guide for more details. |

[ColorAreaThumb.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/ColorArea/ColorAreaThumb.vue)

## Examples

### HSL Saturation/Lightness

A common use case for color area is selecting saturation and lightness in HSL color space.

```vue
<script setup>
import {
  ColorAreaArea,
  ColorAreaRoot,
  ColorAreaThumb,
} from 'akar';
import { ref } from 'vue';

const color = ref('#3b82f6');
</script>

<template>
  <ColorAreaRoot
    v-slot="{ style }"
    v-model="color"
    color-space="hsl"
    x-channel="saturation"
    y-channel="lightness"
  >
    <ColorAreaArea :style="style">
      <ColorAreaThumb />
    </ColorAreaArea>
  </ColorAreaRoot>
</template>
```

### RGB Red/Green Selector

Using RGB color space with red and green channels.

```vue
<script setup>
import {
  ColorAreaArea,
  ColorAreaRoot,
  ColorAreaThumb,
} from 'akar';
import { ref } from 'vue';

const color = ref('#ff0000');
</script>

<template>
  <ColorAreaRoot
    v-slot="{ style }"
    v-model="color"
    color-space="rgb"
    x-channel="red"
    y-channel="green"
  >
    <ColorAreaArea :style="style">
      <ColorAreaThumb />
    </ColorAreaArea>
  </ColorAreaRoot>
</template>
```

### Disabled State

Disable interaction with the color area.

```vue
<script setup>
import {
  ColorAreaArea,
  ColorAreaRoot,
  ColorAreaThumb,
} from 'akar';
import { ref } from 'vue';

const color = ref('#3b82f6');
</script>

<template>
  <ColorAreaRoot
    v-slot="{ style }"
    v-model="color"
    disabled
  >
    <ColorAreaArea :style="style">
      <ColorAreaThumb />
    </ColorAreaArea>
  </ColorAreaRoot>
</template>
```

## Accessibility

### Keyboard Interactions

| Key | Description |
| --- | --- |
| `ArrowLeft` | Decreases the x-axis channel value by one step. |
| `ArrowRight` | Increases the x-axis channel value by one step. |
| `ArrowUp` | Increases the y-axis channel value by one step. |
| `ArrowDown` | Decreases the y-axis channel value by one step. |
| `Shift + ArrowKey` | Changes values by 10 steps at a time. |
| `PageUp` | Increases the y-axis channel value by a larger step. |
| `PageDown` | Decreases the y-axis channel value by a larger step. |
| `Home` | Jumps left (decreases x-axis value). |
| `End` | Jumps right (increases x-axis value). |

---

- [GitHub](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/ColorArea)
- [npm](https://www.npmjs.com/package/akar)


## Sitemap

See the full [sitemap](https://vinicunca.dev/sitemap.md) for all pages.