HelixOverviewComponentsMapsGraphIntroductionInstallationDeriving a themeSandboxTheme builderVisual testingCortexDocsEngramBuildingTraceBuildingRecallDeclaredServicesInsightsGet in touchSource on GitHub
Loading the reference
Color InputView SourceEdit in SandboxView MarkdownCopy MarkdownOpen in ClaudeOpen in CursorA field for a color, typed in any syntax or picked from a panel.StableSince 0.1.0FormsUsageimport'@fusion.dev/helix/color-input'import'@fusion.dev/helix-headless/color-input'Preview
API ReferenceRoothelix-color-inputA field for a color, typed in any syntax or picked from a panel.
PropTypeDescriptionalphabooleanDefaultfalseWhether the color carries an alpha channel.autocompletestringDefault"off"What the browser may autofill in the text field, as a platform token.badInputMessagestringThe message shown when the field holds text the picker cannot read as a
date, a time, or a color.channelFieldsbooleanDefaultfalseWhether the panel shows a number field for each channel of the color.
Passed to the panel; see Color Picker's channel-fields.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"}.defaultOpenbooleanDefaultfalseWhether the element starts open. Ignored once open is written.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.feedbackstringDefault""The validation message shown under the control. It replaces the
browser's message.format"hex"|"hsb"|"hsl"|"oklch"|"rgb"The syntax the value is written in: hex, rgb, hsl, oklch, or
hsb, as Color Picker's format.hintstringDefault""Help text shown under the control. A validation message replaces it.labelstringDefault""The field's label, which is also its accessible name. Content in the
label slot replaces it.namestringDefault""The name the control's value is submitted under.noFormatbooleanDefaultfalseHides the button in the panel that changes the format.openbooleanWhether the element is open.placeholderstringDefault"#000000"The text the field shows before a color is entered.readOnlybooleanDefaultfalseWhether the color is locked. A read-only field still submits its value.requiredbooleanDefaultfalseWhether the field needs a value before the form can submit.swatchesstringDefault""Colors offered under the picker, as a comma-separated list.swatchLabelstringDefault"{name} {value}"What the swatch says in variant="swatch", after the field's label, once
there is a color. {name} is the color's name, such as "vibrant red", and
{value} the value as written.triggerLabelstringDefault"Choose a color"Accessible name for the control that opens the panel.valuestringThe control's current value, which its form submits.valueMissingMessagestringThe message shown when the field is required and empty.variant"swatch"Whether the field is a text box with a swatch on it, or only the swatch.wheelbooleanDefaultfalseDraws the panel's hue as a wheel around the square, in place of the hue
ramp. See Color Picker's wheel.
ReadTypeDescriptionformHTMLFormElement|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.
SlotDescriptionendContent at the trailing end, before the trigger.feedbackThe message that says what is wrong with the value.hintHelp text under the field.labelThe label, for content richer than the label text.panel-footerContent in the panel under the picker, such as a note or an action.panel-headerContent in the panel above the picker, such as a heading or a shortcut.startContent at the leading end of the field, inside its border.triggerThe icon on the trigger, which shows that the field opens a panel.
EventTypeDescriptionchangeEventSent when the user finishes changing the value.helix-before-changeHelixBeforeChangeEventThe color is about to change. Cancelable: cancel it to keep the current color.helix-before-closeHelixBeforeCloseEventThe panel is about to close. Cancelable: cancel it to keep it open.helix-before-openHelixBeforeOpenEventThe panel is about to open. Cancelable: cancel it to keep it closed.inputEventFired as the value changes.toggleToggleEventThe panel opened or closed. The event carries newState and oldState.
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) => voidPuts the caret in the field, as clicking its label does.reportValidity() => booleanReturns whether the control is valid, and when it is not, fires invalid
and shows the browser's message at the control.requestOpen(next: boolean) => booleanRequests that the element open or close, and returns whether the change
was applied.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.toggleOpen() => booleanRequests the opposite of the current state.
PartDescriptioncontrolThe text input that holds the value. Absent in the swatch variant.feedbackThe message that says what is wrong with the value.fieldThe box holding the text and the trigger.hintHelp text under the field, shown while there is no feedback.labelThe label above the field.pickerThe color picker inside the panel.picker-actionsThe group holding the eyedropper and the syntax toggle.picker-channelOne channel slider.picker-channel-controlThe range input of a channel slider.picker-channel-feedbackThe error message for a channel slider.picker-channel-fieldThe row that holds a channel slider's control and its readout.picker-channel-hintThe help text under the track, shown while there is no error.picker-channel-labelThe label above the track.picker-channel-markerOne mark on the track.picker-channel-marker-labelThe value a mark stands at, when marker-labels is set.picker-channel-markersThe row of marks along the track.picker-channel-outputThe current value, shown beside the track.picker-channel-thumbA ramp's thumb box, which holds no content in a picker.picker-channel-thumbsThe layer over a ramp's track that holds its thumb box.picker-channel-tooltipA ramp's value in a bubble, where a ramp shows one.picker-channel-tooltipsThe layer over a ramp's track that holds its bubble.picker-channelsThe channel sliders beside the sample.picker-controlsThe row under the square.picker-eyedropperThe control that samples a color from the screen.picker-eyedropper-buttonThe button inside picker-eyedropper.picker-eyedropper-liveThe live region of the button inside picker-eyedropper, which says its pending label.picker-eyedropper-spinnerThe ring the eyedropper button turns while it is pending.picker-eyedropper-textThe words on the button inside picker-eyedropper.picker-feedbackThe field's message inside the open panel, under the picker, where the panel covers the one under the field.picker-fieldOne channel's number field with its label, in channel-fields.picker-field-inputThe number input in a channel's field.picker-field-labelThe name above a channel's number input.picker-fieldsThe row of channel number fields, in channel-fields.picker-footerThe row holding the value and the tools.picker-formatThe control that changes the syntax the value is written in.picker-format-buttonThe button inside picker-format.picker-format-liveThe live region of the button inside picker-format, which says its pending label.picker-format-spinnerThe ring the syntax button turns while it is pending.picker-format-textThe words on the button inside picker-format.picker-gridThe saturation and brightness square.picker-grid-brightnessThe range input for the square's vertical axis.picker-grid-handleThe mark showing where in the square the color sits.picker-grid-saturationThe range input for the square's horizontal axis.picker-hintThe picker's own help, which the field's hint stands in for here, so it stays hidden.picker-iconAn icon drawn by the picker.picker-labelThe picker's own name, which the field's label stands in for here, so it stays hidden.picker-sampleA chip of the current color. Pressing it copies the value.picker-swatchOne preset.picker-swatchesThe row of presets.picker-valueThe text field that holds the color. It accepts a typed or pasted color.picker-wheelThe hue ring round the square, with wheel.picker-wheel-hueThe range input behind the hue ring.previewThe chip showing the color, inside the trigger.surfaceThe floating panel.triggerThe control that opens the panel.
CSS PropertyDescription--color-input-background-colorFill behind the field.--color-input-border-colorColor of the panel's edge.--color-input-border-widthWidth of the panel's edge. Defaults to --helix-border-floating, which is 0, so the panel stands out by its shadow unless a theme sets a border. --helix-border-floating, which is 0, so the panel is told apart by its lift unless a theme says otherwise.--color-input-panel-sizeWidth of the panel, and so of the square.--color-input-shadowShadow under the panel. Defaults to --helix-shadow-floating, so the panel keeps a shadow over any content below it. --helix-shadow-floating: a floating surface sits over content nobody can predict, so it keeps a lift by default.--color-input-swatchThe chosen color, painted over the checkerboard that shows transparency.--color-input-swatch-radiusCorner radius of the swatch in variant="swatch".--color-input-swatch-sizeEdge length of the swatch in variant="swatch".
Custom stateDescriptioninvalidThe control has an error to show, from the browser's validation or from your feedback.openWhile the picker is open.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Roothelix-headless-color-inputA field for a color, typed in any syntax or picked from a panel.
PropTypeDescriptionalphabooleanDefaultfalseWhether the color carries an alpha channel.autocompletestringDefault"off"What the browser may autofill in the text field, as a platform token.badInputMessagestringThe message shown when the field holds text the picker cannot read as a
date, a time, or a color.channelFieldsbooleanDefaultfalseWhether the panel shows a number field for each channel of the color.
Passed to the panel; see Color Picker's channel-fields.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"}.defaultOpenbooleanDefaultfalseWhether the element starts open. Ignored once open is written.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.feedbackstringDefault""The validation message shown under the control. It replaces the
browser's message.format"hex"|"hsb"|"hsl"|"oklch"|"rgb"The syntax the value is written in: hex, rgb, hsl, oklch, or
hsb, as Color Picker's format.hintstringDefault""Help text shown under the control. A validation message replaces it.labelstringDefault""The field's label, which is also its accessible name. Content in the
label slot replaces it.namestringDefault""The name the control's value is submitted under.noFormatbooleanDefaultfalseHides the button in the panel that changes the format.openbooleanWhether the element is open.placeholderstringDefault"#000000"The text the field shows before a color is entered.readOnlybooleanDefaultfalseWhether the color is locked. A read-only field still submits its value.requiredbooleanDefaultfalseWhether the field needs a value before the form can submit.swatchesstringDefault""Colors offered under the picker, as a comma-separated list.swatchLabelstringDefault"{name} {value}"What the swatch says in variant="swatch", after the field's label, once
there is a color. {name} is the color's name, such as "vibrant red", and
{value} the value as written.triggerLabelstringDefault"Choose a color"Accessible name for the control that opens the panel.valuestringThe control's current value, which its form submits.valueMissingMessagestringThe message shown when the field is required and empty.variant"swatch"Whether the field is a text box with a swatch on it, or only the swatch.wheelbooleanDefaultfalseDraws the panel's hue as a wheel around the square, in place of the hue
ramp. See Color Picker's wheel.
ReadTypeDescriptionformHTMLFormElement|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.
SlotDescriptionendContent at the trailing end, before the trigger.feedbackThe message that says what is wrong with the value.hintHelp text under the field.labelThe label, for content richer than the label text.panel-footerContent in the panel under the picker, such as a note or an action.panel-headerContent in the panel above the picker, such as a heading or a shortcut.startContent at the leading end of the field, inside its border.triggerThe icon on the trigger, which shows that the field opens a panel.
EventTypeDescriptionchangeEventSent when the user finishes changing the value.helix-before-changeHelixBeforeChangeEventThe color is about to change. Cancelable: cancel it to keep the current color.helix-before-closeHelixBeforeCloseEventThe panel is about to close. Cancelable: cancel it to keep it open.helix-before-openHelixBeforeOpenEventThe panel is about to open. Cancelable: cancel it to keep it closed.inputEventFired as the value changes.toggleToggleEventThe panel opened or closed. The event carries newState and oldState.
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) => voidPuts the caret in the field, as clicking its label does.reportValidity() => booleanReturns whether the control is valid, and when it is not, fires invalid
and shows the browser's message at the control.requestOpen(next: boolean) => booleanRequests the panel open or closed. While readOnly is set, it does not open.requestValue(next: string) => booleanRequests a new value. While readOnly is set, nothing changes.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.toggleOpen() => booleanRequests the opposite of the current state.
PartDescriptioncontrolThe text input that holds the value. Absent in the swatch variant.feedbackThe message that says what is wrong with the value.fieldThe box holding the text and the trigger.hintHelp text under the field, shown while there is no feedback.labelThe label above the field.pickerThe color picker inside the panel.picker-actionsThe group holding the eyedropper and the syntax toggle.picker-channelOne channel slider.picker-channel-controlThe range input of a channel slider.picker-channel-feedbackThe error message for a channel slider.picker-channel-fieldThe row that holds a channel slider's control and its readout.picker-channel-hintThe help text under the track, shown while there is no error.picker-channel-labelThe label above the track.picker-channel-markerOne mark on the track.picker-channel-marker-labelThe value a mark stands at, when marker-labels is set.picker-channel-markersThe row of marks along the track.picker-channel-outputThe current value, shown beside the track.picker-channel-thumbA ramp's thumb box, which holds no content in a picker.picker-channel-thumbsThe layer over a ramp's track that holds its thumb box.picker-channel-tooltipA ramp's value in a bubble, where a ramp shows one.picker-channel-tooltipsThe layer over a ramp's track that holds its bubble.picker-channelsThe channel sliders beside the sample.picker-controlsThe row under the square.picker-eyedropperThe control that samples a color from the screen.picker-eyedropper-buttonThe button inside picker-eyedropper.picker-eyedropper-liveThe live region of the button inside picker-eyedropper, which says its pending label.picker-eyedropper-spinnerThe ring the eyedropper button turns while it is pending.picker-eyedropper-textThe words on the button inside picker-eyedropper.picker-feedbackThe field's message inside the open panel, under the picker, where the panel covers the one under the field.picker-fieldOne channel's number field with its label, in channel-fields.picker-field-inputThe number input in a channel's field.picker-field-labelThe name above a channel's number input.picker-fieldsThe row of channel number fields, in channel-fields.picker-footerThe row holding the value and the tools.picker-formatThe control that changes the syntax the value is written in.picker-format-buttonThe button inside picker-format.picker-format-liveThe live region of the button inside picker-format, which says its pending label.picker-format-spinnerThe ring the syntax button turns while it is pending.picker-format-textThe words on the button inside picker-format.picker-gridThe saturation and brightness square.picker-grid-brightnessThe range input for the square's vertical axis.picker-grid-handleThe mark showing where in the square the color sits.picker-grid-saturationThe range input for the square's horizontal axis.picker-hintThe picker's own help, which the field's hint stands in for here, so it stays hidden.picker-iconAn icon drawn by the picker.picker-labelThe picker's own name, which the field's label stands in for here, so it stays hidden.picker-sampleA chip of the current color. Pressing it copies the value.picker-swatchOne preset.picker-swatchesThe row of presets.picker-valueThe text field that holds the color. It accepts a typed or pasted color.picker-wheelThe hue ring round the square, with wheel.picker-wheel-hueThe range input behind the hue ring.previewThe chip showing the color, inside the trigger.surfaceThe floating panel.triggerThe control that opens the panel.
CSS PropertyDescription--color-input-swatchThe chosen color, painted over the checkerboard that shows transparency.
Custom stateDescriptioninvalidThe control has an error to show, from the browser's validation or from your feedback.openWhile the picker is open.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Examples
NameDescriptionAlphaA color with opacity, written in a syntax that includes it.DisabledA disabled field, with the swatch still showing the color.EventsThe events the field sends as its panel opens and closes and its value changes.InvalidA color the field does not accept, with the message that says why.PreviewA field with a swatch that opens a picker.PreviewA field with a swatch that opens a picker.Raw ValueThe value kept exactly as typed, for code that parses the color itself.Swatch OnlyThe swatch alone, for a toolbar with no room for a field.SwatchesPreset colors offered under the picker.