sp-color-area

NPM 1.7.0

View Storybook

Try it on Stackblitz

Overview

API

Changelog

Overview

An <sp-color-area> allows users to visually select two properties of a color simultaneously. It's commonly used together with a color slider or color wheel to create comprehensive color selection interfaces.

Usage

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

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

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

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

import { ColorArea } from '@spectrum-web-components/color-area';

Anatomy

The color area consists of several key parts:

A two-dimensional color selection area with visual gradients
A draggable handle that indicates the current color position
Accessible labels for the X and Y axes
Optional custom gradient slot for advanced styling

<sp-color-area></sp-color-area>

Custom Gradient

You can provide a custom gradient to replace the default color area appearance using the gradient slot:

<sp-color-area>
    <div slot="gradient" class="textured-gradient"></div>
</sp-color-area>

<style>
    .textured-gradient {
        width: 100%;
        height: 100%;
        background: 
        /* Subtle texture overlay */
            radial-gradient(
                circle at 20% 80%,
                rgba(255, 255, 255, 0.1) 0%,
                transparent 90%
            ),
            radial-gradient(
                circle at 80% 20%,
                rgba(0, 0, 0, 0.1) 0%,
                transparent 50%
            ),
            /* Standard HSV gradients */
                linear-gradient(to bottom, transparent 0%, black 100%),
            linear-gradient(to right, white 0%, transparent 100%),
            hsl(180, 100%, 50%);
    }
</style>

Options

Properties

The color area supports several properties for configuration:

Hue

Control the base hue of the color area (0-360 degrees):

<sp-color-area hue="240"></sp-color-area>

Color Values

The color area supports a wide variety of color formats for setting and getting color values:

<!-- Hex formats (3, 4, 6, or 8 digits) -->
<sp-color-area color="#f00"></sp-color-area>
<sp-color-area color="#f00f"></sp-color-area>
<sp-color-area color="#ff0000"></sp-color-area>
<sp-color-area color="#ff0000ff"></sp-color-area>

<!-- RGB/RGBA formats -->
<sp-color-area color="rgb(255, 0, 0)"></sp-color-area>
<sp-color-area color="rgba(255, 0, 0, 0.5)"></sp-color-area>
<sp-color-area color="rgb(100%, 0%, 0%)"></sp-color-area>
<sp-color-area color="rgb 255 0 0"></sp-color-area>

<!-- HSL/HSLA formats -->
<sp-color-area color="hsl(0, 100%, 50%)"></sp-color-area>
<sp-color-area color="hsla(0, 100%, 50%, 0.5)"></sp-color-area>
<sp-color-area color="hsl 0 100% 50%"></sp-color-area>

<!-- HSV/HSVA formats -->
<sp-color-area color="hsv(0, 100%, 100%)"></sp-color-area>
<sp-color-area color="hsva(0, 100%, 100%, 0.5)"></sp-color-area>
<sp-color-area color="hsv 0 100% 100%"></sp-color-area>

<!-- Named colors -->
<sp-color-area color="red"></sp-color-area>
<sp-color-area color="rebeccapurple"></sp-color-area>

When using the color elements, the color property will maintain the format you provided. For example, if you supply a color in rgb() format, el.color will return the color in rgb() format as well.

Step Size

The step attribute controls the granularity of color selection when using keyboard navigation. It defines the increment size (between 0 and 1) for each movement when using arrow keys or other keyboard controls.

<!-- Default step size is 0.01 (1% increments) -->
<sp-color-area></sp-color-area>

<!-- Larger step size for coarser adjustments (5% increments) -->
<sp-color-area step="0.05"></sp-color-area>

<!-- Smaller step size for finer precision (0.5% increments) -->
<sp-color-area step="0.005"></sp-color-area>

The step size affects:

Regular arrow key movements (moves by 1× step)
Shift+arrow key combinations (moves by 5× step)
Page Up/Page Down keys (moves by 10× step vertically)
Home/End keys (moves by 10× step horizontally)

A smaller step value provides more precise control but requires more key presses to move across the color area, while a larger step value allows for faster movement at the cost of precision. Choose a step size appropriate for your use case:

Fine-tuning: Use smaller values (0.001-0.01) for detailed color work
General use: The default (0.01) works well for most scenarios
Quick selection: Larger values (0.05-0.1) for faster navigation

Direction

The color area supports both left-to-right and right-to-left layouts:

<sp-color-area dir="rtl"></sp-color-area>

Custom Sizing

An <sp-color-area>'s height and width can be customized appropriately for its context.

<sp-color-area
    style="
        width: 72px; 
        height: 72px"
></sp-color-area>

States

Disabled

An <sp-color-area> in a disabled state shows that an input exists, but is not available in that circumstance. This can be used to maintain layout continuity and communicate that the area may become available later.

<sp-color-area disabled></sp-color-area>

Focused

The color area manages its focused state automatically, but you can also check the focused state programmatically:

const colorArea = document.querySelector('sp-color-area');
console.log(colorArea.focused); // true or false

Behaviors

Color Formatting

When using the color elements, use el.color to access the color property, which should manage itself in the colour format supplied. For example, If you supply a color in rgb() format, el.color should return the color in rgb() format, as well. In ColorArea, colours are formatted as hex values.

The current color formats supported are as follows:

Hex3, Hex4, Hex6, Hex8
HSV, HSVA
HSL, HSLA
RGB, RGBA
Named color strings (see full list)

Pointer Interactions

The color area supports both mouse and touch interactions:

Click: Jump to a specific color position
Drag: Continuously adjust color while dragging
Touch: Full touch support for mobile devices

<sp-color-area @pointerdown="${(event)" =""></sp-color-area>

Focus Management

The color area automatically manages focus between its internal X and Y axis controls:

Accessibility

The <sp-color-area> is rendered with appropriate ARIA attributes to ensure accessibility for screen readers and keyboard navigation.

Accessible Labels

An <sp-color-area> renders accessible labels for each axis: "saturation" and "luminosity". Specify label-x and label-y attributes to override these defaults.

<sp-color-area
    label-x="Color intensity"
    label-y="Color brightness"
></sp-color-area>

Keyboard Navigation

The color area supports comprehensive keyboard interaction for precise color selection:

Key

Action

Arrow Keys

Move the color selection by one step

Shift + Arrow Keys

Move the color selection by a larger step (5x)

Page Up/Page Down

Move vertically by a large step (10x)

Home/End

Move horizontally by a large step (10x)

ARIA Attributes

The component provides comprehensive ARIA support with different behavior for mobile and desktop:

Role: Uses native input[type="range"] elements with implicit "slider" roles for 2D color selection
Role Description: Announces as "2d slider" on desktop devices (omitted on mobile for better touch screen reader experience)
Labels:
- Mobile: Simple axis labels (e.g., "saturation", "luminosity")
- Desktop: Combined labels (e.g., "saturation Color Picker", "luminosity Color Picker")
Orientation: Explicitly set as "horizontal" for X-axis and "vertical" for Y-axis
Value Text: Internationalized percentage values
- Mobile: Single axis value (e.g., "45%")
- Desktop: Comprehensive context including both axes (e.g., "45%, saturation, 78%, luminosity")
Fieldset: Contains both sliders with appropriate labeling for mobile screen readers
Presentation: Wrapper divs marked with role="presentation" to avoid navigation confusion

The component provides comprehensive screen reader support through:

Internationalized Values: Percentage values are formatted according to the user's locale using Intl.NumberFormat
Context-Aware Announcements: Different announcement patterns for focus changes vs. value changes
Focused State Management: Special handling to prevent focus traps and ensure proper screen reader navigation
Shadow DOM Optimization: Dynamically creates shadow roots when focused to prevent duplicate tab stops in certain browsers
Keyboard Focus Tracking: Maintains the active axis (X or Y) to ensure consistent focus when navigating with a screen reader
Value Change Context: When values change, announces only the changed value; when focused, announces both axes for context

Mobile Accessibility

The component implements specific optimizations for mobile devices (Android and iOS):

Platform Detection: Uses isAndroid() and isIOS() to apply platform-specific behaviors
Simplified ARIA: Provides more concise labels and values on mobile to improve screen reader experience
Touch Pointer Events: Special handling for touch interactions vs. mouse interactions
Mobile Focus States: Different focus handling for touch vs. mouse input
Fieldset Labeling: Adds an explicit aria-label="Color Picker" to the fieldset only on mobile
Omitted Role Description: Removes the "2d slider" role description on mobile for better compatibility with mobile screen readers
Simplified Value Text: Announces only the current axis value without additional context to reduce verbosity on mobile

Attributes and Properties

Property

Attribute

Type

Default

Description

color

ColorTypes

disabled

boolean

false

focused

boolean

false

hue

number

labelX

label-x

string

'saturation'

labelY

label-y

string

'luminosity'

step

number

0.01

value

ColorTypes

x

number

y

number

Slots

Name

Description

gradient

a custom gradient visually outlining the available color values

Events

Name

Type

Description

change

Event

An alteration to the value of the Color Area has been committed by the user.

input

Event

The value of the Color Area has changed.

Patch Changes

Updated dependencies []:
- @spectrum-web-components/color-handle@1.7.0
- @spectrum-web-components/base@1.7.0
- @spectrum-web-components/opacity-checkerboard@1.7.0
- @spectrum-web-components/reactive-controllers@1.7.0
- @spectrum-web-components/shared@1.7.0

1.6.0

Patch Changes

Updated dependencies []:
- @spectrum-web-components/color-handle@1.6.0
- @spectrum-web-components/base@1.6.0
- @spectrum-web-components/opacity-checkerboard@1.6.0
- @spectrum-web-components/reactive-controllers@1.6.0
- @spectrum-web-components/shared@1.6.0

1.5.0

Patch Changes

#5271 165a904 Thanks @renovate! - Remove unnecessary system theme references to reduce complexity for components that don't need the additional mapping layer.
Updated dependencies [165a904]:
- @spectrum-web-components/color-handle@1.5.0
- @spectrum-web-components/base@1.5.0
- @spectrum-web-components/opacity-checkerboard@1.5.0
- @spectrum-web-components/reactive-controllers@1.5.0
- @spectrum-web-components/shared@1.5.0

1.4.0

Patch Changes

Updated dependencies []:
- @spectrum-web-components/color-handle@1.4.0
- @spectrum-web-components/base@1.4.0
- @spectrum-web-components/opacity-checkerboard@1.4.0
- @spectrum-web-components/reactive-controllers@1.4.0
- @spectrum-web-components/shared@1.4.0

1.3.0

Patch Changes

Updated dependencies [ea38ef0]:
- @spectrum-web-components/reactive-controllers@1.3.0
- @spectrum-web-components/color-handle@1.3.0
- @spectrum-web-components/base@1.3.0
- @spectrum-web-components/opacity-checkerboard@1.3.0
- @spectrum-web-components/shared@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)

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-area

1.1.1 (2025-01-29)

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

1.1.0 (2025-01-29)

Bug Fixes

lock prerelease versions for Spectrum CSS (#5014) (8aa7734)

1.0.3 (2024-12-09)

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

1.0.1 (2024-11-11)

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

1.0.0 (2024-10-31)

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

0.49.0 (2024-10-15)

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

0.48.1 (2024-10-01)

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

0.48.0 (2024-09-17)

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

0.47.2 (2024-09-03)

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

0.47.1 (2024-08-27)

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

0.47.0 (2024-08-20)

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

0.46.0 (2024-08-08)

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

0.45.0 (2024-07-30)

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

0.44.0 (2024-07-15)

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

0.43.0 (2024-06-11)

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

0.42.5 (2024-05-24)

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

0.42.4 (2024-05-14)

Bug Fixes

color-area: providing x and y attributes renders color handle correctly (#4240) (9eb5056)

0.42.3 (2024-05-01)

Bug Fixes

color-area: providing x and y attributes renders color handle correctly (#4240) (9eb5056)

0.42.2 (2024-04-03)

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

0.42.1 (2024-04-02)

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

0.42.0 (2024-03-19)

Features

asset: use core tokens (99e76f4)

0.41.2 (2024-03-05)

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

0.41.1 (2024-02-22)

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

0.41.0 (2024-02-13)

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

0.40.5 (2024-02-05)

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

0.40.4 (2024-01-29)

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

0.40.3 (2024-01-11)

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

0.40.2 (2023-12-18)

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

0.40.1 (2023-12-05)

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

0.40.0 (2023-11-16)

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

0.39.4 (2023-11-02)

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

0.39.3 (2023-10-18)

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

0.39.2 (2023-10-13)

Bug Fixes

update deps graph, update link docs (#3709) (2deb284)

0.39.1 (2023-10-06)

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

0.39.0 (2023-09-25)

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

0.38.0 (2023-09-05)

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

0.37.0 (2023-08-18)

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

0.36.0 (2023-08-18)

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

0.35.0 (2023-07-31)

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

0.34.0 (2023-07-11)

Bug Fixes

color-area,color-slider: color-area labeling, RTL support, vertical slider orientation(#3315) (ca2acda), closes #3313

0.33.2 (2023-06-14)

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

0.33.0 (2023-06-08)

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

0.32.0 (2023-06-01)

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

0.31.0 (2023-05-17)

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

0.30.0 (2023-05-03)

Bug Fixes

abstract "hasVisibleFocusInTree" functionality and return trigger focus after close (4f39f2c)
address westbrooks comments (634af60)
color-area: fix hue value for hsv and hsl (a66e111)
color-area: up and down arrows now work properly (44b9f74)
ensure streamingListener ends even if pointercancel not fired (74105f2)
expand support for maintaining hue and saturation across customization (fe18944)
flappy Slider/Color Area tests (c769c87)
include touch-action rule for draggable content (3f507e6)
key interaction handling no longer prevents "tab" presses (b542ce8)
leverage Color Controller to unify color interface across packages (fb71690)
lint away debugger statements (34a498e)
manage "focused" across more contexts (9273c15)
normalize focus passing during and after pointer events (357931b)
overlay: allow overlay-trigger to declaratively open overlay content (194a44e)
remove right click value setting (a44968d)
update package.json (455b626)
use hue normalized color in handle and allow focus (f9e1fa2)

Features

adopt DNA@7 base Spectrum CSS (e08cafd)
color-area: add color-area pattern (dc15e1c)
color-area: separate X and Y aria labels to improve accessibility (e8d9768)
color-area: use core tokens (51a89de)
debug colour elements for a11y (7008f7c)
include all Dev Mode files in side effects (f70817c)
shared pkg versions, devmode define warning, registry-conflicts docs (6e49565)
update lit-* dependencies, wip (377f3c8)

0.6.2 (2023-04-24)

Bug Fixes

ensure streamingListener ends even if pointercancel not fired (74105f2)

0.6.1 (2023-04-05)

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

0.6.0 (2023-03-22)

Features

color-area: use core tokens (51a89de)

0.5.8 (2023-02-08)

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

0.5.7 (2023-01-23)

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

0.5.6 (2023-01-09)

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

0.5.5 (2022-12-08)

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

0.5.4 (2022-11-21)

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

0.5.3 (2022-11-14)

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

0.5.2 (2022-10-28)

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

0.5.1 (2022-10-10)

Bug Fixes

leverage Color Controller to unify color interface across packages (fb71690)

0.5.0 (2022-08-09)

Features

include all Dev Mode files in side effects (f70817c)

0.4.11 (2022-08-04)

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

0.4.10 (2022-07-18)

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

0.4.9 (2022-06-29)

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

0.4.8 (2022-06-07)

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

0.4.7 (2022-05-12)

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

0.4.6 (2022-04-21)

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

0.4.5 (2022-03-08)

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

0.4.4 (2022-03-04)

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

0.4.3 (2022-02-22)

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

0.4.2 (2022-01-26)

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

0.4.1 (2021-12-13)

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

0.4.0 (2021-11-08)

Features

update lit-* dependencies, wip (377f3c8)

0.3.1 (2021-11-08)

Bug Fixes

abstract "hasVisibleFocusInTree" functionality and return trigger focus after close (4f39f2c)

0.3.0 (2021-11-02)

Features

adopt DNA@7 base Spectrum CSS (e08cafd)

0.2.1 (2021-10-12)

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

0.2.0 (2021-09-20)

Features

color-area: separate X and Y aria labels to improve accessibility (e8d9768)

0.1.12 (2021-09-13)

Bug Fixes

flappy Slider/Color Area tests (c769c87)
manage "focused" across more contexts (9273c15)

0.1.11 (2021-08-24)

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

0.1.10 (2021-08-17)

Bug Fixes

key interaction handling no longer prevents "tab" presses (b542ce8)

0.1.9 (2021-08-03)

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

0.1.8 (2021-07-22)

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

0.1.7 (2021-07-01)

Bug Fixes

expand support for maintaining hue and saturation across customization (fe18944)
normalize focus passing during and after pointer events (357931b)

0.1.6 (2021-06-16)

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

0.1.5 (2021-06-07)

Bug Fixes

lint away debugger statements (34a498e)
color-area: fix hue value for hsv and hsl (a66e111)

0.1.4 (2021-05-12)

Bug Fixes

include touch-action rule for draggable content (3f507e6)

0.1.3 (2021-04-09)

Bug Fixes

use hue normalized color in handle and allow focus (f9e1fa2)

0.1.2 (2021-03-29)

Bug Fixes

color-area: up and down arrows now work properly (44b9f74)

0.1.1 (2021-03-22)

Bug Fixes

overlay: allow overlay-trigger to declaratively open overlay content (194a44e)
remove right click value setting (a44968d)

0.1.0 (2021-03-05)

Bug Fixes

address westbrooks comments (634af60)
update package.json (455b626)

Features

debug colour elements for a11y (7008f7c)
color-area: add color-area pattern (dc15e1c)

Spectrum Web Components

sp-color-area

Overview

Usage

Anatomy

Custom Gradient

Options

Properties

Hue

Color Values

Step Size

Direction

Custom Sizing

States

Disabled

Focused

Behaviors

Color Formatting

Pointer Interactions

Focus Management

Accessibility

Accessible Labels

Keyboard Navigation

ARIA Attributes

Screen Reader Support

Mobile Accessibility

API

Attributes and Properties

Slots

Events

Changelog

Patch Changes

1.6.0

Patch Changes

1.5.0

Patch Changes

1.4.0

Patch Changes

1.3.0

Patch Changes

1.2.0 (2025-02-27)

Features

1.1.2 (2025-02-12)

1.1.1 (2025-01-29)

1.1.0 (2025-01-29)

Bug Fixes

1.0.3 (2024-12-09)

1.0.1 (2024-11-11)

1.0.0 (2024-10-31)

0.49.0 (2024-10-15)

0.48.1 (2024-10-01)

0.48.0 (2024-09-17)

0.47.2 (2024-09-03)

0.47.1 (2024-08-27)

0.47.0 (2024-08-20)

0.46.0 (2024-08-08)

0.45.0 (2024-07-30)

0.44.0 (2024-07-15)

0.43.0 (2024-06-11)

0.42.5 (2024-05-24)

0.42.4 (2024-05-14)

Bug Fixes

0.42.3 (2024-05-01)

Bug Fixes

0.42.2 (2024-04-03)

0.42.1 (2024-04-02)

0.42.0 (2024-03-19)

Features

0.41.2 (2024-03-05)

0.41.1 (2024-02-22)

0.41.0 (2024-02-13)

0.40.5 (2024-02-05)

0.40.4 (2024-01-29)

0.40.3 (2024-01-11)

0.40.2 (2023-12-18)

0.40.1 (2023-12-05)

0.40.0 (2023-11-16)

0.39.4 (2023-11-02)

0.39.3 (2023-10-18)

0.39.2 (2023-10-13)

Spectrum
Web Components