Kobalte.v0.13.7
GitHub

Color Channel Field

A number input that allow users to edit individual color channel value.

Import

ts
import { ColorChannelField } from "@kobalte/core/color-channel-field";
// or
import { Root, Label, ... } from "@kobalte/core/color-channel-field";
ts
import { ColorChannelField } from "@kobalte/core/color-channel-field";
// or
import { Root, Label, ... } from "@kobalte/core/color-channel-field";

Features

  • Follows the WAI ARIA Spinbutton design pattern.
  • Built with a native <input> element.
  • Visual and ARIA labeling support.
  • Required and invalid states exposed to assistive technology via ARIA.
  • Support for description and error message help text linked to the input via ARIA.
  • Syncs with form reset events.
  • Can be controlled or uncontrolled.
  • Supports increment and decrement buttons.
  • Format and localize input number and raw input.
  • Supports mouse wheel event and all keyboard events.

Anatomy

The color channel field consists of:

  • ColorChannelField: The root container for the color channel field.
  • ColorChannelField.Label: The label that gives the user information on the color channel field.
  • ColorChannelField.Input: The native HTML input of the color channel field, used for display number.
  • ColorChannelField.HiddenInput: The native HTML input of the color channel field, used for raw number form submition.
  • ColorChannelField.IncrementTrigger: The increment button of the color channel field.
  • ColorChannelField.DecrementTrigger: The decrement button of the color channel field.
  • ColorChannelField.Description: The description that gives the user more information on the color channel field.
  • ColorChannelField.ErrorMessage: The error message that gives the user information about how to fix a validation error on a color channel field.
tsx
<ColorChannelField>
	<ColorChannelField.Label />
	<ColorChannelField.Input />
	<ColorChannelField.HiddenInput />
	<ColorChannelField.IncrementTrigger />
	<ColorChannelField.DecrementTrigger />
	<ColorChannelField.Description />
	<ColorChannelField.ErrorMessage />
</ColorChannelField>
tsx
<ColorChannelField>
	<ColorChannelField.Label />
	<ColorChannelField.Input />
	<ColorChannelField.HiddenInput />
	<ColorChannelField.IncrementTrigger />
	<ColorChannelField.DecrementTrigger />
	<ColorChannelField.Description />
	<ColorChannelField.ErrorMessage />
</ColorChannelField>

Example

Usage

A ColorChannelField requires either an uncontrolled default value or a controlled value, provided using the defaultValue or value props respectively. The value provided to either of these props should be Color object. You can obtain a Color object by using the parseColor function to parse a color from a string. The channel prop must also be provided to specify which color channel the field manipulates. This must be one of the channels included in the color value, for example, for RGB colors, the "red", "green", and "blue" channels are available.

Default value

tsx
<ColorChannelField defaultValue={parseColor("hsl(200, 98%, 39%)")} channel="saturation">
	<ColorChannelField.Label>Saturation</ColorChannelField.Label>
	<div>
		<ColorChannelField.Input />
		<ColorChannelField.IncrementTrigger />
		<ColorChannelField.DecrementTrigger />
	</div>
</ColorChannelField>
tsx
<ColorChannelField defaultValue={parseColor("hsl(200, 98%, 39%)")} channel="saturation">
	<ColorChannelField.Label>Saturation</ColorChannelField.Label>
	<div>
		<ColorChannelField.Input />
		<ColorChannelField.IncrementTrigger />
		<ColorChannelField.DecrementTrigger />
	</div>
</ColorChannelField>

Controlled value

Lightness: 39%

tsx
import { createSignal } from "solid-js";
function ControlledExample() {
	const [value, setValue] = createSignal(parseColor("hsl(200, 98%, 39%)"));
	return (
		<>
			<ColorChannelField value={value()} onChange={setValue}>
				<ColorChannelField.Label>Lightness</ColorChannelField.Label>
				<div>
					<ColorChannelField.Input />
					<ColorChannelField.IncrementTrigger />
					<ColorChannelField.DecrementTrigger />
				</div>
			</ColorChannelField>
			<p>Lightness: {value().getChannelValue("lightness")}%</p>
		</>
	);
}
tsx
import { createSignal } from "solid-js";
function ControlledExample() {
	const [value, setValue] = createSignal(parseColor("hsl(200, 98%, 39%)"));
	return (
		<>
			<ColorChannelField value={value()} onChange={setValue}>
				<ColorChannelField.Label>Lightness</ColorChannelField.Label>
				<div>
					<ColorChannelField.Input />
					<ColorChannelField.IncrementTrigger />
					<ColorChannelField.DecrementTrigger />
				</div>
			</ColorChannelField>
			<p>Lightness: {value().getChannelValue("lightness")}%</p>
		</>
	);
}

Description

The ColorChannelField.Description component can be used to associate additional help text with a color channel field.

Enter your favorite hue.
tsx
<ColorChannelField defaultValue={parseColor("hsl(0, 98%, 39%)")} channel="hue">
	<ColorChannelField.Label>Hue</ColorChannelField.Label>
	<div>
		<ColorChannelField.Input />
		<ColorChannelField.IncrementTrigger />
		<ColorChannelField.DecrementTrigger />
	</div>
	<ColorChannelField.Description>Enter your favorite hue.</ColorChannelField.Description>
</ColorChannelField>
tsx
<ColorChannelField defaultValue={parseColor("hsl(0, 98%, 39%)")} channel="hue">
	<ColorChannelField.Label>Hue</ColorChannelField.Label>
	<div>
		<ColorChannelField.Input />
		<ColorChannelField.IncrementTrigger />
		<ColorChannelField.DecrementTrigger />
	</div>
	<ColorChannelField.Description>Enter your favorite hue.</ColorChannelField.Description>
</ColorChannelField>

Error message

The ColorChannelField.ErrorMessage component can be used to help the user fix a validation error. It should be combined with the validationState prop to semantically mark the field as invalid for assistive technologies.

By default, it will render only when the validationState prop is set to invalid, use the forceMount prop to always render the error message (ex: for usage with animation libraries).

Hmm, I prefer 40% saturation.
tsx
import { createSignal } from "solid-js";
function ErrorMessageExample() {
	const [value, setValue] = createSignal(parseColor("hsl(200, 30%, 39%)"));
	return (
		<ColorChannelField
			value={value()}
			channel="saturation"
			onChange={setValue}
			validationState={value().getChannelValue("saturation") !== 40 ? "invalid" : "valid"}
		>
			<ColorChannelField.Label>Saturation</ColorChannelField.Label>
			<div>
				<ColorChannelField.Input />
				<ColorChannelField.IncrementTrigger />
				<ColorChannelField.DecrementTrigger />
			</div>
			<ColorChannelField.ErrorMessage>Hmm, I prefer 40% saturation.</ColorChannelField.ErrorMessage>
		</ColorChannelField>
	);
}
tsx
import { createSignal } from "solid-js";
function ErrorMessageExample() {
	const [value, setValue] = createSignal(parseColor("hsl(200, 30%, 39%)"));
	return (
		<ColorChannelField
			value={value()}
			channel="saturation"
			onChange={setValue}
			validationState={value().getChannelValue("saturation") !== 40 ? "invalid" : "valid"}
		>
			<ColorChannelField.Label>Saturation</ColorChannelField.Label>
			<div>
				<ColorChannelField.Input />
				<ColorChannelField.IncrementTrigger />
				<ColorChannelField.DecrementTrigger />
			</div>
			<ColorChannelField.ErrorMessage>Hmm, I prefer 40% saturation.</ColorChannelField.ErrorMessage>
		</ColorChannelField>
	);
}

HTML forms

The color channel field name prop along with <ColorChannelField.HiddenInput/> can be used for integration with HTML forms. Only the raw value is passed to the form.

If the formatted value is wanted (unrecommended) set the name attribute on <ColorChannelField.Input/>.

tsx
function HTMLFormExample() {
	const onSubmit = (e: SubmitEvent) => {
		// handle form submission.
	};
	return (
		<form onSubmit={onSubmit}>
			<ColorChannelField name="hue" defaultValue={parseColor("hsl(10, 98%, 39%)")} channel="hue">
				<ColorChannelField.Label>Hue</ColorChannelField.Label>
				<ColorChannelField.HiddenInput />
				<div>
					<ColorChannelField.Input />
					<ColorChannelField.IncrementTrigger />
					<ColorChannelField.DecrementTrigger />
				</div>
			</ColorChannelField>
			<div>
				<button type="reset">Reset</button>
				<button type="submit">Submit</button>
			</div>
		</form>
	);
}
tsx
function HTMLFormExample() {
	const onSubmit = (e: SubmitEvent) => {
		// handle form submission.
	};
	return (
		<form onSubmit={onSubmit}>
			<ColorChannelField name="hue" defaultValue={parseColor("hsl(10, 98%, 39%)")} channel="hue">
				<ColorChannelField.Label>Hue</ColorChannelField.Label>
				<ColorChannelField.HiddenInput />
				<div>
					<ColorChannelField.Input />
					<ColorChannelField.IncrementTrigger />
					<ColorChannelField.DecrementTrigger />
				</div>
			</ColorChannelField>
			<div>
				<button type="reset">Reset</button>
				<button type="submit">Submit</button>
			</div>
		</form>
	);
}

Triggers

The color channel field supports optional increment/decrement triggers that are easily customizable.

tsx
<ColorChannelField defaultValue={parseColor("hsb(10, 98%, 50%)")} channel="brightness">
	<ColorChannelField.Label>Brightness</ColorChannelField.Label>
	<div>
		<ColorChannelField.DecrementTrigger class="custom-trigger">
			-
		</ColorChannelField.DecrementTrigger>
		<ColorChannelField.Input />
		<ColorChannelField.IncrementTrigger class="custom-trigger">
			+
		</ColorChannelField.IncrementTrigger>
	</div>
</ColorChannelField>
tsx
<ColorChannelField defaultValue={parseColor("hsb(10, 98%, 50%)")} channel="brightness">
	<ColorChannelField.Label>Brightness</ColorChannelField.Label>
	<div>
		<ColorChannelField.DecrementTrigger class="custom-trigger">
			-
		</ColorChannelField.DecrementTrigger>
		<ColorChannelField.Input />
		<ColorChannelField.IncrementTrigger class="custom-trigger">
			+
		</ColorChannelField.IncrementTrigger>
	</div>
</ColorChannelField>

API Reference

ColorChannelField

ColorChannelField is equivalent to the Root import from @kobalte/core/color-channel-field.

PropDescription
valueColor
The controlled formatted value of the field.
defaultValueColor
The default value when initially rendered. Useful when you do not need to control the value.
colorSpaceColorSpace
The color space that the field operates in. The channel must be in this color space.
onChange(value: Color) => void
Event handler called when the value of the field changes.
minValuenumber
The smallest value allowed in the number field.
maxValuenumber
The largest value allowed in the number field.
stepnumber
Increment/Decrement step when using the triggers or the arrows on keyboard in the field.
largeStepnumber
Increment/Decrement step when using the Page UP/Down keys in the field, defaults 10 * step.
changeOnWheelboolean
Whether to increment/decrement on wheel scroll inside the field.
formatboolean
Whether to format the input value.
namestring
The name of the ColorChannelField.HiddenInput of the field, used when submitting an HTML form. See MDN.
validationState'valid' | 'invalid'
Whether the field should display its "valid" or "invalid" visual styling.
requiredboolean
Whether the user must fill the field before the owning form can be submitted.
disabledboolean
Whether the field is disabled.
readOnlyboolean
Whether the field items can be selected but not changed by the user.
Data attributeDescription
data-validPresent when the field is valid according to the validation rules.
data-invalidPresent when the field is invalid according to the validation rules.
data-requiredPresent when the user must fill the field before the owning form can be submitted.
data-disabledPresent when the field is disabled.
data-readonlyPresent when the field is read only.

ColorChannelField.Label, ColorChannelField.Input, ColorChannelField.HiddenInput, ColorChannelField.Description and ColorChannelField.ErrorMesssage share the same data-attributes.

ColorChannelField.ErrorMessage

PropDescription
forceMountboolean
Used to force mounting when more control is needed. Useful when controlling animation with SolidJS animation libraries.

Rendered elements

ComponentDefault rendered element
ColorChannelFielddiv
ColorChannelField.Labellabel
ColorChannelField.Inputinput
ColorChannelField.HiddenInputinput
ColorChannelField.IncrementTriggerbutton
ColorChannelField.DecrementTriggerbutton
ColorChannelField.Descriptiondiv
ColorChannelField.ErrorMessagediv
Previous
Color Area
Next
Color Field