useColorArea

Provides the behavior and accessibility implementation for a color area component. Color area allows users to adjust two channels of an RGB, HSL or HSB color value against a two-dimensional gradient background.

Example

ColorArea.tsx

ColorArea.css

ColorThumb.css

Example

ColorArea.tsx

ColorArea.css

ColorThumb.css

import {ColorArea} from './ColorArea';

<ColorArea defaultValue="hsl(30, 100%, 50%)" xChannel="saturation" yChannel="lightness" />

API

<ColorArea>
  <ColorThumb />
</ColorArea>

useColorAreaState(props: ColorAreaProps): ColorAreaStateuseColorArea(props: AriaColorAreaOptions, state: ColorAreaState): ColorAreaAria

ColorAreaState

Properties

Name	Type
`xValue`	`number`
The current value of the horizontal axis channel displayed by the color area.
`yValue`	`number`
The current value of the vertical axis channel displayed by the color area.
`isDragging`	`boolean`
Whether the color area is currently being dragged.
`channels`	`{xChannel: ColorChannel, yChannel: ColorChannel, zChannel: ColorChannel }`
Returns the xChannel, yChannel and zChannel names based on the color value.
`xChannelStep`	`number`
The step value of the xChannel, used when incrementing and decrementing.
`yChannelStep`	`number`
The step value of the yChannel, used when incrementing and decrementing.
`xChannelPageStep`	`number`
The page step value of the xChannel, used when incrementing and decrementing.
`yChannelPageStep`	`number`
The page step value of the yChannel, used when incrementing and decrementing.

`value`	`Color`
The current color value displayed by the color area.
`defaultValue`	`Color`
The default value of the color area.

Methods

`setValue(value: string \| Color): void`
Sets the current color value. If a string is passed, it will be parsed to a Color.
`setXValue(value: number): void`
Sets the value for the horizontal axis channel displayed by the color area, and triggers `onChange`.
`setYValue(value: number): void`
Sets the value for the vertical axis channel displayed by the color area, and triggers `onChange`.
`setColorFromPoint(x: number, y: number): void`
Sets the x and y channels of the current color value based on a percentage of the width and height of the color area, and triggers `onChange`.
`getThumbPosition(): {'x': number, 'y': number }`
Returns the coordinates of the thumb relative to the upper left corner of the color area as a percentage.
`incrementX(stepSize?: number): void`
Increments the value of the horizontal axis channel by the channel step or page amount.
`decrementX(stepSize?: number): void`
Decrements the value of the horizontal axis channel by the channel step or page amount.
`incrementY(stepSize?: number): void`
Increments the value of the vertical axis channel by the channel step or page amount.
`decrementY(stepSize?: number): void`
Decrements the value of the vertical axis channel by the channel step or page amount.
`setDragging(value: boolean): void`
Sets whether the color area is being dragged.
`getDisplayColor(): Color`
Returns the color that should be displayed in the color area thumb instead of `value`.

AriaColorAreaOptions

Name	Type
`inputXRef`	`RefObject<HTMLInputElement \| null>`
A ref to the input that represents the x axis of the color area.
`inputYRef`	`RefObject<HTMLInputElement \| null>`
A ref to the input that represents the y axis of the color area.
`containerRef`	`RefObject<Element \| null>`
A ref to the color area containing element.
`xName`	`string`
The name of the x channel input element, used when submitting an HTML form. See MDN.
`yName`	`string`
The name of the y channel input element, used when submitting an HTML form. See MDN.
`colorSpace`	`ColorSpace`
The color space that the color area operates in. The `xChannel` and `yChannel` must be in this color space. If not provided, this defaults to the color space of the `color` or `defaultColor` value.
`xChannel`	`ColorChannel`
Color channel for the horizontal axis.
`yChannel`	`ColorChannel`
Color channel for the vertical axis.
`isDisabled`	`boolean`
Whether the ColorArea is disabled.

`value`	`T`
The current value (controlled).
`defaultValue`	`T`
The default value (uncontrolled).
`onChange`	`(value: Color) => void`
Handler that is called when the value changes, as the user drags.
`onChangeEnd`	`(value: Color) => void`
Handler that is called when the user stops dragging.

ColorAreaAria

Name	Type
`colorAreaProps`	`DOMAttributes`
Props for the color area container element.
`thumbProps`	`DOMAttributes`
Props for the thumb element.
`xInputProps`	`InputHTMLAttributes<HTMLInputElement>`
Props for the visually hidden horizontal range input element.
`yInputProps`	`InputHTMLAttributes<HTMLInputElement>`
Props for the visually hidden vertical range input element.