Spectrum 2 is now available! Check out the migration docs.

useColorAreaState

Provides state management for a color area component. Color area allows users to adjust two channels of an HSL, HSB or RGB color value against a two-dimensional gradient background.

install	`yarn add react-stately`
version	3.47.0
usage	`import {useColorAreaState} from 'react-stately'`

View repository

GitHub

View package

NPM

API#

useColorAreaState(
  (props: ColorAreaProps
)): ColorAreaState

Interface#

Properties

Name	Type	Description
`value`	`Color`	The current color value displayed by the color area.
`defaultValue`	`Color`	The default value of the color area.
`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.

Methods

Method	Description
`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`.

Example#

See the docs for useColorArea in react-aria for an example of useColorAreaState.

Name	Type	Description
`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.
`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.
`value`	`T`	The current value (controlled).
`defaultValue`	`T`	The default value (uncontrolled).

'rgb'
  | 'hsl'
  | 'hsb'

A list of color channels.

'hue'
  | 'saturation'
  | 'brightness'
  | 'lightness'
  | 'red'
  | 'green'
  | 'blue'
  | 'alpha'

Represents a color value.

Method	Description
`toFormat( (format: ColorFormat )): Color`	Converts the color to the given color format, and returns a new Color object.
`toString( (format?: ColorFormat \| \| 'css' )): string`	Converts the color to a string in the given format.
`clone(): Color`	Returns a duplicate of the color value.
`toHexInt(): number`	Converts the color to hex, and returns an integer representation.
`getChannelValue( (channel: ColorChannel )): number`	Returns the numeric value for a given channel. Throws an error if the channel is unsupported in the current color format.
`withChannelValue( (channel: ColorChannel, , value: number )): Color`	Sets the numeric value for a given channel, and returns a new Color object. Throws an error if the channel is unsupported in the current color format.
`getChannelRange( (channel: ColorChannel )): ColorChannelRange`	Returns the minimum, maximum, and step values for a given channel.
`getChannelName( (channel: ColorChannel, , locale: string )): string`	Returns a localized color channel name for a given channel and locale, for use in visual or accessibility labels.
`getChannelFormatOptions( (channel: ColorChannel )): Intl.NumberFormatOptions`	Returns the number formatting options for the given channel.
`formatChannelValue( (channel: ColorChannel, , locale: string )): string`	Formats the numeric value for a given channel for display according to the provided locale.
`getColorSpace(): ColorSpace`	Returns the color space, 'rgb', 'hsb' or 'hsl', for the current color.
`getColorSpaceAxes( (xyChannels: {xChannel?: ColorChannel, yChannel?: ColorChannel } )): ColorAxes`	Returns the color space axes, xChannel, yChannel, zChannel.
`getColorChannels(): [ ColorChannel, ColorChannel, ColorChannel ]`	Returns an array of the color channels within the current color space space.
`getColorName( (locale: string )): string`	Returns a localized name for the color, for use in visual or accessibility labels.
`getHueName( (locale: string )): string`	Returns a localized name for the hue, for use in visual or accessibility labels.

A list of supported color formats.

'hex'
  | 'hexa'
  | 'rgb'
  | 'rgba'
  | 'hsl'
  | 'hsla'
  | 'hsb'
  | 'hsba'

Name	Type	Description
`minValue`	`number`	The minimum value of the color channel.
`maxValue`	`number`	The maximum value of the color channel.
`step`	`number`	The step value of the color channel, used when incrementing and decrementing.
`pageSize`	`number`	The page step value of the color channel, used when incrementing and decrementing.

{xChannel: ColorChannel,
yChannel: ColorChannel,
zChannel: ColorChannel
}

Properties

Name	Type	Description
`value`	`Color`	The current color value displayed by the color area.
`defaultValue`	`Color`	The default value of the color area.
`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.

Methods

Method	Description
`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`.