@spectrum-web-components/color-handle

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

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.

Changelog

1.8.0 (2025-09-23)

Minor Changes

sp-picker: Fixed escape key behavior in modal overlays containing picker components. Previously, pressing the Escape key when a picker was open inside a modal overlay would not properly close the modal, instead moving focus to the picker. Now, the escape key correctly closes the picker first (if open), then closes the modal overlay on subsequent escape key presses.

This fix adds a check for this.open in the picker's handleEscape method to ensure proper modal overlay closure behavior.

sp-overlay: Added allow-outside-click property to <sp-overlay> with deprecation notice. This property allows clicks outside the overlay to close it, but is not recommended for accessibility reasons and will be removed in a future version.

This property is being added as deprecated to support the fallback for showModal() which was removed as part of performance optimization. We will no longer support outside clicks for modal overlays as they violate accessibility guidelines.

The property defaults to false and shows deprecation warnings when used. Consider using explicit close buttons or modal/page overlay types instead for better accessibility.

sp-menu: Fixed : Fix iPad scrolling issue in picker dropdown where scrolling through menu items would accidentally select the first touched item and close the picker.

The fix implements touch gesture detection to distinguish between scrolling and selection. Added isScrolling getter for public API access. Test on iPad devices with long menus to validate scrolling behavior and selection accuracy.

sp-overlay: Fixed : Added body scroll prevention for modal and page overlays. Overlay automatically blocks body scroll when modal or page overlays are open and restores the original scroll state when they are closed, improving user experience and accessibility for modal dialogs.

sp-clear-button: Clear button styles have been updated to the latest Spectrum CSS version of the clear button. This update includes a major reduction in the number of custom property abstractions needed to support the multiple theming layers (as seen in the styles package).

This update spans the following additional packages:

• @spectrum-web-components/button
• @spectrum-web-components/styles

As the updated styles now offer additional styling options, we have added the following API to the clear button component that exists in the button package:

• quiet - when set to true, the button will be rendered as a quiet button. This is useful for cases where you want to use the clear button in a more subtle way.
• disabled - when set to true, the button will be rendered as a disabled button.
• static-color - currently this only supports the white context color. This is useful for cases where the button appears on a dark background texture. This is a replacement for the previously used variant="overBackground" attribute which is deprecated.

Deprecation

The variant="overBackground" attribute is deprecated; please use the new static-color="white" attribute instead. When this property is used in the component, a deprecation warning will be shown in the console when in debug mode. The variant attribute will be removed in a future release.

sp-card: Fixed the card component's CSS by moving block-size: 100% from the base :host selector to only apply to gallery and quiet variants

sp-overlay: Fixed : external click registration behavior in the sp-overlay component. Programmatic clicks on elements outside of modal overlays now properly register and close the overlay, while user-initiated clicks are prevented from doing so.

sp-card: Enhanced the Card component's checkbox functionality with improved screen reader support and keyboard navigation.

Patch Changes

sp-progress-bar: Added: Deprecation warning for the over-background attribute.

sp-combobox: Replace the use of offsetWidth with a resizeObserver to avoid unecessary, performance-impacting layout reflows.

sp-styles: Bring the CJK font alias token fix from CSS #3883 4e3a120.

The --spectrum-cjk-font token was incorrectly mapped to the code font-family stack instead of --spectrum-cjk-font-family-stack. Thanks @byteakp!

sp-color-wheel: Fixed <sp-color-wheel> step attribute functionality for keyboard navigation. The step attribute now properly controls the increment size when using arrow keys to navigate the color wheel.

sp-switch: ### Fix down state colors for switch

Because the postcss-hover-media-feature plugin converts hover styles into a media query for devices that support hover, the hover styles were overriding any active/down state styles. We needed to target the active/down states of the switch with additional active state selectors, in order to ensure that the active state takes precedence over the hover state, maintaining the correct visual behavior of the switch component across different interaction states.

This fix should address hover + active state discrepancies in S1 and S2 foundations.

sp-contextual-help: Fixed a typo in the default info variant label from "Informations" to "Information".

Additionally, added package dependency for @spectrum-web-components/reactive-controllers@1.7.0.

sp-slider: Editable sliders will now reliably emit input events when interaction starts with the track.

sp-link: Fixed quiet variant links not showing keyboard focus state in Safari. Links with the quiet attribute now properly display focus indicators when navigating with keyboard, improving accessibility for keyboard users.

sp-progress-bar: Smooths the transition animation of indeterminate progress bar by overriding the incoming CSS, and positioning the animating fill element completely off of the progress bar track in both LTR and RTL languages. Before, the fill element was automatically starting on the track which led to a jarring animation loop.

sp-divider: Added: staticColor property to the Divider component, enabling programmatic control of the existing static color functionality.