useColorWheelState

Provides state management for a color wheel component. Color wheels allow users to adjust the hue of an HSL or HSB color value on a circular track.

install	`yarn add react-stately`
version	3.34.0
usage	`import {useColorSliderState} from 'react-stately'`

View repository

GitHub

View package

NPM

API#

useColorWheelState(
  (props: ColorWheelProps
)): ColorWheelState

Interface#

Properties

Name	Type	Description
`value`	`Color`	The current color value represented by the color wheel.
`hue`	`number`	The current value of the hue channel displayed by the color wheel.
`isDragging`	`boolean`	Whether the color wheel is currently being dragged.
`step`	`number`	The step value of the hue channel, used when incrementing and decrementing.
`pageStep`	`number`	The page step value of the hue channel, used when incrementing and decrementing.
`isDisabled`	`boolean`	Whether the color wheel is disabled.

Methods

Method	Description
`setValue( (value: string \| \| Color )): void`	Sets the color value represented by the color wheel, and triggers `onChange`.
`setHue( (value: number )): void`	Sets the hue channel of the current color value and triggers `onChange`.
`setHueFromPoint( x: number, y: number, radius: number ): void`	Sets the hue channel of the current color value based on the given coordinates and radius of the color wheel, and triggers `onChange`.
`getThumbPosition( (radius: number )): {x: number, y: number }`	Returns the coordinates of the thumb relative to the center point of the color wheel.
`increment( (stepSize?: number )): void`	Increments the hue by the given amount (defaults to 1).
`decrement( (stepSize?: number )): void`	Decrements the hue by the given amount (defaults to 1).
`setDragging( (value: boolean )): void`	Sets whether the color wheel is being dragged.
`getDisplayColor(): Color`	Returns the color that should be displayed in the color wheel instead of `value`.

Example#

See the docs for useColorWheel in react-aria for an example of useColorWheelState.

Name	Type	Default	Description
`isDisabled`	`boolean`	—	Whether the ColorWheel 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.
`defaultValue`	`string \| Color`	`'hsl(0, 100%, 50%)'`	The default value (uncontrolled).
`value`	`T`	—	The current value (controlled).

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'

A list of color channels.

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

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.

'rgb'
  | 'hsl'
  | 'hsb'

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

Properties

Name	Type	Description
`value`	`Color`	The current color value represented by the color wheel.
`hue`	`number`	The current value of the hue channel displayed by the color wheel.
`isDragging`	`boolean`	Whether the color wheel is currently being dragged.
`step`	`number`	The step value of the hue channel, used when incrementing and decrementing.
`pageStep`	`number`	The page step value of the hue channel, used when incrementing and decrementing.
`isDisabled`	`boolean`	Whether the color wheel is disabled.

Methods

Method	Description
`setValue( (value: string \| \| Color )): void`	Sets the color value represented by the color wheel, and triggers `onChange`.
`setHue( (value: number )): void`	Sets the hue channel of the current color value and triggers `onChange`.
`setHueFromPoint( x: number, y: number, radius: number ): void`	Sets the hue channel of the current color value based on the given coordinates and radius of the color wheel, and triggers `onChange`.
`getThumbPosition( (radius: number )): {x: number, y: number }`	Returns the coordinates of the thumb relative to the center point of the color wheel.
`increment( (stepSize?: number )): void`	Increments the hue by the given amount (defaults to 1).
`decrement( (stepSize?: number )): void`	Decrements the hue by the given amount (defaults to 1).
`setDragging( (value: boolean )): void`	Sets whether the color wheel is being dragged.
`getDisplayColor(): Color`	Returns the color that should be displayed in the color wheel instead of `value`.