Choose a version:

Color field

The color field component allows users to select colors through an integrated color picker or direct text input. Use color field for theme colors, brand colors, or any color selection to provide both visual and text-based color input methods.

Color fields support hex color codes, color preview swatches, and validation to ensure users select or enter valid color values. For a standalone visual color palette interface without text input, use color picker.

Support

Targets (47)

Supported targets

Anchor to PropertiesProperties

Configure the following properties on the color field component.

Anchor to alpha alpha boolean Default: false required: Whether to enable alpha (transparency) channel selection in the color picker, allowing users to choose semi-transparent colors.
Anchor to value value string required: The currently selected color value. Accepts multiple input formats:

Hex: #RGB, #RRGGBB, #RRGGBBAA (3, 6, or 8 digits)

RGB/RGBA: rgb(255, 0, 0) or rgb(255 0 0) (comma or space-separated)

HSL/HSLA: hsl(0, 100%, 50%) or hsl(0 100% 50%)

Returns an empty string if the value is invalid. The change event always emits values in hex format.
Anchor to autocomplete autocomplete "on" | "off" Default: 'on' for everything else required: Controls browser autofill behavior for the field.

Basic values:

on - Enables autofill without specifying content type (default)

off - Disables autofill for sensitive data or one-time codes

Specific field values describe the expected data type. You can optionally prefix these with:

section-${string} - Scopes autofill to a specific form section (when multiple forms exist on the same page)

shipping or billing - Indicates whether the data is for shipping or billing purposes

Both section and group (for example, section-primary shipping email)

Providing a specific autofill token helps browsers suggest more relevant saved data.

Learn more about the set of autocomplete values supported in browsers.
Anchor to defaultValue defaultValue string required: The initial value of the field when it first loads. Unlike placeholder, this is a real value that the user can edit and that gets submitted with the form. Once the user starts typing, their input replaces it. Changing this property after the field has loaded has no effect. To update the field value at any time, use value instead.
Anchor to details details string required: Supplementary text displayed below the checkbox to provide additional context, instructions, or help. Use this to explain what checking the box means or provide guidance to users. This text is announced to screen readers.
Anchor to error error string required: An error message displayed below the checkbox to indicate validation problems. When set, the checkbox is styled with error indicators and the message is announced to screen readers.
Anchor to label label string required: The text displayed as the field label, which identifies the purpose of the field to users. This label is associated with the field for accessibility and helps users understand what information to provide.
Anchor to labelAccessibilityVisibility labelAccessibilityVisibility "visible" | "exclusive" Default: 'visible' required: Controls whether the label is visible to all users or only to screen readers.

visible: The label is shown to everyone (default).

exclusive: The label is visually hidden but still announced by screen readers.

Use exclusive when the surrounding context makes the label redundant visually, but screen reader users still need it for clarity.
Anchor to placeholder placeholder string required: The placeholder text displayed in the field when it's empty, providing a hint about the expected input format or value.
Anchor to readOnly readOnly boolean Default: false required: Whether the field is read-only and can't be edited. Read-only fields remain focusable and their content is announced by screen readers.
Anchor to required required boolean Default: false required: Whether the field requires a value before form submission. Displays a visual indicator and adds semantic meaning, but doesn't automatically validate or show errors. Use the error property to display validation messages.
Anchor to disabled disabled boolean Default: false required: Whether the field is disabled, preventing any user interaction.
Anchor to id id string required: A unique identifier for the element. Use this to reference the element in JavaScript, link labels to form controls, or target specific elements for styling or scripting.
Anchor to name name string required: The name attribute for the field, used to identify the field's value when the form is submitted. Must be unique within the nearest containing form.

Anchor to EventsEvents

The color field component provides event callbacks for handling user interactions. Learn more about handling events.

Anchor to blur blur <'input'> required: A callback fired when the color field loses focus.

Learn more about the blur event.
Anchor to change change <'input'> required: A callback fired when the color field value changes.

Learn more about the change event.
Anchor to focus focus <'input'> required: A callback fired when the color field receives focus.

Learn more about the focus event.
Anchor to input input <'input'> required: A callback fired when the user inputs data into the color field.

Learn more about the input event.

CallbackEventListener

A function that handles events from UI components. This type represents an event listener callback that receives a `CallbackEvent` with a strongly-typed `currentTarget`. Use this for component event handlers like `click`, `focus`, `blur`, and other DOM events.

(EventListener & {
      (event: CallbackEvent<T>): void;
    }) | null

CallbackEvent

An event object with a strongly-typed `currentTarget` property that references the specific HTML element that triggered the event. This type extends the standard DOM `Event` interface and ensures type safety when accessing the element that fired the event.

Event & {
  currentTarget: HTMLElementTagNameMap[T];
}

Anchor to ExamplesExamples

Anchor to Pick a colorPick a color

Display a labeled color field with a pre-selected hex value.

Preview

html

<s-color-field

label="Brand color"

value="#FF0000"

></s-color-field>

Anchor to Add a labelAdd a label

Identify the color field's purpose clearly. This example displays a labeled color field with a name attribute for form submission.

Preview

html

<s-stack gap="base">

<s-color-field label="Brand color" name="color" value="#FF0000"></s-color-field>

</s-stack>

Anchor to Mark as requiredMark as required

Ensure users provide a color value before submitting. This example presents a required color field that must have a value.

Preview

html

<s-stack gap="base">

<s-color-field label="Brand color" value="#FF0000" required></s-color-field>

</s-stack>

Anchor to Enable alpha transparencyEnable alpha transparency

Allow selection of semi-transparent colors. This example displays a color field with alpha enabled, presenting an RGBA value with 50% opacity.

Preview

html

<s-stack gap="base">

<s-color-field

label="Background color"

value="rgba(255, 0, 0, 0.5)"

alpha

></s-color-field>

</s-stack>

Anchor to Show a validation errorShow a validation error

Communicate color format problems clearly. This example demonstrates an error message when an invalid hex code is entered.

Preview

html

<s-stack gap="base">

<s-color-field

label="Brand color"

name="brandColor"

value="#invalid"

error="Please enter a valid color format (hex, rgb, or rgba)"

required

></s-color-field>

</s-stack>

Anchor to Add helper textAdd helper text

Guide users on how the color will be used. This example adds helper text beneath the field explaining the color's purpose.

Preview

html

<s-stack gap="base">

<s-color-field

label="Primary color"

value="#1a73e8"

details="Main brand color used for buttons and links"

></s-color-field>

</s-stack>

Anchor to Show a read-only fieldShow a read-only field

Show a color value without allowing changes. This example presents a read-only color field displaying a locked value.

Preview

html

<s-stack gap="base">

<s-color-field label="System color" name="color" value="#1a73e8" readOnly></s-color-field>

</s-stack>

Anchor to Combine multiple fields in a formCombine multiple fields in a form

Build a complete theme customization interface. This example combines multiple color fields for primary, secondary, and overlay colors with helper text.

Preview

html

<s-stack gap="base">

<s-section>

<s-heading>Theme settings</s-heading>

<s-stack gap="base">

<s-color-field

label="Primary brand color"

name="primaryColor"

value="#1a73e8"

details="This color will be used for buttons, links, and brand elements"

required

></s-color-field>

<s-color-field

label="Secondary color"

name="secondaryColor"

value="#34a853"

details="Used for secondary actions and accents"

></s-color-field>

<s-color-field

label="Background overlay"

name="overlayColor"

value="rgba(0, 0, 0, 0.5)"

alpha

details="Background color for modal overlays and dropdowns"

></s-color-field>

</s-stack>

</s-section>

</s-stack>

Anchor to Validate in real timeValidate in real time

Display a validation error for an invalid color value. This example shows a color field with a static error message for a malformed hex code.

Preview

html

<s-section>

<s-stack gap="base" justifyContent="start">

<s-text-field label="Theme name"></s-text-field>

<s-color-field

label="Brand color"

name="Color"

value="#invalid"

error="Please enter a valid color format"

required

></s-color-field>

</s-stack>

</s-section>

Anchor to Best practicesBest practices

Label by specific purpose: Use labels that describe exactly what the color affects (Button background color, Heading text color, or Border accent color rather than generic Color).
Pre-populate when editing: Always show the current color value when editing existing settings so merchants understand what they're changing from.

Anchor to LimitationsLimitations

The component always outputs values in hex format. While it accepts multiple input formats (hex, RGB, HSL), the change event emits values in hex: 6-digit (#RRGGBB) or 8-digit with alpha (#RRGGBBAA).

Was this page helpful?