Color Wheel

Since v0.13.9@kobalte/core/color-wheelSource

Allows users to adjust the hue of an HSL or HSB color value on a circular track.

Import

import { ColorWheel } from "@kobalte/core/color-wheel";
// or
import { Root, Track, ... } from "@kobalte/core/color-wheel";

Features

Support for adjusting the hue of an HSL or HSB color value.
Support click or touch on track to change value.
Support right or left direction.
Support for custom value label.
Localized color descriptions for screen reader users.
Can be controlled or uncontrolled.

Anatomy

The color wheel consists of:

ColorWheel: The root container for the color wheel.
ColorWheel.Track: The component that visually represents the color wheel track.
ColorWheel.Thumb: The thumb that is used to visually indicate a value in the color wheel.
ColorWheel.Input: The native html input that is visually hidden in the color wheel thumb.
ColorWheel.Label: The label that gives the user information on the color wheel.
ColorWheel.ValueLabel: The accessible label text representing the current value in a human-readable format.

<ColorWheel>
  <ColorWheel.Label />
  <ColorWheel.ValueLabel />
  <ColorWheel.Track>
    <ColorWheel.Thumb>
      <ColorWheel.Input />
    </ColorWheel.Thumb>
  </ColorWheel.Track>
</ColorWheel>

Example

Label

import { ColorWheel } from "@kobalte/core/color-wheel";

export function BasicExample() {
  return (
    <ColorWheel class={style.ColorWheelRoot}>
      <ColorWheel.Label class={style.ColorWheelLabel}>Label</ColorWheel.Label>
      <ColorWheel.Track class={style.ColorWheelTrack}>
        <ColorWheel.Thumb class={style.ColorWheelThumb}>
          <ColorWheel.Input />
        </ColorWheel.Thumb>
      </ColorWheel.Track>
    </ColorWheel>
  );
}

.ColorWheelRoot {
  position: relative;
  display: flex;
  flex-direction: column;
  align-items: center;
  user-select: none;
  touch-action: none;
}

.ColorWheelTrack {
  position: relative;
  height: 160px;
  width: 160px;
}

.ColorWheelThumb {
  display: block;
  width: 16px;
  height: 16px;
  border-radius: 9999px;
  border: 2px solid #fff;
  background: var(--kb-color-current);
}

.ColorWheelThumb:focus {
  outline: none;
}

.ColorWheelValueLabel {
  display: flex;
  justify-content: space-between;
  width: 20ch;
  text-align: center;
}

.ColorWheelLabel {
  font-size: 14px;
  font-weight: 500;
  user-select: none;
}

Usage

Default value

By default, ColorWheel is uncontrolled with a default value of red (hue = 0). You can change the default value using the defaultValue prop.

Label

import { ColorWheel } from "@kobalte/core/color-wheel";
import { parseColor } from "@kobalte/core/colors";

function App() {
  return (
    <ColorWheel defaultValue={parseColor("hsl(80, 100%, 50%)")}>
      <ColorWheel.Label>Label</ColorWheel.Label>
      <ColorWheel.Track>
        <ColorWheel.Thumb>
          <ColorWheel.Input />
        </ColorWheel.Thumb>
      </ColorWheel.Track>
    </ColorWheel>
  );
}

Controlled value

A ColorWheel can be made controlled using the value prop. The onChange event is fired when the user drags the thumb and receive the new value.

Label

Current color value: hsl(0 100% 50%)

import { createSignal } from "solid-js";

function ControlledValueExample() {
  const [value, setValue] = createSignal(parseColor("hsl(0, 100%, 50%)"));

  return (
    <>
      <ColorWheel value={value()} onChange={setValue}>
        <ColorWheel.Label>Label</ColorWheel.Label>
        <ColorWheel.Track>
          <ColorWheel.Thumb>
            <ColorWheel.Input />
          </ColorWheel.Thumb>
        </ColorWheel.Track>
      </ColorWheel>
      <p>Current color value: {value().toString("hsl")}</p>
    </>
  );
}

Thickness

The thickness prop controls the width of the ColorWheel's circular track. This prop is required.

Label

<ColorWheel thickness={60}>
  <ColorWheel.Label>Label</ColorWheel.Label>
  <ColorWheel.Track>
    <ColorWheel.Thumb>
      <ColorWheel.Input />
    </ColorWheel.Thumb>
  </ColorWheel.Track>
</ColorWheel>

Custom Value Label

Label

hsla(0 100% 50% / 1)

<ColorWheel
  getValueLabel={color =>
    color
      .toFormat("hsl")
      .withChannelValue("saturation", 100)
      .withChannelValue("lightness", 50)
      .withChannelValue("alpha", 1)
      .toString()
  }
>
  <ColorWheel.Label>Label</ColorWheel.Label>
  <ColorWheel.Track>
    <ColorWheel.Thumb>
      <ColorWheel.Input />
    </ColorWheel.Thumb>
  </ColorWheel.Track>
  <div>
    <ColorWheel.ValueLabel />
  </div>
</ColorWheel>

HTML forms

ColorWheel supports the name prop for integration with HTML forms.

function HTMLFormExample() {
  const onSubmit = (e: SubmitEvent) => {
    // handle form submission.
  };

  return (
    <form onSubmit={onSubmit}>
      <ColorWheel name="hue">
        <ColorWheel.Track>
          <ColorWheel.Thumb>
            <ColorWheel.Input />
          </ColorWheel.Thumb>
        </ColorWheel.Track>
      </ColorWheel>
    </form>
  );
}

API Reference

ColorWheel

ColorWheel is equivalent to the Root import from @kobalte/core/color-wheel.

Prop	Description
value	`Color` The controlled value of the color wheel. Must be used in conjunction with `onChange`.
defaultValue	`Color` The value of the color wheel when initially rendered. Use when you do not need to control the state of the color wheel.
thickness	`number` The thickness of the track `0-100`.
onChange	`(value: Color) => void` Event handler called when the value changes.
onChangeEnd	`(value: Color) => void` Event handler called when the value changes at the end of an interaction.
getValueLabel	`(param: Color) => string` A function to get the accessible label text representing the current value in a human-readable format.
name	`string` The name of the color wheel, used when submitting an HTML form.
validationState	`'valid' \| 'invalid'` Whether the color wheel should display its "valid" or "invalid" visual styling.
required	`boolean` Whether the user must check a radio group item before the owning form can be submitted.
disabled	`boolean` Whether the color wheel is disabled.
readOnly	`boolean` Whether the color wheel items can be selected but not changed by the user.
translations	`ColorIntlTranslations` Localization strings.

Data attribute	Description
data-valid	Present when the color wheel is valid according to the validation rules.
data-invalid	Present when the color wheel is invalid according to the validation rules.
data-required	Present when the color wheel is required.
data-disabled	Present when the color wheel is disabled.
data-readonly	Present when the color wheel is read only.

ColorWheel.ValueLabel, ColorWheel.Input, ColorWheel.Thumb and ColorWheel.Track share the same data-attributes.

ColorWheel.Thumb

The current color is available on the thumb using the custom css property --kb-color-current.

Rendered elements

Component	Default rendered element
`ColorWheel`	`div`
`ColorWheel.Track`	`div`
`ColorWheel.Thumb`	`span`
`ColorWheel.Input`	`input`
`ColorWheel.ValueLabel`	`div`
`ColorWheel.Label`	`label`
`ColorWheel.Description`	`div`
`ColorWheel.ErrorMessage`	`div`

Accessibility

Keyboard Interactions

Key	Description
`PageUp`	Increments the value of the thumb by a larger step.
`PageDown`	Decrements the value of the thumb by a larger step.
`ArrowDown`	Decrements the value of the thumb by the step amount.
`ArrowUp`	Increments the value of the thumb by the step amount.
`ArrowRight`	Increments the value of the thumb by the step value.
`ArrowLeft`	Decrements the value of the thumb by the step value.
`Home`	Sets the value of the thumb to the minimum value.
`End`	Sets the value of the thumb to the maximum value.

Last updated: 7/16/26, 7:09 AM

Edit this page on GitHub