useColorFieldState

Provides state management for a color field component. Color fields allow users to enter and adjust a hex color value.

install	`yarn add react-stately`
version	3.21.0
usage	`import {useColorFieldState} from 'react-stately'`

View repository

GitHub

View package

NPM

API#

useColorFieldState(
  (props: ColorFieldProps
)): ColorFieldState

Interface#

Properties

Name	Type	Description
`inputValue`	`string`	The current text value of the input. Updated as the user types, and formatted according to `formatOptions` on blur.
`colorValue`	`Color`	The currently parsed color value, or null if the field is empty. Updated based on the `inputValue` as the user types.

Methods

Method	Description
`setInputValue( (value: string )): void`	Sets the current text value of the input.
`commit(): void`	Updates the input value based on the currently parsed color value. Typically this is called when the field is blurred.
`increment(): void`	Increments the current input value to the next step boundary, and fires `onChange`.
`decrement(): void`	Decrements the current input value to the next step boundary, and fires `onChange`.
`incrementToMax(): void`	Sets the current value to the maximum color value, and fires `onChange`.
`decrementToMin(): void`	Sets the current value to the minimum color value, and fires `onChange`.
`validate( (value: string )): boolean`	Validates a user input string. Values can be partially entered, and may be valid even if they cannot currently be parsed to a color. Can be used to implement validation as a user types.

Example#

See the docs for useColorField in react-aria for an example of useColorFieldState.

Name	Type	Description
`onChange`	`( (color: Color \| \| null )) => void`	Handler that is called when the value changes.
`value`	`T`	The current value (controlled).
`defaultValue`	`T`	The default value (uncontrolled).
`isDisabled`	`boolean`	Whether the input is disabled.
`isReadOnly`	`boolean`	Whether the input can be selected but not changed by the user.
`validationState`	`ValidationState`	Whether the input should display its "valid" or "invalid" visual styling.
`isRequired`	`boolean`	Whether user input is required on the input before form submission. Often paired with the `necessityIndicator` prop to add a visual indicator to the input.
`autoFocus`	`boolean`	Whether the element should receive focus on render.
`onFocus`	`( (e: FocusEvent<Target> )) => void`	Handler that is called when the element receives focus.
`onBlur`	`( (e: FocusEvent<Target> )) => void`	Handler that is called when the element loses focus.
`onFocusChange`	`( (isFocused: boolean )) => void`	Handler that is called when the element's focus status changes.
`onKeyDown`	`( (e: KeyboardEvent )) => void`	Handler that is called when a key is pressed.
`onKeyUp`	`( (e: KeyboardEvent )) => void`	Handler that is called when a key is released.
`placeholder`	`string`	Temporary text that occupies the text input when it is empty.
`label`	`ReactNode`	The content to display as the label.
`description`	`ReactNode`	A description for the field. Provides a hint such as specific requirements for what to choose.
`errorMessage`	`ReactNode`	An error message for the field.

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.
`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.
`formatChannelValue( (channel: ColorChannel, , locale: string )): string`	Formats the numeric value for a given channel for display according to the provided locale.
`getColorSpace(): ColorFormat`	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.

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.

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

'valid' | 'invalid'

BaseEvent<ReactKeyboardEvent<any>>

SyntheticEvent & {stopPropagation: () => void,
continuePropagation: () => void
}

Properties

Name	Type	Description
`inputValue`	`string`	The current text value of the input. Updated as the user types, and formatted according to `formatOptions` on blur.
`colorValue`	`Color`	The currently parsed color value, or null if the field is empty. Updated based on the `inputValue` as the user types.

Methods

Method	Description
`setInputValue( (value: string )): void`	Sets the current text value of the input.
`commit(): void`	Updates the input value based on the currently parsed color value. Typically this is called when the field is blurred.
`increment(): void`	Increments the current input value to the next step boundary, and fires `onChange`.
`decrement(): void`	Decrements the current input value to the next step boundary, and fires `onChange`.
`incrementToMax(): void`	Sets the current value to the maximum color value, and fires `onChange`.
`decrementToMin(): void`	Sets the current value to the minimum color value, and fires `onChange`.
`validate( (value: string )): boolean`	Validates a user input string. Values can be partially entered, and may be valid even if they cannot currently be parsed to a color. Can be used to implement validation as a user types.