HelixOverviewComponentsMapsGraphIntroductionInstallationDeriving a themeSandboxTheme builderVisual testingCortexDocsEngramBuildingTraceBuildingRecallDeclaredServicesInsightsGet in touchSource on GitHub
Loading the reference
Color PickerView SourceEdit in SandboxView MarkdownCopy MarkdownOpen in ClaudeOpen in CursorA color picker made of a square and two ramps.StableSince 0.1.0FormsUsageimport'@fusion.dev/helix/color-picker'import'@fusion.dev/helix-headless/color-picker'Preview
API ReferenceRoothelix-color-pickerA color picker made of a square and two ramps.
PropTypeDescriptionalphabooleanDefaultfalseWhether the color carries an alpha channel.autocompletestringDefault"off"What the browser may autofill in the text field, as a platform token.badInputMessagestringDefault"Enter a color, like #ff0000, rgb(255 0 0) or hsl(0 100% 50%)."The message shown when the value is text that is not a color.blueLabelstringDefault"Blue"What the blue channel's field is called, in channel-fields.brightnessLabelstringDefault"Brightness"What the square's vertical ramp is called.channelFieldsbooleanDefaultfalseWhether the picker shows a number field for each channel of the color, as
React Aria's ColorField does with channel: red, green and blue for hex
and rgb, hue, saturation and lightness for hsl, hue, saturation and
brightness for hsb, lightness, chroma and hue for oklch, and the opacity
with alpha.chromaLabelstringDefault"Chroma"What the chroma channel's field is called, in channel-fields with
oklch.colorWordsPartial<ColorWords>Default{}The words a color's name is spoken in, as JSON keyed by their English,
such as {"red": "rot", "vibrant": "kräftiges"}.copiedLabelstringDefault"Copied"The text the sample shows for a moment after it copies the value.copyLabelstringDefault"Copy {value}"The name of the sample, which copies the value. {value} is replaced with
the color.defaultValuestringDefault""The value the control starts with. A form reset returns it to this value,
and to the value attribute where this one is not written, as a native
control resets to the value it declares.disabledbooleanDefaultfalseWhether the control is disabled and cannot be used.eyedropperLabelstringDefault"Sample a color from the screen"What the eyedropper is called.feedbackstringDefault""A message under the picker, such as what is wrong with the answer.format"hex"|"hsb"|"hsl"|"oklch"|"rgb"The syntax the value is written in: hex, rgb, hsl, oklch, or
hsb.formatLabelstringDefault"Syntax: {format}. Change it."What the syntax toggle is called, with {format} filled in.greenLabelstringDefault"Green"What the green channel's field is called, in channel-fields.hintstringDefault""Help under the picker, such as what the color is used for. The hint
slot takes richer content.hueLabelstringDefault"Hue"What the hue channel is called.invalidbooleanDefaultfalseWhether the answer fails validation, marked on the controls a reader
answers with and as :state(invalid).labelstringDefault""The name above the picker, such as "Brand color". The picker is then a
group with this name. The label slot takes richer content.lightnessLabelstringDefault"Lightness"What the lightness channel's field is called, in channel-fields with
hsl and oklch.namestringDefault""The name the control's value is submitted under.noEyedropperbooleanDefaultfalseHides the eyedropper. Without it, the eyedropper appears in browsers that
support one.noFormatbooleanDefaultfalseHides the syntax toggle, so the format cannot be changed.noValuebooleanDefaultfalseHides the text field that holds the value. Use it when the value is shown
elsewhere.opacityLabelstringDefault"Opacity"What the opacity channel is called, where alpha offers one.presetsLabelstringDefault"Presets"What the row of swatches is called.readOnlybooleanDefaultfalseMakes the color read-only. The value is still submitted with the form.redLabelstringDefault"Red"What the red channel's field is called, in channel-fields.requiredbooleanDefaultfalseRequires a color before the form can submit.saturationLabelstringDefault"Saturation"What the square's horizontal ramp is called.squareTextstringDefault"{first, select, brightness {{brightnessLabel} {brightness, number, percent}, {saturationLabel} {saturation, number, percent}, {name}} other {{saturationLabel} {saturation, number, percent}, {brightnessLabel} {brightness, number, percent}, {name}}}"What a screen reader hears for the square's place, the color's two
numbers and its name, on whichever of its two inputs it is on.
{first} is saturation or brightness, the input's own channel, which
is said first, so each order is its whole sentence. {saturation} and
{brightness} are shares from 0 to 1, written as percentages with
number, percent, {saturationLabel} and {brightnessLabel} the
channels' names, and {name} the color's, such as "vibrant red".swatchesstringDefault""Colors offered under the picker, as a comma-separated list.toolsLabelstringDefault"Color tools"What the group holding the eyedropper and the syntax toggle is called.valuestringThe control's current value, which its form submits.valueLabelstringDefault"Color"What the text field holding the value is called.valueMissingMessagestringDefault"Choose a color."The message shown when a color is required and none is chosen.wheelbooleanDefaultfalseDraws the hue as a wheel around the square, in place of the hue ramp, as
React Aria's ColorWheel sits round its ColorArea.
ReadTypeDescriptioncolorColorThe current color: the last one moved to, the value, or the start color.formHTMLFormElement|nullThe form the control belongs to, or null.labelsNodeListThe labels associated with the control.validationMessagestringThe message the browser would show for the control, or an empty string.validityValidityStateWhether the control meets its constraints, and why not.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.willValidatebooleanWhether the control is checked when its form is submitted.
SlotDescriptioneyedropper-iconThe icon on the eyedropper button, usually a dropper.hintHelp under the picker, for content richer than the hint text.labelThe name above the picker, for content richer than the label text.
EventTypeDescriptionchangeEventFired after the value changes.helix-before-changeHelixBeforeChangeEventFired before the color changes. Cancelable: call preventDefault() to keep the current color.helix-copyHelixCopyEventFired when the color is put on the clipboard.helix-sample-endHelixSampleEndEventFired when the eyedropper closes, whether or not a color was taken.helix-sample-startHelixSampleStartEventFired as the eyedropper opens. Hide anything that covers the page.inputEventFired after the value changes.
MethodTypeDescriptioncheckValidity() => booleanReturns whether the control is valid, and fires invalid on it when it is
not. The control shows no message for it: reportValidity() does that.focus(options: FocusOptions) => voidMoves focus to the control, as focusing a native control does.reportValidity() => booleanReturns whether the control is valid, and when it is not, fires invalid
and shows the browser's message at the control.requestValue(next: string) => booleanRequests a new value, and returns whether the change was applied.setCustomValidity(message: string) => voidMarks the control invalid with message, or clears that with an empty
string, as on a native control. The form does not submit while it is set.
PartDescriptionactionsThe group holding the eyedropper and the syntax toggle.channelOne ramp.channel-controlThe range input.channel-feedbackThe error message for a ramp.channel-fieldThe row that holds a ramp's control and its readout.channel-hintThe help text under the track, shown while there is no error.channel-labelThe label above the track.channel-markerOne mark on the track.channel-marker-labelThe value a mark stands at, when marker-labels is set.channel-markersThe row of marks along the track.channel-outputThe current value, shown beside the track.channel-thumbA ramp's thumb box, which holds no content in a picker.channel-thumbsThe layer over a ramp's track that holds its thumb box.channel-tooltipA ramp's value in a bubble, where a ramp shows one.channel-tooltipsThe layer over a ramp's track that holds its bubble.channelsThe ramps beside the sample.controlsThe row under the square.eyedropperThe control that samples a color from the screen.eyedropper-buttonThe button inside eyedropper.eyedropper-liveThe live region of the button inside eyedropper, which says its pending label.eyedropper-spinnerThe ring the eyedropper button turns while it is pending.eyedropper-textThe words on the button inside eyedropper, trimmed to their capitals and baseline.feedbackThe message under the picker: feedback, or what is wrong with the answer once the picker is marked invalid.fieldOne channel's number field with its label, in channel-fields.field-inputThe number input in a channel's field.field-labelThe name above a channel's number input.fieldsThe row of channel number fields, in channel-fields.footerThe row holding the value and the tools.formatThe control that changes the syntax the value is written in.format-buttonThe button inside format.format-liveThe live region of the button inside format, which says its pending label.format-spinnerThe ring the syntax button turns while it is pending.format-textThe words on the button inside format, trimmed to their capitals and baseline.gridThe saturation and brightness square. Draw the mark that shows where the color sits with ::part(grid)::after in your stylesheet. The square carries the two channels as --color-picker-saturation and --color-picker-brightness, and this tier ships no CSS.grid-brightnessThe range input for the square's vertical axis.grid-saturationThe range input for the square's horizontal axis.hintThe help under the picker, while hint is set or the hint slot has content.labelThe name above the picker, while label is set or the label slot has content.sampleA chip of the current color. Pressing it copies the value.swatchOne preset, an option in the swatches listbox.swatchesThe row of presets, a listbox.valueThe text field that holds the color. It accepts a typed or pasted color.wheelThe hue ring round the square, with wheel. Draw the ring and its mark from --color-picker-hue.wheel-hueThe range input behind the ring, which a reader turns with the keys.
CSS PropertyDescription--color-picker-brightnessThe chosen brightness, 0 to 100, as a percentage.--color-picker-feedback-colorThe color of the message under the picker, while feedback is set.--color-picker-field-label-colorThe color of the names above the channel number fields, in channel-fields.--color-picker-fields-gapThe space between the channel number fields, in channel-fields.--color-picker-grid-radiusThe corner radius of the square.--color-picker-grid-ratioThe aspect ratio of the square.--color-picker-hueThe chosen hue, 0 to 360, unitless.--color-picker-paddingThe inset of the rows under the square and of the picker's bottom edge.--color-picker-sample-sizeThe width and height of the chip that copies the value.--color-picker-saturationThe chosen saturation, 0 to 100, as a percentage.--color-picker-swatchThe color a chip shows: the current color on the sample, and the preset's color on each preset.--color-picker-swatch-sizeThe width and height of one preset.--color-picker-wheel-sizeThe widest the hue ring draws, with wheel. The picker's width by default.--color-picker-wheel-thicknessThe width of the hue ring's band, with wheel.
Custom stateDescriptioncopiedThe moment after the sample copies the value, while it says copied-label.draggingWhile a pointer drags the square's handle.invalidWhile invalid is set or feedback says what is wrong.samplingWhile the eyedropper is open over the screen.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Roothelix-headless-color-pickerA color picker made of a square and two ramps.
PropTypeDescriptionalphabooleanDefaultfalseWhether the color carries an alpha channel.autocompletestringDefault"off"What the browser may autofill in the text field, as a platform token.badInputMessagestringDefault"Enter a color, like #ff0000, rgb(255 0 0) or hsl(0 100% 50%)."The message shown when the value is text that is not a color.blueLabelstringDefault"Blue"What the blue channel's field is called, in channel-fields.brightnessLabelstringDefault"Brightness"What the square's vertical ramp is called.channelFieldsbooleanDefaultfalseWhether the picker shows a number field for each channel of the color, as
React Aria's ColorField does with channel: red, green and blue for hex
and rgb, hue, saturation and lightness for hsl, hue, saturation and
brightness for hsb, lightness, chroma and hue for oklch, and the opacity
with alpha.chromaLabelstringDefault"Chroma"What the chroma channel's field is called, in channel-fields with
oklch.colorWordsPartial<ColorWords>Default{}The words a color's name is spoken in, as JSON keyed by their English,
such as {"red": "rot", "vibrant": "kräftiges"}.copiedLabelstringDefault"Copied"The text the sample shows for a moment after it copies the value.copyLabelstringDefault"Copy {value}"The name of the sample, which copies the value. {value} is replaced with
the color.defaultValuestringDefault""The value the control starts with. A form reset returns it to this value,
and to the value attribute where this one is not written, as a native
control resets to the value it declares.disabledbooleanDefaultfalseWhether the control is disabled and cannot be used.eyedropperLabelstringDefault"Sample a color from the screen"What the eyedropper is called.feedbackstringDefault""A message under the picker, such as what is wrong with the answer.format"hex"|"hsb"|"hsl"|"oklch"|"rgb"The syntax the value is written in: hex, rgb, hsl, oklch, or
hsb.formatLabelstringDefault"Syntax: {format}. Change it."What the syntax toggle is called, with {format} filled in.greenLabelstringDefault"Green"What the green channel's field is called, in channel-fields.hintstringDefault""Help under the picker, such as what the color is used for. The hint
slot takes richer content.hueLabelstringDefault"Hue"What the hue channel is called.invalidbooleanDefaultfalseWhether the answer fails validation, marked on the controls a reader
answers with and as :state(invalid).labelstringDefault""The name above the picker, such as "Brand color". The picker is then a
group with this name. The label slot takes richer content.lightnessLabelstringDefault"Lightness"What the lightness channel's field is called, in channel-fields with
hsl and oklch.namestringDefault""The name the control's value is submitted under.noEyedropperbooleanDefaultfalseHides the eyedropper. Without it, the eyedropper appears in browsers that
support one.noFormatbooleanDefaultfalseHides the syntax toggle, so the format cannot be changed.noValuebooleanDefaultfalseHides the text field that holds the value. Use it when the value is shown
elsewhere.opacityLabelstringDefault"Opacity"What the opacity channel is called, where alpha offers one.presetsLabelstringDefault"Presets"What the row of swatches is called.readOnlybooleanDefaultfalseMakes the color read-only. The value is still submitted with the form.redLabelstringDefault"Red"What the red channel's field is called, in channel-fields.requiredbooleanDefaultfalseRequires a color before the form can submit.saturationLabelstringDefault"Saturation"What the square's horizontal ramp is called.squareTextstringDefault"{first, select, brightness {{brightnessLabel} {brightness, number, percent}, {saturationLabel} {saturation, number, percent}, {name}} other {{saturationLabel} {saturation, number, percent}, {brightnessLabel} {brightness, number, percent}, {name}}}"What a screen reader hears for the square's place, the color's two
numbers and its name, on whichever of its two inputs it is on.
{first} is saturation or brightness, the input's own channel, which
is said first, so each order is its whole sentence. {saturation} and
{brightness} are shares from 0 to 1, written as percentages with
number, percent, {saturationLabel} and {brightnessLabel} the
channels' names, and {name} the color's, such as "vibrant red".swatchesstringDefault""Colors offered under the picker, as a comma-separated list.toolsLabelstringDefault"Color tools"What the group holding the eyedropper and the syntax toggle is called.valuestringThe control's current value, which its form submits.valueLabelstringDefault"Color"What the text field holding the value is called.valueMissingMessagestringDefault"Choose a color."The message shown when a color is required and none is chosen.wheelbooleanDefaultfalseDraws the hue as a wheel around the square, in place of the hue ramp, as
React Aria's ColorWheel sits round its ColorArea.
ReadTypeDescriptioncolorColorThe current color: the last one moved to, the value, or the start color.formHTMLFormElement|nullThe form the control belongs to, or null.labelsNodeListThe labels associated with the control.validationMessagestringThe message the browser would show for the control, or an empty string.validityValidityStateWhether the control meets its constraints, and why not.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.willValidatebooleanWhether the control is checked when its form is submitted.
SlotDescriptioneyedropper-iconThe icon on the eyedropper button, usually a dropper.hintHelp under the picker, for content richer than the hint text.labelThe name above the picker, for content richer than the label text.
EventTypeDescriptionchangeEventFired after the value changes.helix-before-changeHelixBeforeChangeEventFired before the color changes. Cancelable: call preventDefault() to keep the current color.helix-copyHelixCopyEventFired when the color is put on the clipboard.helix-sample-endHelixSampleEndEventFired when the eyedropper closes, whether or not a color was taken.helix-sample-startHelixSampleStartEventFired as the eyedropper opens. Hide anything that covers the page.inputEventFired after the value changes.
MethodTypeDescriptioncheckValidity() => booleanReturns whether the control is valid, and fires invalid on it when it is
not. The control shows no message for it: reportValidity() does that.focus(options: FocusOptions) => voidMoves focus to the square.reportValidity() => booleanReturns whether the control is valid, and when it is not, fires invalid
and shows the browser's message at the control.requestValue(next: string) => booleanBlocks every change while readOnly is set.setCustomValidity(message: string) => voidMarks the control invalid with message, or clears that with an empty
string, as on a native control. The form does not submit while it is set.
PartDescriptionactionsThe group holding the eyedropper and the syntax toggle.channelOne ramp.channel-controlThe range input.channel-feedbackThe error message for a ramp.channel-fieldThe row that holds a ramp's control and its readout.channel-hintThe help text under the track, shown while there is no error.channel-labelThe label above the track.channel-markerOne mark on the track.channel-marker-labelThe value a mark stands at, when marker-labels is set.channel-markersThe row of marks along the track.channel-outputThe current value, shown beside the track.channel-thumbA ramp's thumb box, which holds no content in a picker.channel-thumbsThe layer over a ramp's track that holds its thumb box.channel-tooltipA ramp's value in a bubble, where a ramp shows one.channel-tooltipsThe layer over a ramp's track that holds its bubble.channelsThe ramps beside the sample.controlsThe row under the square.eyedropperThe control that samples a color from the screen.eyedropper-buttonThe button inside eyedropper.eyedropper-liveThe live region of the button inside eyedropper, which says its pending label.eyedropper-spinnerThe ring the eyedropper button turns while it is pending.eyedropper-textThe words on the button inside eyedropper, trimmed to their capitals and baseline.feedbackThe message under the picker: feedback, or what is wrong with the answer once the picker is marked invalid.fieldOne channel's number field with its label, in channel-fields.field-inputThe number input in a channel's field.field-labelThe name above a channel's number input.fieldsThe row of channel number fields, in channel-fields.footerThe row holding the value and the tools.formatThe control that changes the syntax the value is written in.format-buttonThe button inside format.format-liveThe live region of the button inside format, which says its pending label.format-spinnerThe ring the syntax button turns while it is pending.format-textThe words on the button inside format, trimmed to their capitals and baseline.gridThe saturation and brightness square. Draw the mark that shows where the color sits with ::part(grid)::after in your stylesheet. The square carries the two channels as --color-picker-saturation and --color-picker-brightness, and this tier ships no CSS.grid-brightnessThe range input for the square's vertical axis.grid-saturationThe range input for the square's horizontal axis.hintThe help under the picker, while hint is set or the hint slot has content.labelThe name above the picker, while label is set or the label slot has content.sampleA chip of the current color. Pressing it copies the value.swatchOne preset, an option in the swatches listbox.swatchesThe row of presets, a listbox.valueThe text field that holds the color. It accepts a typed or pasted color.wheelThe hue ring round the square, with wheel. Draw the ring and its mark from --color-picker-hue.wheel-hueThe range input behind the ring, which a reader turns with the keys.
CSS PropertyDescription--color-picker-brightnessThe chosen brightness, 0 to 100, as a percentage.--color-picker-hueThe chosen hue, 0 to 360, unitless.--color-picker-saturationThe chosen saturation, 0 to 100, as a percentage.--color-picker-swatchThe color a chip shows: the current color on the sample, and the preset's color on each preset.
Custom stateDescriptioncopiedThe moment after the sample copies the value, while it says copied-label.draggingWhile a pointer drags the square's handle.invalidWhile invalid is set or feedback says what is wrong.samplingWhile the eyedropper is open over the screen.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Examples
NameDescriptionChannel FieldsA number field for each channel, for a color copied from a brand guide.DisabledA disabled picker, which shows a color that cannot be changed.EventsThe events for a value change, a color sampled from the screen, and a color copied to the clipboard.InvalidThe picker marked invalid.LabelA picker named by its label, with help under it from hint.No FormatThe picker with no syntax toggle, for when the format is already set.No Value Or EyedropperThe picker with no readout and no eyedropper, for a picker placed beside its own preview.OklchA picker that writes its value as oklch(), with a field for its lightness, chroma, and hue.PreviewThe area, the hue rail, and the value in a field.PreviewThe area, the hue rail, and the value in a field.SwatchesPrepared colors under the picker, with opacity on.SyntaxesSwatches written in hex, rgb(), and hsl(), in a picker that writes its value as hsl.WheelThe hue as a ring round the square, for a picker where hue is the first choice.