beta
ColorWheel
ColorWheels allow users to adjust the hue of an HSL or HSB color value on a circular track.
< ColorWheel defaultValue = "hsl(30, 100%, 50%)" / > < ColorWheel defaultValue = "hsl(30, 100%, 50%)" / > < ColorWheel defaultValue = "hsl(30, 100%, 50%)" / > A ColorWheel's value specifies the position of the ColorWheel's thumb on the track, and accepts a string or hsl(0, 100%, 50%) by default, but an alternative initial uncontrolled value can be provided using the defaultValue prop.
Alternatively, a controlled value can be provided using the value prop. Note that only HSB(A) values are supported as valid values.
In the example below, the value's type remains consistent.
import { parseColor } from '@react-stately/color' ;
function Example ( ) {
let [ value , setValue ] = React . useState ( parseColor ( 'hsl(30, 100%, 50%)' ) ) ;
return (
< Flex gap = "size-300" wrap >
< Flex direction = "column" alignItems = "center" >
< label id = "label-1" > Hue (uncontrolled)< / label >
< ColorWheel
defaultValue = "hsl(30, 100%, 50%)"
aria-labelledby = "label-1" / >
< / Flex >
< Flex direction = "column" alignItems = "center" >
< label id = "label-2" > Hue (controlled)< / label >
< ColorWheel
value = { value }
onChange = { setValue }
aria-labelledby = "label-1" / >
< / Flex >
< / Flex >
) ;
} import { parseColor } from '@react-stately/color' ;
function Example ( ) {
let [ value , setValue ] = React . useState (
parseColor ( 'hsl(30, 100%, 50%)' )
) ;
return (
< Flex gap = "size-300" wrap >
< Flex direction = "column" alignItems = "center" >
< label id = "label-1" > Hue (uncontrolled)< / label >
< ColorWheel
defaultValue = "hsl(30, 100%, 50%)"
aria-labelledby = "label-1"
/ >
< / Flex >
< Flex direction = "column" alignItems = "center" >
< label id = "label-2" > Hue (controlled)< / label >
< ColorWheel
value = { value }
onChange = { setValue }
aria-labelledby = "label-1"
/ >
< / Flex >
< / Flex >
) ;
}
import { parseColor } from '@react-stately/color' ;
function Example ( ) {
let [ value , setValue ] =
React . useState (
parseColor (
'hsl(30, 100%, 50%)'
)
) ;
return (
< Flex
gap = "size-300"
wrap
>
< Flex
direction = "column"
alignItems = "center"
>
< label id = "label-1" >
Hue
(uncontrolled)
< / label >
< ColorWheel
defaultValue = "hsl(30, 100%, 50%)"
aria-labelledby = "label-1"
/ >
< / Flex >
< Flex
direction = "column"
alignItems = "center"
>
< label id = "label-2" >
Hue
(controlled)
< / label >
< ColorWheel
value = { value }
onChange = { setValue }
aria-labelledby = "label-1"
/ >
< / Flex >
< / Flex >
) ;
}
By default, a localized string for the "hue" channel name is used as the aria-label for the ColorWheel. When a custom aria-label or aria-labelledby
is provided, it should be localized accordingly.
ColorWheel supports two events: onChange and onChangeEnd. onChange is triggered whenever the ColorWheel's handle is dragged, and onChangeEnd
is triggered when the user stops dragging the handle. Both events receive a
The example below uses onChange and onChangeEnd to update two separate elements with the ColorWheel's value.
function Example ( ) {
let [ currentValue , setCurrentValue ] = React . useState (
parseColor ( 'hsl(50, 100%, 50%)' )
) ;
let [ finalValue , setFinalValue ] = React . useState (
parseColor ( 'hsl(50, 100%, 50%)' )
) ;
return (
< div >
< ColorWheel
value = { currentValue }
onChange = { setCurrentValue }
onChangeEnd = { setFinalValue }
/ >
< pre > Current value: { currentValue . toString ( 'hsl' ) } < / pre >
< pre > Final value: { finalValue . toString ( 'hsl' ) } < / pre >
< / div >
) ;
}
function Example ( ) {
let [ currentValue , setCurrentValue ] = React . useState (
parseColor ( 'hsl(50, 100%, 50%)' )
) ;
let [ finalValue , setFinalValue ] = React . useState (
parseColor ( 'hsl(50, 100%, 50%)' )
) ;
return (
< div >
< ColorWheel
value = { currentValue }
onChange = { setCurrentValue }
onChangeEnd = { setFinalValue }
/ >
< pre > Current value: { currentValue . toString ( 'hsl' ) }
< / pre >
< pre > Final value: { finalValue . toString ( 'hsl' ) } < / pre >
< / div >
) ;
}
function Example ( ) {
let [
currentValue ,
setCurrentValue
] = React . useState (
parseColor (
'hsl(50, 100%, 50%)'
)
) ;
let [
finalValue ,
setFinalValue
] = React . useState (
parseColor (
'hsl(50, 100%, 50%)'
)
) ;
return (
< div >
< ColorWheel
value = { currentValue }
onChange = { setCurrentValue }
onChangeEnd = { setFinalValue }
/ >
< pre >
Current value:
{ ' ' }
{ currentValue
. toString (
'hsl'
) }
< / pre >
< pre > Final value:
{ ' ' }
{ finalValue
. toString ( 'hsl' ) }
< / pre >
< / div >
) ;
}
Current value: hsl(50, 100%, 50%) Final value: hsl(50, 100%, 50%) Name Type Default Description size — The outer diameter of the ColorWheel. isDisabled boolean — Whether the ColorWheel is disabled. defaultValue string | 'hsl(0, 100%, 50%)'The default value (uncontrolled). value T — The current value (controlled).
Name Type Default Description onChange (
( value :
) ) => void — Handler that is called when the value changes, as the user drags. onChangeEnd (
( value :
) ) => void — Handler that is called when the user stops dragging.
Name Type Default Description flex < string
| number
| boolean > — When used in a flex layout, specifies how the element will grow or shrink to fit the space available. See MDN . flexGrow < number > — When used in a flex layout, specifies how the element will grow to fit the space available. See MDN . flexShrink < number > — When used in a flex layout, specifies how the element will shrink to fit the space available. See MDN . flexBasis < number | string > — When used in a flex layout, specifies the initial main size of the element. See MDN . alignSelf < 'auto'
| 'normal'
| 'start'
| 'end'
| 'center'
| 'flex-start'
| 'flex-end'
| 'self-start'
| 'self-end'
| 'stretch' > — Overrides the alignItems property of a flex or grid container. See MDN . justifySelf < 'auto'
| 'normal'
| 'start'
| 'end'
| 'flex-start'
| 'flex-end'
| 'self-start'
| 'self-end'
| 'center'
| 'left'
| 'right'
| 'stretch' > — Specifies how the element is justified inside a flex or grid container. See MDN . order < number > — The layout order for the element within a flex or grid container. See MDN . gridArea < string > — When used in a grid layout, specifies the named grid area that the element should be placed in within the grid. See MDN . gridColumn < string > — When used in a grid layout, specifies the column the element should be placed in within the grid. See MDN . gridRow < string > — When used in a grid layout, specifies the row the element should be placed in within the grid. See MDN . gridColumnStart < string > — When used in a grid layout, specifies the starting column to span within the grid. See MDN . gridColumnEnd < string > — When used in a grid layout, specifies the ending column to span within the grid. See MDN . gridRowStart < string > — When used in a grid layout, specifies the starting row to span within the grid. See MDN . gridRowEnd < string > — When used in a grid layout, specifies the ending row to span within the grid. See MDN .
Name Type Default Description margin < > — The margin for all four sides of the element. See MDN . marginTop < > — The margin for the top side of the element. See MDN . marginBottom < > — The margin for the bottom side of the element. See MDN . marginStart < > — The margin for the logical start side of the element, depending on layout direction. See MDN . marginEnd < > — The margin for the logical end side of an element, depending on layout direction. See MDN . marginX < > — The margin for both the left and right sides of the element. See MDN . marginY < > — The margin for both the top and bottom sides of the element. See MDN .
Name Type Default Description minWidth < > — The minimum width of the element. See MDN . maxWidth < > — The maximum width of the element. See MDN . minHeight < > — The minimum height of the element. See MDN . maxHeight < > — The maximum height of the element. See MDN .
Name Type Default Description position < 'static'
| 'relative'
| 'absolute'
| 'fixed'
| 'sticky' > — Specifies how the element is positioned. See MDN . top < > — The top position for the element. See MDN . bottom < > — The bottom position for the element. See MDN . left < > — The left position for the element. See MDN . Consider using start instead for RTL support. right < > — The right position for the element. See MDN . Consider using start instead for RTL support. start < > — The logical start position for the element, depending on layout direction. See MDN . end < > — The logical end position for the element, depending on layout direction. See MDN . zIndex < number > — The stacking order for the element. See MDN . isHidden < boolean > — Hides the element.
Name Type Default Description id string — The element's unique identifier. See MDN . aria-label string — Defines a string value that labels the current element. aria-labelledby string — Identifies the element (or elements) that labels the current element. aria-describedby string — Identifies the element (or elements) that describes the object. aria-details string — Identifies the element (or elements) that provide a detailed, extended description for the object.
Name Type Default Description UNSAFE_className string — Sets the CSS className for the element. Only use as a last resort . Use style props instead. UNSAFE_style CSSProperties — Sets inline style for the element. Only use as a last resort . Use style props instead.
View guidelines
< ColorWheel isDisabled / > < ColorWheel isDisabled / > < ColorWheel isDisabled / > View guidelines
< ColorWheel size = "size-1600" / > < ColorWheel size = "size-1600" / > < ColorWheel size = "size-1600" / >