sp-color-wheel

NPM 1.7.0

View Storybook

Try it on Stackblitz
Overview API Changelog

Overview

An <sp-color-wheel> allows users to visually select the hue of a color on a circular track. It's commonly used together with other color components to create comprehensive color selection interfaces.

Usage

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

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

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

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

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

import { ColorWheel } from '@spectrum-web-components/color-wheel';

Anatomy

The color wheel consists of several key parts:

  • A circular track displaying the full spectrum of hues
  • A draggable handle that indicates the current hue selection
  • Accessible labels for screen readers
  • Optional custom gradient slot for advanced styling
<sp-color-wheel></sp-color-wheel>

Custom Gradient

⚠️ Deprecated Feature

The custom gradient functionality has been deprecated and is no longer supported. While the gradient slot may still be present in the component's code, it is broken and will not work as intended.

If you previously relied on custom gradients for the color wheel, you should:

  • Use the default color wheel appearance
  • Consider alternative approaches for custom styling
  • Remove any existing custom gradient implementations

Note: Even if you find the gradient slot in the component's source code, this feature is non-functional and should not be used in new implementations.

Options

Properties

The color wheel supports several properties for configuration:

Value (Hue)

The value property controls the hue angle of the color wheel (0-360 degrees). This represents the position of the handle on the circular track and determines the hue component of the displayed color.

<sp-color-wheel value="180"></sp-color-wheel>
Color Values

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

<div style="display: flex; gap: 16px;">
    <sp-color-wheel color="#7277b5"></sp-color-wheel>
    <sp-color-wheel color="hsl(96, 84.00%, 49.00%)"></sp-color-wheel>
    <sp-color-wheel color="red"></sp-color-wheel>
</div>
 Format Example Values Description Hex3 #f00, #0a5 3-digit hexadecimal Hex4 #f00f, #0a58 3-digit hexadecimal + alpha Hex6 #ff0000, #00aa55 6-digit hexadecimal Hex8 #ff0000ff, #00aa5580 6-digit hexadecimal + alpha RGB rgb(255, 0, 0), rgb(0, 170, 85) Red, Green, Blue values (0-255) RGBA rgba(255, 0, 0, 1), rgba(0, 170, 85, 0.5) RGB + Alpha channel (0-1) HSL hsl(0, 100%, 50%), hsl(150, 100%, 33%) Hue (0-360°), Saturation, Lightness HSLA hsla(0, 100%, 50%, 1), hsla(150, 100%, 33%, 0.5) HSL + Alpha channel (0-1) HSV hsv(0, 100%, 100%), hsv(150, 100%, 67%) Hue (0-360°), Saturation, Value HSVA hsva(0, 100%, 100%, 1), hsva(150, 100%, 67%, 0.5) HSV + Alpha channel (0-1) Named Colors red, rebeccapurple, darkseagreen CSS color keywords (full list)
Step Size

The step attribute controls the increment of hue adjustment when using keyboard navigation. It defines how many degrees the hue changes with each arrow key press:

<div style="display: flex; gap: 16px;">
    <sp-color-wheel step="1" label="Fine Control (1° per key)"></sp-color-wheel>
    <sp-color-wheel
        step="10"
        label="Medium Control (10° per key)"
    ></sp-color-wheel>
    <sp-color-wheel
        step="45"
        label="Coarse Control (45° per key)"
    ></sp-color-wheel>
</div>

The step size affects keyboard navigation:

  • Regular arrow keys move by the step value
  • Shift + arrow keys move by 10× the step value
  • Choose your step size based on your use case:
    • step="1": Precise color selection, best for professional design tools
    • step="10": Balanced control, good for general use
    • step="45": Quick selection between major hues, ideal for simple color pickers
Label

Provide a custom aria-label for accessibility:

<sp-color-wheel label="Select color hue"></sp-color-wheel>
Direction

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

<sp-color-wheel dir="rtl"></sp-color-wheel>
Tab Index

The tabIndex property controls the tab order of the color wheel within the page. This follows the standard HTML tabindex attribute behavior:

<div style="display: flex; gap: 16px;">
    <div style="text-align: center;">
        <div style="font-weight: bold; margin-bottom: 8px;">
            Default Tab Order
        </div>
        <sp-color-wheel></sp-color-wheel>
    </div>
    <div style="text-align: center;">
        <div style="font-weight: bold; margin-bottom: 8px;">
            Skip in Tab Order
        </div>
        <sp-color-wheel tabindex="-1"></sp-color-wheel>
    </div>
    <div style="text-align: center;">
        <div style="font-weight: bold; margin-bottom: 8px;">
            Custom Tab Order
        </div>
        <sp-color-wheel tabindex="5"></sp-color-wheel>
    </div>
</div>

Note: See the general documentation about the HTML tabindex property for detailed information about tab order behavior.

Custom Sizing

An <sp-color-wheel>'s size can be customized appropriately for its context. By default, the size is 192 px.

Using Inline Styles

You can set custom dimensions using inline styles. For a perfect circle, ensure width and height are the same:

<sp-color-wheel style="width: 300px; height: 300px;"></sp-color-wheel>
Using Mod Tokens

The component exposes CSS custom properties for consistent theming. Both --mod-colorwheel-width and --mod-colorwheel-height should be set to the same value to maintain a perfect circle:

<sp-color-wheel
    style="--mod-colorwheel-width: 250px; --mod-colorwheel-height: 250px;"
></sp-color-wheel>

Note: The CSS internally reuses the width value for both dimensions, but both mod tokens are exposed for flexibility in custom implementations.

States

Disabled

A color wheel 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 wheel may become available later.

<sp-color-wheel disabled></sp-color-wheel>

Focused

The color wheel manages its focused state automatically, providing visual feedback during keyboard navigation:

<sp-color-wheel focused></sp-color-wheel>

Behaviors

Color Formatting

When using the color elements, use el.color to access the color property, which should manage itself in the color format supplied. If you supply a color in rgb() format, el.color should return the color in rgb() format, as well.

Please note for the following formats: HSV, HSVA, HSL, HSLA When using the HSL or HSV formats, and a color's value (in HSV) is set to 0, or its luminosity (in HSL) is set to 0 or 1, the hue and saturation values may not be preserved by the element's color property. This is detailed in the colorjs documentation. Separately, the element's value property is directly managed by the hue as represented in the interface.

Pointer Interactions

The color wheel supports both mouse and touch interactions:

  • Click: Jump to a specific hue on the wheel
  • Drag: Continuously adjust hue while dragging around the wheel
  • Touch: Full touch support for mobile devices

Focus Management

The color wheel automatically manages focus for keyboard accessibility, ensuring proper focus indication and keyboard operability.

Accessibility

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

Keyboard Navigation

The color wheel supports comprehensive keyboard interaction:

Key Action Arrow Left/Arrow Right Decrease/Increase hue by step value (respects RTL) Arrow Up/Arrow Down Increase/Decrease hue by step value Shift + Arrow Keys Adjust hue by larger increments (10× step)

ARIA Attributes

The component provides comprehensive ARIA support:

  • Role: Uses native input[type="range"] with implicit "slider" role
  • Label: Customizable via the label property (defaults to "hue")
  • Value Text: Announces the current hue value in degrees with proper internationalization
  • Orientation: Implicitly circular, supporting both LTR and RTL layouts

Screen Reader Support

The component provides meaningful announcements for assistive technologies:

  • Current hue value announced in degrees (e.g., "180 degrees")
  • Internationalized number formatting based on user's locale
  • Clear indication of the control's purpose through proper labeling

Mobile Accessibility

The color wheel is fully accessible on mobile devices with:

  • Touch-friendly interaction areas
  • Proper focus management for mobile screen readers

Attributes and Properties

Property Attribute Type Default Description color color ColorTypes disabled disabled boolean false Disable this control. It will not receive focus or events focused focused boolean false label label string 'hue' step step number 1 tabIndex tabIndex number The tab index to apply to this control. See general documentation about the tabindex HTML property value value 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 Wheel has been committed by the user. input Event The value of the Color Wheel has changed.

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/color-handle@1.7.0
    • @spectrum-web-components/base@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/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/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/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/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-wheel

1.1.1 (2025-01-29)

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

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

1.0.1 (2024-11-11)

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

1.0.0 (2024-10-31)

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

0.49.0 (2024-10-15)

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

0.48.1 (2024-10-01)

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

0.48.0 (2024-09-17)

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

0.47.2 (2024-09-03)

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

0.47.1 (2024-08-27)

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

0.47.0 (2024-08-20)

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

0.46.0 (2024-08-08)

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

0.45.0 (2024-07-30)

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

0.44.0 (2024-07-15)

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

0.43.0 (2024-06-11)

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

0.42.5 (2024-05-24)

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

0.42.4 (2024-05-14)

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

0.42.3 (2024-05-01)

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

0.42.2 (2024-04-03)

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

0.42.1 (2024-04-02)

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

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

0.41.1 (2024-02-22)

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

0.41.0 (2024-02-13)

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

0.40.5 (2024-02-05)

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

0.40.4 (2024-01-29)

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

0.40.3 (2024-01-11)

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

0.40.2 (2023-12-18)

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

0.40.1 (2023-12-05)

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

0.40.0 (2023-11-16)

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

0.39.4 (2023-11-02)

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

0.39.3 (2023-10-18)

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

0.39.2 (2023-10-13)

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

0.39.1 (2023-10-06)

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

0.39.0 (2023-09-25)

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

0.38.0 (2023-09-05)

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

0.37.0 (2023-08-18)

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

0.36.0 (2023-08-18)

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

0.35.0 (2023-07-31)

Bug Fixes

  • color-wheel: reorient reactively to "dir" changes (#3319) (6a9dcec)

0.34.0 (2023-07-11)

Bug Fixes

  • color-area,color-slider: color-area labeling, RTL support, vertical slider orientation(#3315) (ca2acda), closes #3313
  • color-slider,color-wheel: fix focused state #3278 (96b83f7)

0.33.2 (2023-06-14)

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

0.33.0 (2023-06-08)

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

0.32.0 (2023-06-01)

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

0.31.0 (2023-05-17)

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

0.30.0 (2023-05-03)

Bug Fixes

  • abstract "hasVisibleFocusInTree" functionality and return trigger focus after close (4f39f2c)
  • address westbrooks comments (634af60)
  • color-wheel: use correct focus events in test (f6f35ec)
  • ensure color wheel in not opinionated about saturation and lightness (8e0fd9c)
  • ensure streamingListener ends even if pointercancel not fired (74105f2)
  • expand support for maintaining hue and saturation across customization (fe18944)
  • 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)
  • manage "focused" across more contexts (9273c15)
  • normalize focus passing during and after pointer events (357931b)
  • prevent tabindex=-1 elements from placing focus on their host (1ac1293)
  • remove right click value setting (a44968d)
  • update colour slider (9acda67)
  • use hue normalized color in handle and allow focus (f9e1fa2)

Features

  • adopt DNA@7 base Spectrum CSS (e08cafd)
  • color-wheel: add color-wheel pattern (8b2a56d)
  • color-wheel: use core tokens (57159a2)
  • 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.5.2 (2023-04-24)

Bug Fixes

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

0.5.1 (2023-04-05)

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

0.5.0 (2023-03-22)

Features

  • color-wheel: use core tokens (57159a2)

0.4.9 (2023-02-08)

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

0.4.8 (2023-01-23)

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

0.4.7 (2023-01-09)

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

0.4.6 (2022-12-08)

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

0.4.5 (2022-11-21)

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

0.4.4 (2022-11-14)

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

0.4.3 (2022-10-28)

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

0.4.2 (2022-10-17)

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

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.13 (2022-08-04)

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

0.3.12 (2022-07-18)

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

0.3.11 (2022-06-29)

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

0.3.10 (2022-06-07)

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

0.3.9 (2022-05-12)

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

0.3.8 (2022-04-21)

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

0.3.7 (2022-03-30)

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

0.3.6 (2022-03-08)

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

0.3.5 (2022-03-04)

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

0.3.4 (2022-02-22)

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

0.3.3 (2022-01-26)

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

0.3.2 (2022-01-07)

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

0.3.1 (2021-12-13)

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

0.3.0 (2021-11-08)

Features

  • update lit-* dependencies, wip (377f3c8)

0.2.1 (2021-11-08)

Bug Fixes

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

0.2.0 (2021-11-02)

Features

  • adopt DNA@7 base Spectrum CSS (e08cafd)

0.1.13 (2021-10-12)

Bug Fixes

  • color-wheel: use correct focus events in test (f6f35ec)

0.1.12 (2021-09-20)

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

0.1.11 (2021-09-13)

Bug Fixes

  • manage "focused" across more contexts (9273c15)

0.1.10 (2021-08-24)

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

0.1.9 (2021-08-17)

Bug Fixes

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

0.1.8 (2021-07-22)

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

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

0.1.5 (2021-05-24)

Bug Fixes

  • prevent tabindex=-1 elements from placing focus on their host (1ac1293)

0.1.4 (2021-05-12)

Bug Fixes

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

0.1.3 (2021-04-09)

Bug Fixes

  • ensure color wheel in not opinionated about saturation and lightness (8e0fd9c)
  • use hue normalized color in handle and allow focus (f9e1fa2)

0.1.2 (2021-03-29)

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

0.1.1 (2021-03-22)

Bug Fixes

  • remove right click value setting (a44968d)

0.1.0 (2021-03-05)

Bug Fixes

  • address westbrooks comments (634af60)
  • update colour slider (9acda67)

Features

  • debug colour elements for a11y (7008f7c)
  • color-wheel: add color-wheel pattern (8b2a56d)