sp-color-field
NPM 1.7.0
View Storybook
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
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
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
Sizes
<sp-color-field size="s" value="#ffff00"></sp-color-field>
<sp-color-field size="m" value="#ffff00"></sp-color-field>
<sp-color-field size="l" value="#ffff00"></sp-color-field>
<sp-color-field size="xl" value="#ffff00"></sp-color-field>
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
A quiet color field provides a more subtle appearance:
<sp-color-field quiet value="#e6e600"></sp-color-field>
States
Standard
The default state of the color field, ready for user input:
<sp-color-field value="#ffff00"></sp-color-field>
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
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
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
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 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>
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>
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>
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>
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
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
The <sp-color-field>
component provides comprehensive accessibility support:
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
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
- 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
- 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
- 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
- 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
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
Minor Changes
#5322 Thankse19e55f
@blunteshwar ! - Fix Color Handle Positioning in Scrollable Containers
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
Minor Changes
#5246 Thankse247de9
@blunteshwar ! - Alpha values for hex color formats wil be represented using hex instead of decimal
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
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
1.2.0 (2025-02-27)
Features
- reactive-controllers: Migrate to Colorjs from Tinycolor (
#4713 ) (9d740f0 )
1.1.2 (2025-02-12)
Note: Version bump only for package @spectrum-web-components/color-field
1.1.1 (2025-01-29)
Note: Version bump only for package @spectrum-web-components/color-field
1.1.0 (2025-01-29)
Note: Version bump only for package @spectrum-web-components/color-field
1.0.3 (2024-12-09)
Note: Version bump only for package @spectrum-web-components/color-field
1.0.1 (2024-11-11)
Note: Version bump only for package @spectrum-web-components/color-field
1.0.0 (2024-10-31)
Note: Version bump only for package @spectrum-web-components/color-field
0.49.0 (2024-10-15)
Note: Version bump only for package @spectrum-web-components/color-field
0.48.1 (2024-10-01)
Note: Version bump only for package @spectrum-web-components/color-field
0.48.0 (2024-09-17)
Note: Version bump only for package @spectrum-web-components/color-field
0.47.2 (2024-09-03)
Note: Version bump only for package @spectrum-web-components/color-field
0.47.1 (2024-08-27)
Note: Version bump only for package @spectrum-web-components/color-field
0.47.0 (2024-08-20)
Note: Version bump only for package @spectrum-web-components/color-field
0.46.0 (2024-08-08)
Note: Version bump only for package @spectrum-web-components/color-field
0.45.0 (2024-07-30)
Note: Version bump only for package @spectrum-web-components/color-field
0.44.0 (2024-07-15)
Note: Version bump only for package @spectrum-web-components/color-field
0.43.0 (2024-06-11)
Note: Version bump only for package @spectrum-web-components/color-field
0.42.5 (2024-05-24)
Note: Version bump only for package @spectrum-web-components/color-field
0.42.4 (2024-05-14)
Note: Version bump only for package @spectrum-web-components/color-field
0.42.3 (2024-05-01)
Note: Version bump only for package @spectrum-web-components/color-field
0.42.2 (2024-04-03)
Note: Version bump only for package @spectrum-web-components/color-field
0.42.1 (2024-04-02)
Note: Version bump only for package @spectrum-web-components/color-field
0.42.0 (2024-03-19)
Bug Fixes
- color-field: added missing dependencies (
#4141 ) (b3bb23a )
0.41.2 (2024-03-05)
Bug Fixes
- color-field: add color-field package (
#3870 ) (5081634 )
API
Attributes and Properties
autocomplete
autocomplete
| 'list' | 'none' | HTMLInputElement['autocomplete'] | HTMLTextAreaElement['autocomplete'] | undefined
disabled
disabled
boolean
false
grows
grows
boolean
false
invalid
invalid
boolean
false
label
label
string
''
maxlength
maxlength
number
-1
minlength
minlength
number
-1
multiline
multiline
boolean
false
name
name
string | undefined
pattern
pattern
string | undefined
placeholder
placeholder
string
''
quiet
quiet
boolean
false
readonly
readonly
boolean
false
required
required
boolean
false
rows
rows
number
-1
tabIndex
tabIndex
number
valid
valid
boolean
false
value
value
string | number
viewColor
view-color
boolean
false
Events
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.