# ColorWheel
Package: @mantine/core
Import: import { ColorWheel } from '@mantine/core';
Description: Circular hue selector

## Usage

`ColorWheel` is a circular hue selector. Its value is a hue in degrees, from `0` at the top (red)
increasing clockwise to `360`:

```tsx
import { ColorWheel } from '@mantine/core';

function Demo() {
  return <ColorWheel aria-label="Color wheel" size={180} thickness={24} thumbSize={20} saturation={100} lightness={50} withThumbIndicator={true} />;
}
```


## Controlled

Convert the value to a color with `hsl(hue, 100%, 50%)` or any color conversion function:

```tsx
import { useState } from 'react';
import { ColorSwatch, ColorWheel, Group, Stack, Text } from '@mantine/core';

function Demo() {
  const [hue, setHue] = useState(210);

  return (
    <Stack align="center">
      <Group>
        <ColorSwatch color={`hsl(${hue}, 100%, 50%)`} />
        <Text size="sm">Hue: {hue}°</Text>
      </Group>
      <ColorWheel aria-label="Color wheel" value={hue} onChange={setHue} />
    </Stack>
  );
}
```


## Ring colors

Use `saturation` and `lightness` props (0 to 100) to change the ring colors.
They change only the appearance, the value is always the hue:

```tsx
import { ColorWheel, Group, Stack, Text } from '@mantine/core';

function Demo() {
  return (
    <Group justify="center">
      <Stack align="center" gap="xs">
        <ColorWheel aria-label="Vivid" saturation={100} lightness={50} defaultValue={210} />
        <Text size="sm">saturation=100 lightness=50</Text>
      </Stack>

      <Stack align="center" gap="xs">
        <ColorWheel aria-label="Pastel" saturation={60} lightness={70} defaultValue={210} />
        <Text size="sm">saturation=60 lightness=70</Text>
      </Stack>
    </Group>
  );
}
```


## onChangeEnd

`onChangeEnd` is called when the user stops dragging the wheel or changes the value with the keyboard.
Use it as a debounced callback to avoid too frequent updates:

```tsx
import { useState } from 'react';
import { ColorWheel, Text } from '@mantine/core';

function Demo() {
  const [value, setValue] = useState(0);
  const [endValue, setEndValue] = useState(0);

  return (
    <>
      <ColorWheel
        aria-label="Color wheel"
        value={value}
        onChange={setValue}
        onChangeEnd={setEndValue}
      />
      <Text mt="md">Current value: {value}</Text>
      <Text>End value: {endValue}</Text>
    </>
  );
}
```


## Disabled

Set `disabled` to prevent user interaction:

```tsx
import { ColorWheel } from '@mantine/core';

function Demo() {
  return <ColorWheel aria-label="Color wheel" defaultValue={210} disabled />;
}
```


## ColorWheel with uncontrolled forms

Set `name` prop to include the hue value in the `FormData` object on form submission
and `defaultValue` to set the initial value:

```tsx
import { ColorWheel } from '@mantine/core';

function Demo() {
  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();
        const formData = new FormData(event.currentTarget);
        console.log('Hue value:', formData.get('hue'));
      }}
    >
      <ColorWheel name="hue" defaultValue={120} />
      <button type="submit">Submit</button>
    </form>
  );
}
```

## Accessibility

Set `aria-label` to make the wheel accessible for screen readers:

```tsx
import { ColorWheel } from '@mantine/core';

function Demo() {
  return <ColorWheel aria-label="Hue" />;
}
```

## Keyboard interactions

When the thumb is focused, arrow keys wrap around at `0` and `360`:

## Based on use-radial-move

`ColorWheel` is based on the [use-radial-move](https://alpha.mantine.dev/llms/hooks-use-radial-move.md) hook.
Use it to build a custom radial selector:

```tsx
// Demo.tsx
import { useState } from 'react';
import { Box } from '@mantine/core';
import { useRadialMove } from '@mantine/hooks';
import classes from './Demo.module.css';

function Demo() {
  const [value, setValue] = useState(115);
  const { ref } = useRadialMove(setValue);

  return (
    <Box className={classes.root} ref={ref} style={{ '--angle': `${value}deg` }}>
      <div className={classes.value}>{value}°</div>
      <div className={classes.thumb} />
    </Box>
  );
}

// Demo.module.css
.root {
  position: relative;
  width: 160px;
  height: 160px;
  border-radius: 160px;
  display: flex;
  align-items: center;
  justify-content: center;

  --empty-color: light-dark(var(--mantine-color-gray-2), var(--mantine-color-dark-6));
  --filled-color: light-dark(var(--mantine-color-blue-6), var(--mantine-color-blue-8));

  background-image: conic-gradient(
    var(--filled-color) 0deg,
    var(--filled-color) var(--angle, 0deg),
    var(--empty-color) var(--angle, 0deg)
  );
}

.value {
  background-color: var(--mantine-color-body);
  width: 132px;
  height: 132px;
  border-radius: 132px;
  display: flex;
  align-items: center;
  justify-content: center;
}

.thumb {
  position: absolute;
  width: 14px;
  height: 160px;
  transform: rotate(var(--angle, 0deg));

  &::before {
    content: '';
    position: absolute;
    width: 14px;
    height: 14px;
    background-color: light-dark(var(--mantine-color-white), var(--filled-color));
    border: 2px solid light-dark(var(--filled-color), var(--mantine-color-white));
    border-radius: 50%;
    left: 50%;
    transform: translateX(-50%);
  }
}
```



#### Props

**ColorWheel props**

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| defaultValue | number | 0 | Uncontrolled component default value, hue in degrees (0–360) |
| disabled | boolean | - | Sets `data-disabled` attribute, disables interactions |
| hiddenInputProps | React.ComponentProps<"input"> | - | Props passed down to the hidden input |
| lightness | number | 50 | Lightness (0–100) used to render the ring colors |
| name | string | - | Hidden input name, use with uncontrolled component |
| onChange | (value: number) => void | - | Called on value change |
| onChangeEnd | (value: number) => void | - | Called after the selection is finished |
| onScrubEnd | () => void | - | Called in `onMouseUp` and `onTouchEnd` |
| onScrubStart | () => void | - | Called in `onMouseDown` and `onTouchStart` |
| saturation | number | 100 | Saturation (0–100) used to render the ring colors |
| size | string \| number | 180 | Wheel outer diameter |
| step | number | 1 | Step between values |
| thickness | number | 24 | Ring thickness in px |
| thumbSize | number | - | Size of the thumb in px. Calculated based on the `thickness` value by default. |
| value | number | - | Controlled component value, hue in degrees (0–360) |
| withThumbIndicator | boolean | true | If set, the thumb indicator is displayed |


#### Styles API

ColorWheel component supports Styles API. With Styles API, you can customize styles of any inner element. Follow the documentation to learn how to use CSS modules, CSS variables and inline styles to get full control over component styles.

**ColorWheel selectors**

| Selector | Static selector | Description |
|----------|----------------|-------------|
| root | .mantine-ColorWheel-root | Root element, contains the hue ring |
| thumb | .mantine-ColorWheel-thumb | Thumb used to select hue value |

**ColorWheel CSS variables**

| Selector | Variable | Description |
|----------|----------|-------------|
| root | --cw-size | Controls `width` and `height` of the component |
| root | --cw-thickness | Controls `thickness` of the hue ring |
| root | --cw-thumb-size | Controls thumb `width` and `height` |
| root | --cw-ring-background | Controls `background` of the hue ring |

**ColorWheel data attributes**

| Selector | Attribute | Condition | Value |
|----------|-----------|-----------|-------|
| root | data-disabled | `disabled` prop is set | - |
| thumb | data-hidden | `withThumbIndicator` prop is `false` | - |
