sp-color-handle

NPM 1.7.0

View Storybook
Overview API Changelog

Overview

The <sp-color-handle> is used to select a color on an <sp-color-area>, <sp-color-slider>, or <sp-color-wheel>. It provides a draggable control point for precise color selection within color components.

Usage

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

Note: <sp-color-handle> is a primitive component designed to be used within other color selection components. It's not typically used directly in applications, but rather as part of higher-level color components like <sp-color-area>, <sp-color-slider>, or <sp-color-wheel>.

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

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

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

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

import { ColorHandle } from '@spectrum-web-components/color-handle';

Anatomy

The color handle consists of several key parts:

  • A visual handle element that indicates the current position
  • Touch-responsive interaction areas
  • Color display showing the current selected color
  • Opacity checkerboard pattern for transparent colors
  • An optional sp-color-loupe that appears above the handle when the properties open = true and disabled = false
<sp-color-handle></sp-color-handle>

Options

Color

The color property sets the visual color displayed within the handle. This accepts any valid CSS color format. The default color is rgba(255, 0, 0, 0.5) (semi-transparent red).

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

Transparency Support: When using transparent colors, the handle displays an opacity checkerboard pattern background to clearly show the transparency level.

<div style="display: flex; gap: 16px; align-items: center; margin: 16px 0;">
    <!-- Hex color -->
    <div style="position: relative; height: 20px; margin: 20px;">
        <sp-color-handle color="#ff0000"></sp-color-handle>
    </div>

    <!-- RGB format -->
    <div style="position: relative; height: 20px; margin: 20px;">
        <sp-color-handle color="rgb(255, 0, 0)"></sp-color-handle>
    </div>

    <!-- RGBA format with transparency -->
    <div style="position: relative; height: 20px; margin: 20px;">
        <sp-color-handle color="rgba(255, 0, 0, 0.5)"></sp-color-handle>
    </div>

    <!-- HSL format -->
    <div style="position: relative; height: 20px; margin: 20px;">
        <sp-color-handle color="hsl(0, 100%, 50%)"></sp-color-handle>
    </div>

    <!-- Named colors -->
    <div style="position: relative; height: 20px; margin: 20px;">
        <sp-color-handle color="red"></sp-color-handle>
    </div>
</div>

States

Standard

The default state of the color handle, ready for interaction:

<sp-color-handle></sp-color-handle>

Disabled

A disabled color handle shows that the control exists but is not available for interaction. This maintains layout continuity and communicates that the handle may become available later:

<sp-color-handle disabled></sp-color-handle>

Open

When the open property is set, the <sp-color-loupe> component appears above the handle to show the selected color that would otherwise be covered by a mouse, stylus, or finger on the down/touch state. The loupe automatically appears for touch input (pointerType === 'touch').

<div style="height: 72px"></div>
<sp-color-handle open></sp-color-handle>

Automatic Behavior: The loupe automatically opens when touched and closes when the touch interaction ends. For mouse and stylus input, the loupe remains hidden by default unless explicitly set to open="true".

Focused

The color handle can receive keyboard focus when used within interactive color components. The focused state is managed automatically by the parent component and is indicated visually:

<sp-color-handle focused></sp-color-handle>

Behaviors

Pointer Interactions

The color handle automatically manages pointer events to provide the optimal user experience:

  • Touch Input: When touched (pointerType === 'touch'), the color loupe automatically appears to prevent the finger from obscuring the selected color
  • Mouse/Stylus Input: The loupe remains hidden by default for precision pointing devices
  • Pointer Capture: The handle captures pointer events during interaction to ensure smooth dragging even when the pointer moves outside the handle area
  • Event Handling: The component listens for pointerdown, pointerup, and pointercancel events to manage the interaction lifecycle

Color Display

The handle displays the current color with proper support for transparency:

  • Transparent colors are shown with an opacity checkerboard pattern background
  • The color updates in real-time as the user interacts with the parent color component
  • Supports all standard CSS color formats

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

Accessibility

The <sp-color-handle> is designed to work as part of accessible color selection components:

Keyboard Support

While the color handle itself is not directly keyboard accessible, it works in conjunction with its parent components (<sp-color-area>, <sp-color-slider>, <sp-color-wheel>) which provide comprehensive keyboard navigation. Example: Keyboard accessibility with sp-color-area as parent component

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

Screen Reader Support

The color handle is rendered as a visual indicator and does not directly interface with screen readers. Accessibility is provided through the parent color component's ARIA implementation.

Touch Accessibility

  • Color Loupe: Automatically appears for touch input to ensure the selected color remains visible
  • Large Touch Target: The handle provides an appropriately sized touch target for mobile interaction
  • Pointer Capture: Ensures reliable dragging behavior across different touch devices

Focus Management

Focus is managed by the parent color component, with the handle reflecting the focused state visually when its parent component has keyboard focus.

Attributes and Properties

Property Attribute Type Default Description color color string 'rgba(255, 0, 0, 0.5)' disabled disabled boolean false focused focused boolean false open open boolean false

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/color-loupe@1.7.0
    • @spectrum-web-components/base@1.7.0
    • @spectrum-web-components/opacity-checkerboard@1.7.0

1.6.0

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/color-loupe@1.6.0
    • @spectrum-web-components/base@1.6.0
    • @spectrum-web-components/opacity-checkerboard@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-loupe@1.5.0
    • @spectrum-web-components/base@1.5.0
    • @spectrum-web-components/opacity-checkerboard@1.5.0

1.4.0

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/color-loupe@1.4.0
    • @spectrum-web-components/base@1.4.0
    • @spectrum-web-components/opacity-checkerboard@1.4.0

1.3.0

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/color-loupe@1.3.0
    • @spectrum-web-components/base@1.3.0
    • @spectrum-web-components/opacity-checkerboard@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)

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

1.1.2 (2025-02-12)

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

1.1.1 (2025-01-29)

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

1.1.0 (2025-01-29)

Bug Fixes

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

1.0.1 (2024-11-11)

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

1.0.0 (2024-10-31)

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

0.49.0 (2024-10-15)

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

0.48.1 (2024-10-01)

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

0.48.0 (2024-09-17)

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

0.47.2 (2024-09-03)

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

0.47.1 (2024-08-27)

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

0.47.0 (2024-08-20)

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

0.46.0 (2024-08-08)

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

0.45.0 (2024-07-30)

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

0.44.0 (2024-07-15)

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

0.43.0 (2024-06-11)

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

0.42.5 (2024-05-24)

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

0.42.4 (2024-05-14)

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

0.42.3 (2024-05-01)

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

0.42.2 (2024-04-03)

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

0.42.1 (2024-04-02)

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

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

0.41.1 (2024-02-22)

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

0.41.0 (2024-02-13)

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

0.40.5 (2024-02-05)

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

0.40.4 (2024-01-29)

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

0.40.3 (2024-01-11)

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

0.40.2 (2023-12-18)

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

0.40.1 (2023-12-05)

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

0.40.0 (2023-11-16)

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

0.39.4 (2023-11-02)

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

0.39.3 (2023-10-18)

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

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

0.39.0 (2023-09-25)

Bug Fixes

  • color-handle,color-loupe,swatch,thumbnail: use the Opacity Checkerboard package (47e1fc4)

Features

  • color-slider: migrate to core tokens (#3507) (96d0d40)

0.38.0 (2023-09-05)

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

0.37.0 (2023-08-18)

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

0.36.0 (2023-08-18)

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

0.35.0 (2023-07-31)

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

0.34.0 (2023-07-11)

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

0.33.2 (2023-06-14)

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

0.33.0 (2023-06-08)

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

0.32.0 (2023-06-01)

Bug Fixes

  • color-handle,color-loupe: accept updated CSS token names (8c28f6d)

0.31.0 (2023-05-17)

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

0.30.0 (2023-05-03)

Bug Fixes

  • address westbrooks comments (634af60)
  • expand support for maintaining hue and saturation across customization (fe18944)
  • include touch-action rule for draggable content (3f507e6)
  • leverage Color Controller to unify color interface across packages (fb71690)
  • manage "focused" across more contexts (9273c15)
  • prevent focus outline (af2b077)

Features

  • adopt DNA@7 base Spectrum CSS (e08cafd)
  • color-handle: add color-handle pattern (e3856d8)
  • color-handle: use core tokens (e0c1468)
  • color-loupe: use core tokens (149165c)
  • include all Dev Mode files in side effects (f70817c)
  • shared pkg versions, devmode define warning, registry-conflicts docs (6e49565)

0.5.0 (2023-04-24)

Features

  • color-handle: use core tokens (e0c1468)
  • color-loupe: use core tokens (149165c)

0.4.9 (2023-04-05)

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

0.4.8 (2023-03-22)

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

0.4.7 (2023-02-08)

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

0.4.6 (2023-01-23)

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

0.4.5 (2023-01-09)

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

0.4.4 (2022-12-08)

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

0.4.3 (2022-11-21)

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

0.4.2 (2022-11-14)

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

0.4.1 (2022-10-10)

Bug Fixes

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

0.4.0 (2022-08-09)

Features

  • include all Dev Mode files in side effects (f70817c)

0.3.11 (2022-08-04)

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

0.3.10 (2022-07-18)

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

0.3.9 (2022-06-29)

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

0.3.8 (2022-06-07)

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

0.3.7 (2022-05-12)

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

0.3.6 (2022-04-21)

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

0.3.5 (2022-03-08)

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

0.3.4 (2022-03-04)

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

0.3.3 (2022-02-22)

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

0.3.2 (2022-01-26)

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

0.3.1 (2021-12-13)

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

0.3.0 (2021-11-08)

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

0.2.1 (2021-11-08)

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

0.2.0 (2021-11-02)

Features

  • adopt DNA@7 base Spectrum CSS (e08cafd)

0.1.10 (2021-10-12)

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

0.1.9 (2021-09-20)

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

0.1.8 (2021-09-13)

Bug Fixes

  • manage "focused" across more contexts (9273c15)
  • prevent focus outline (af2b077)

0.1.7 (2021-07-22)

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

0.1.6 (2021-07-01)

Bug Fixes

  • expand support for maintaining hue and saturation across customization (fe18944)

0.1.5 (2021-06-16)

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

0.1.4 (2021-05-12)

Bug Fixes

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

0.1.3 (2021-04-09)

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

0.1.2 (2021-03-29)

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

0.1.1 (2021-03-22)

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

0.1.0 (2021-03-05)

Bug Fixes

  • address westbrooks comments (634af60)

Features

  • color-handle: add color-handle pattern (e3856d8)