sp-color-field

quiet true false
disabled true false
viewColor true false
size Small Medium Large Extra large
Overview API Changelog

Overview

Section titled Overview

<sp-color-field> elements are textfields that allow users to input custom color values. They support multiple color formats including HEX, RGB, HSL, HSV, and shorthand HEX formats, providing a flexible interface for color selection in applications.

Usage

Section titled Usage

See it on NPM! How big is this package in your project?

yarn add @spectrum-web-components/color-field

Import the side effectful registration of <sp-color-field> via:

import '@spectrum-web-components/color-field/sp-color-field.js';

When looking to leverage the ColorField base class as a type and/or for extension purposes, do so via:

import { ColorField } from '@spectrum-web-components/color-field';

Anatomy

Section titled Anatomy

The color field consists of several key parts:

  • Input field: The main text input area where users can type color values
  • Color handle: An optional visual indicator showing the current color (when view-color attribute is enabled)
  • Validation feedback: Visual indicators for valid and invalid color inputs
  • Size variations: Different size options to match your design requirements
<sp-color-field value="#ffff00"></sp-color-field>

Options

Section titled Options

Sizes

Section titled Sizes
Small
<sp-color-field size="s" value="#ffff00"></sp-color-field>
Medium
<sp-color-field size="m" value="#ffff00"></sp-color-field>
Large
<sp-color-field size="l" value="#ffff00"></sp-color-field>
Xtra Large
<sp-color-field size="xl" value="#ffff00"></sp-color-field>

View Color

Section titled View Color

When view-color is true, the color handle will be rendered. This is useful for development and debugging purposes.

<sp-color-field view-color value="#f00"></sp-color-field>

Quiet

Section titled Quiet

A quiet color field provides a more subtle appearance:

<sp-color-field quiet value="#e6e600"></sp-color-field>

States

Section titled States

Standard

Section titled Standard

The default state of the color field, ready for user input:

<sp-color-field value="#ffff00"></sp-color-field>

Read Only

Section titled Read Only

A readonly color field that displays the color value but prevents user modification:

<sp-color-field readonly value="#ffff00"></sp-color-field>

Invalid Input

Section titled Invalid Input

If the input value is not a valid color, <sp-color-field> will not accept it and may show validation feedback:

<sp-color-field value="not a color"></sp-color-field>

Behaviors

Section titled Behaviors

Color Format Support

Section titled Color Format Support

The <sp-color-field> component accepts color values in various formats: HEX, RGB, HSL, HSV, and shorthand HEX

For a complete list of supported color formats, see the ColorController documentation.

HEX

A hexadecimal color is specified with: #RRGGBB. RR (red), GG (green) and BB (blue) are hexadecimal integers between 00 and FF specifying the intensity of the color.

<sp-color-field view-color value="#ff0000"></sp-color-field>
Shorthand HEX

Shorthand hexadecimal color values are also supported. #RGB is a shorthand for #RRGGBB. In the shorthand form, R (red), G (green), and B (blue) are hexadecimal characters between 0 and F. Each character is repeated to create the full 6-digit color code. For example, #123 would expand to #112233.

<sp-color-field view-color value="#f00"></sp-color-field>
RGB

An RGB color value is specified with: rgb(red, green, blue). Each parameter defines the intensity of the color with a value between 0 and 255.

<sp-color-field view-color value="rgb(255,0,0)"></sp-color-field>
RGBA

An RGBA color value is specified with: rgba(red, green, blue, alpha). The alpha parameter is a number between 0.0 (fully transparent) and 1.0 (fully opaque).

<sp-color-field view-color value="rgba(0,255,0,0.3)"></sp-color-field>
HSL

An HSL color value is specified with: hsl(hue, saturation, lightness). Hue is a degree on the color wheel from 0 to 360. 0 is red, 120 is green, and 240 is blue. Saturation and lightness are percentages.

<sp-color-field view-color value="hsl(234, 70%, 50%)"></sp-color-field>
HSV

An HSV color value is specified with: hsv(hue, saturation, value). Hue is a degree on the color wheel from 0 to 360. 0 is red, 120 is green, and 240 is blue. Saturation and value are percentages.

<sp-color-field view-color value="hsv(0, 70%, 50%)"></sp-color-field>

Events

Section titled Events

The <sp-color-field> component fires two types of events for color value changes:

  • input event: Fired when the value of the color-field has changed (fires on every keystroke)
  • change event: Fired when an alteration to the value of the color-field has been committed by the user (fires when the user finishes editing)

You can listen for these events to react to changes in the color value:

const colorField = document.querySelector('sp-color-field');

// Listen for real-time changes
colorField.addEventListener('input', (event) => {
    console.log('Color value changed:', event.target.value);
});

// Listen for committed changes
colorField.addEventListener('change', (event) => {
    console.log('Color value committed:', event.target.value);
});

Accessibility

Section titled Accessibility

The <sp-color-field> component provides comprehensive accessibility support:

Keyboard Navigation

Section titled Keyboard Navigation
  • Tab Navigation: The color field is keyboard accessible and can be navigated to using the Tab key
  • Input Validation: Invalid color values are clearly indicated to assistive technologies
  • Focus Management: Proper focus indicators are provided for keyboard users

Focus Management

Section titled Focus Management

The <sp-color-field> inherits comprehensive focus management capabilities from the TextfieldBase class:

  • Focus Element: The component automatically delegates focus to the underlying input element, ensuring proper keyboard navigation
  • Focus State Tracking: The component tracks focus state with the focused property, which is reflected as an attribute for styling
  • Focus Event Handling: Proper focus and blur event handling ensures accessibility compliance
  • Tab Index Management: Automatic tab index management ensures the component is properly included in the tab order
  • Focus Delegation: The component properly delegates focus to the underlying input element for keyboard navigation

Screen Reader Support

Section titled Screen Reader Support
  • ARIA Labels: The component uses appropriate ARIA attributes to describe its purpose and state
  • Value Announcements: Changes to the color value are announced to screen readers
  • Validation Feedback: Invalid input states are communicated to assistive technologies

Color Accessibility

Section titled Color Accessibility
  • Color Contrast: The component ensures sufficient contrast for text and visual elements
  • Color Independence: The component works effectively for users with color vision deficiencies
  • Alternative Input: Multiple color format support provides flexibility for different user needs

Best Practices

Section titled Best Practices
  • Provide Labels: Always include a descriptive label for the color field to provide context
  • Use View Color: Enable the view-color attribute to provide visual feedback alongside text input
  • Validate Input: Handle invalid color inputs gracefully and provide clear feedback to users

Changelog

Patch Changes

Section titled Patch Changes
  • Updated dependencies [cde976d]:
    • @spectrum-web-components/textfield@1.7.0
    • @spectrum-web-components/color-handle@1.7.0
    • @spectrum-web-components/base@1.7.0

1.6.0

Section titled 1.6.0

Patch Changes

Section titled Patch Changes
  • Updated dependencies [9e15a66]:
    • @spectrum-web-components/textfield@1.6.0
    • @spectrum-web-components/color-handle@1.6.0
    • @spectrum-web-components/base@1.6.0

1.5.0

Section titled 1.5.0

Minor Changes

Section titled Minor Changes
  • #5322 e19e55f Thanks @blunteshwar! - Fix Color Handle Positioning in Scrollable Containers

Patch Changes

Section titled Patch Changes
  • Updated dependencies [165a904]:
    • @spectrum-web-components/color-handle@1.5.0
    • @spectrum-web-components/textfield@1.5.0
    • @spectrum-web-components/base@1.5.0

1.4.0

Section titled 1.4.0

Minor Changes

Section titled Minor Changes
  • #5246 e247de9 Thanks @blunteshwar! - Alpha values for hex color formats wil be represented using hex instead of decimal

Patch Changes

Section titled Patch Changes
  • Updated dependencies []:
    • @spectrum-web-components/color-handle@1.4.0
    • @spectrum-web-components/textfield@1.4.0
    • @spectrum-web-components/base@1.4.0

1.3.0

Section titled 1.3.0

Patch Changes

Section titled Patch Changes
  • Updated dependencies []:
    • @spectrum-web-components/color-handle@1.3.0
    • @spectrum-web-components/textfield@1.3.0
    • @spectrum-web-components/base@1.3.0

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

1.2.0 (2025-02-27)

Section titled

Features

Section titled Features
  • reactive-controllers: Migrate to Colorjs from Tinycolor (#4713) (9d740f0)

1.1.2 (2025-02-12)

Section titled

Note: Version bump only for package @spectrum-web-components/color-field

1.1.1 (2025-01-29)

Section titled

Note: Version bump only for package @spectrum-web-components/color-field

1.1.0 (2025-01-29)

Section titled

Note: Version bump only for package @spectrum-web-components/color-field

1.0.3 (2024-12-09)

Section titled

Note: Version bump only for package @spectrum-web-components/color-field

1.0.1 (2024-11-11)

Section titled

Note: Version bump only for package @spectrum-web-components/color-field

1.0.0 (2024-10-31)

Section titled

Note: Version bump only for package @spectrum-web-components/color-field

0.49.0 (2024-10-15)

Section titled

Note: Version bump only for package @spectrum-web-components/color-field

0.48.1 (2024-10-01)

Section titled

Note: Version bump only for package @spectrum-web-components/color-field

0.48.0 (2024-09-17)

Section titled

Note: Version bump only for package @spectrum-web-components/color-field

0.47.2 (2024-09-03)

Section titled

Note: Version bump only for package @spectrum-web-components/color-field

0.47.1 (2024-08-27)

Section titled

Note: Version bump only for package @spectrum-web-components/color-field

0.47.0 (2024-08-20)

Section titled

Note: Version bump only for package @spectrum-web-components/color-field

0.46.0 (2024-08-08)

Section titled

Note: Version bump only for package @spectrum-web-components/color-field

0.45.0 (2024-07-30)

Section titled

Note: Version bump only for package @spectrum-web-components/color-field

0.44.0 (2024-07-15)

Section titled

Note: Version bump only for package @spectrum-web-components/color-field

0.43.0 (2024-06-11)

Section titled

Note: Version bump only for package @spectrum-web-components/color-field

0.42.5 (2024-05-24)

Section titled

Note: Version bump only for package @spectrum-web-components/color-field

0.42.4 (2024-05-14)

Section titled

Note: Version bump only for package @spectrum-web-components/color-field

0.42.3 (2024-05-01)

Section titled

Note: Version bump only for package @spectrum-web-components/color-field

0.42.2 (2024-04-03)

Section titled

Note: Version bump only for package @spectrum-web-components/color-field

0.42.1 (2024-04-02)

Section titled

Note: Version bump only for package @spectrum-web-components/color-field

0.42.0 (2024-03-19)

Section titled

Bug Fixes

Section titled Bug Fixes
  • color-field: added missing dependencies (#4141) (b3bb23a)

0.41.2 (2024-03-05)

Section titled

Bug Fixes

Section titled Bug Fixes
  • color-field: add color-field package (#3870) (5081634)

API

Attributes and Properties

Section titled Attributes and Properties
Property Attribute Type Default Description autocomplete autocomplete | 'list' | 'none' | HTMLInputElement['autocomplete'] | HTMLTextAreaElement['autocomplete'] | undefined What form of assistance should be provided when attempting to supply a value to the form control disabled disabled boolean false Disable this control. It will not receive focus or events grows grows boolean false Whether a form control delivered with the `multiline` attribute will change size vertically to accomodate longer input invalid invalid boolean false Whether the `value` held by the form control is invalid. label label string '' A string applied via `aria-label` to the form control when a user visible label is not provided. maxlength maxlength number -1 Defines the maximum string length that the user can enter minlength minlength number -1 Defines the minimum string length that the user can enter multiline multiline boolean false Whether the form control should accept a value longer than one line name name string | undefined Name of the form control. pattern pattern string | undefined Pattern the `value` must match to be valid placeholder placeholder string '' Text that appears in the form control when it has no value set quiet quiet boolean false Whether to display the form control with no visible background readonly readonly boolean false Whether a user can interact with the value of the form control required required boolean false Whether the form control will be found to be invalid when it holds no `value` rows rows number -1 The specific number of rows the form control should provide in the user interface tabIndex tabIndex number The tab index to apply to this control. See general documentation about the tabindex HTML property valid valid boolean false Whether the `value` held by the form control is valid. value value string | number The value held by the form control viewColor view-color boolean false

Events

Section titled Events
Name Type Description change Event An alteration to the value of the color-field has been committed by the user. input Event The value of the color-field has changed.