Color Field

Allows users to enter and adjust a hex color value.

Import

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

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

Features

• Support for parsing and formatting a hex color value.
• Validates keyboard entry as the user types so that only valid hex characters are accepted.
• 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.

Anatomy

The color field consists of:

• ColorField: The root container for the color field.
• ColorField.Label: The label that gives the user information on the color field.
• ColorField.Input: The native HTML input of the color field.
• ColorField.Description: The description that gives the user more information on the color field.
• ColorField.ErrorMessage: The error message that gives the user information about how to fix a validation error on the color field.

tsx
<ColorField>
	<ColorField.Label />
	<ColorField.Input />
	<ColorField.Description />
	<ColorField.ErrorMessage />
</ColorField>

tsx
<ColorField>
	<ColorField.Label />
	<ColorField.Input />
	<ColorField.Description />
	<ColorField.ErrorMessage />
</ColorField>

Example

Usage

Default value

An initial, uncontrolled value can be provided using the defaultValue prop.

tsx
<ColorField class="color-field" defaultValue="#7f007f">
	<ColorField.Label class="color-field__label">Favorite color</ColorField.Label>
	<ColorField.Input class="color-field__input" />
</ColorField>

tsx
<ColorField class="color-field" defaultValue="#7f007f">
	<ColorField.Label class="color-field__label">Favorite color</ColorField.Label>
	<ColorField.Input class="color-field__input" />
</ColorField>

Controlled value

The value prop can be used to make the value controlled. The onChange event is fired when the user type into the input and receive the new value.

tsx
import { createSignal } from "solid-js";
function ControlledExample() {
	const [value, setValue] = createSignal("#7f007f");
	return (
		<>
			<ColorField class="color-field" value={value()} onChange={setValue}>
				<ColorField.Label class="color-field__label">Favorite color</ColorField.Label>
				<ColorField.Input class="color-field__input" />
			</ColorField>
			<p>Your favorite color is: {value()}</p>
		</>
	);
}

tsx
import { createSignal } from "solid-js";
function ControlledExample() {
	const [value, setValue] = createSignal("#7f007f");
	return (
		<>
			<ColorField class="color-field" value={value()} onChange={setValue}>
				<ColorField.Label class="color-field__label">Favorite color</ColorField.Label>
				<ColorField.Input class="color-field__input" />
			</ColorField>
			<p>Your favorite color is: {value()}</p>
		</>
	);
}

Description

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

tsx
<ColorField class="color-field">
	<ColorField.Label class="color-field__label">Favorite color</ColorField.Label>
	<ColorField.Input class="color-field__input" />
	<ColorField.Description class="color-field__description">
		Choose the color you like the most.
	</ColorField.Description>
</ColorField>

tsx
<ColorField class="color-field">
	<ColorField.Label class="color-field__label">Favorite color</ColorField.Label>
	<ColorField.Input class="color-field__input" />
	<ColorField.Description class="color-field__description">
		Choose the color you like the most.
	</ColorField.Description>
</ColorField>

Error message

The ColorField.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 color 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).

tsx
import { createSignal } from "solid-js";
function ErrorMessageExample() {
	const [value, setValue] = createSignal("#7f007f");
	return (
		<ColorField
			value={value()}
			onChange={setValue}
			validationState={value() !== "#000000" ? "invalid" : "valid"}
		>
			<ColorField.Label>Favorite color</ColorField.Label>
			<ColorField.Input />
			<ColorField.ErrorMessage>Hmm, I prefer black.</ColorField.ErrorMessage>
		</ColorField>
	);
}

tsx
import { createSignal } from "solid-js";
function ErrorMessageExample() {
	const [value, setValue] = createSignal("#7f007f");
	return (
		<ColorField
			value={value()}
			onChange={setValue}
			validationState={value() !== "#000000" ? "invalid" : "valid"}
		>
			<ColorField.Label>Favorite color</ColorField.Label>
			<ColorField.Input />
			<ColorField.ErrorMessage>Hmm, I prefer black.</ColorField.ErrorMessage>
		</ColorField>
	);
}

HTML forms

The color field name prop can be used for integration with HTML forms.

tsx
function HTMLFormExample() {
	const onSubmit = (e: SubmitEvent) => {
		// handle form submission.
	};
	return (
		<form onSubmit={onSubmit}>
			<ColorField name="favorite-color">
				<ColorField.Label>Favorite color</ColorField.Label>
				<ColorField.Input />
			</ColorField>
		</form>
	);
}

tsx
function HTMLFormExample() {
	const onSubmit = (e: SubmitEvent) => {
		// handle form submission.
	};
	return (
		<form onSubmit={onSubmit}>
			<ColorField name="favorite-color">
				<ColorField.Label>Favorite color</ColorField.Label>
				<ColorField.Input />
			</ColorField>
		</form>
	);
}

API Reference

ColorField

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

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

ColorField.ErrorMessage

Rendered elements