---
title: "Color Field"
description: "An input field for entering and editing color values in various formats."
canonical_url: "https://vinicunca.dev/akar/components/color-field"
---
# Color Field

> An input field for entering and editing color values in various formats.

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

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

<template>
  <div class="akar-demo akar-demo-ColorField">
    <div class="ColorFieldDemo">
        <ColorFieldRoot
          v-model="color"
          class="ColorFieldRoot"
        >
          <label class="ColorFieldLabel">
            Color
          </label>
          <div class="ColorFieldControl">
            <div
              class="ColorFieldSwatch"
              :style="{ background: color }"
            />
            <ColorFieldInput class="ColorFieldInput" />
          </div>
        </ColorFieldRoot>
      </div>
  </div>
</template>
```

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

@scope (.akar-demo-ColorField) {
.ColorFieldDemo {
  display: flex;
  flex-direction: column;
  gap: 12px;
}

.ColorFieldRoot {
  display: inline-flex;
  flex-direction: column;
  gap: 4px;
}

.ColorFieldLabel {
  color: var(--mauve-12);
  font-size: 14px;
  font-weight: 500;
}

.ColorFieldControl {
  display: flex;
  gap: 8px;
  align-items: center;
}

.ColorFieldSwatch {
  flex-shrink: 0;
  width: 32px;
  height: 32px;
  border-radius: 4px;
  box-shadow: inset 0 0 0 1px var(--black-a7);
}

.ColorFieldInput {
  width: 128px;
  padding: 8px 12px;
  color: var(--mauve-12);
  font-size: 14px;
  background-color: var(--black-a5);
  border: none;
  border-radius: 6px;
  box-shadow: 0 0 0 1px var(--black-a9);
}

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

.ColorFieldInput:disabled {
  cursor: not-allowed;
  opacity: 0.5;
}
}
```

## Features

- Supports hex color input mode.
- Individual color channel editing mode.
- Keyboard navigation with arrow keys.
- Mouse wheel support for increment/decrement.
- Page Up/Down for larger value changes.
- Home/End keys to jump to min/max values.
- Form integration with hidden inputs.
- Support for HSL, HSB, and RGB color spaces.

## 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 {
  ColorFieldInput,
  ColorFieldRoot,
} from 'akar';
</script>

<template>
  <ColorFieldRoot>
    <ColorFieldInput />
  </ColorFieldRoot>
</template>
```

## API Reference

### ColorFieldRoot

The root component that provides the color field 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. |
| `channel` |  | `"hue" \| "saturation" \| "red" \| "green" \| "blue" \| "alpha" \| "lightness" \| "brightness"` | The color channel to display. If not provided, displays hex value. |
| `colorSpace` | `"hsl"` | `"hsl" \| "rgb" \| "hsb"` | The color space to operate in when displaying a channel. |
| `defaultValue` | `"#000000"` | `string \| Color` | The default color value (uncontrolled). |
| `disabled` | `false` | `boolean` | When `true`, prevents the user from interacting with the field. |
| `disableWheelChange` | `false` | `boolean` | When `true`, prevents the value from changing on wheel scroll. |
| `locale` |  | `string` | The locale to use for number formatting. |
| `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. |
| `placeholder` |  | `string` | Placeholder text when the field is empty. |
| `readonly` | `false` | `boolean` | When `true`, the field is read-only. |
| `required` |  | `boolean` | When `true`, indicates that the user must set the value before the owning form can be submitted. |
| `step` |  | `number` | Custom step value for increment/decrement. Defaults to channel step or 1 for hex. |

**Events**

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

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

### ColorFieldInput

The input element for entering color values.

**Props**

| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| `as` | `"input"` | `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. |

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

## Examples

### Hex Color Input

Basic hex color input field.

```vue
<script setup>
import {
  ColorFieldInput,
  ColorFieldRoot,
} from 'akar';
import { ref } from 'vue';

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

<template>
  <ColorFieldRoot v-model="color">
    <ColorFieldInput />
  </ColorFieldRoot>
</template>
```

### Channel Input

Input for a specific color channel (e.g., hue).

```vue
<script setup>
import {
  ColorFieldInput,
  ColorFieldRoot,
} from 'akar';
import { ref } from 'vue';

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

<template>
  <ColorFieldRoot
    v-model="color"
    color-space="hsl"
    channel="hue"
  >
    <ColorFieldInput />
  </ColorFieldRoot>
</template>
```

### With Wheel Control Disabled

Prevent changing values with mouse wheel.

```vue
<script setup>
import {
  ColorFieldInput,
  ColorFieldRoot,
} from 'akar';
import { ref } from 'vue';

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

<template>
  <ColorFieldRoot
    v-model="color"
    disable-wheel-change
  >
    <ColorFieldInput />
  </ColorFieldRoot>
</template>
```

### Read-only Mode

Display the color value without allowing edits.

```vue
<script setup>
import {
  ColorFieldInput,
  ColorFieldRoot,
} from 'akar';
import { ref } from 'vue';

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

<template>
  <ColorFieldRoot
    v-model="color"
    readonly
  >
    <ColorFieldInput />
  </ColorFieldRoot>
</template>
```

## Accessibility

### Keyboard Interactions

| Key | Description |
| --- | --- |
| `ArrowUp` | Increases the value by one step. |
| `ArrowDown` | Decreases the value by one step. |
| `PageUp` | Increases the value by 10 steps. |
| `PageDown` | Decreases the value by 10 steps. |
| `Home` | Sets the value to minimum. |
| `End` | Sets the value to maximum. |
| `Enter` | Commits the current input value. |

---

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


## Sitemap

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