sp-color-slider

NPM 1.7.0

View Storybook

Try it on Stackblitz
Overview API Changelog

Overview

An <sp-color-slider> lets users visually change an individual channel of a color. The background of the <sp-color-slider> is a visual representation of the range of values a user can select from. This can represent color properties such as hues, color channel values (such as RGB or CMYK levels), or opacity. Currently, the slider only supports leveraging the hue property.

Usage

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

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

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

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

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

import { ColorSlider } from '@spectrum-web-components/color-slider';

Anatomy

The color slider consists of several key parts:

  • A gradient track showing the range of color values
  • A draggable handle that indicates the current color position
  • An accessible label for screen readers
<sp-color-slider></sp-color-slider>

Options

Orientation

By default, the color slider is displayed horizontally. You can change the orientation to vertical using the vertical attribute:

<sp-color-slider vertical></sp-color-slider>

States

Standard

The standard color slider allows users to select hue values from 0 to 360 degrees:

<sp-color-slider></sp-color-slider>

Disabled

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

<sp-color-slider disabled></sp-color-slider>

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. If you supply a color in rgb() format, el.color should return the color in rgb() format, as well.

The current color formats supported are as follows:

  • Hex3, Hex4, Hex6, Hex8
  • HSV, HSVA
  • HSL, HSLA
  • RGB, RGBA
  • Strings (eg "red", "blue")

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

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. Seperately, the element's value property is directly managed by the hue as represented in the interface.

Accessibility

The <sp-color-slider> is rendered with appropriate ARIA attributes to ensure accessibility:

  • Uses native input[type="range"] element with implicit "slider" role
  • Provides value text announcements for screen readers
  • Supports full keyboard navigation

Accessible Labels

The color slider includes an accessible label that describes what the slider controls. By default, the label is set to "hue", but you can customize it using the label attribute:

<!-- Default label -->
<sp-color-slider></sp-color-slider>

<!-- Custom label -->
<sp-color-slider label="Color hue"></sp-color-slider>
<sp-color-slider label="Saturation level"></sp-color-slider>

The label serves several important accessibility purposes:

  • Screen Reader Announcements: Screen readers announce the label when the slider receives focus, helping users understand what they're adjusting
  • ARIA Labeling: The label is used as the aria-label attribute on the internal range input
  • Context for Value Changes: When the slider value changes, screen readers announce both the current value and the label for context

For example, when a user focuses on a color slider with label="Color hue", screen readers will announce something like "Color hue slider, 180 degrees" to provide clear context about what the control does and its current value.

Keyboard Navigation

Key Action Arrow Left/Arrow Down Decreases the hue value Arrow Right/Arrow Up Increases the hue value Shift + Arrow Left/Shift + Arrow Down Decreases the hue value by a larger step (10x) Shift + Arrow Right/Shift + Arrow Up Increases the hue value by a larger step (10x) Page Down Decreases the hue value by a larger step(10% of total value) Page Up Increases the hue value by a larger step(10% of total value) Home Sets the hue to minimum value (0) End Sets the hue to maximum value (360)

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 vertical vertical boolean false

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 Slider has been committed by the user. input Event The value of the Color Slider 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-slider

1.1.1 (2025-01-29)

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

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

1.0.1 (2024-11-11)

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

1.0.0 (2024-10-31)

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

0.49.0 (2024-10-15)

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

0.48.1 (2024-10-01)

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

0.48.0 (2024-09-17)

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

0.47.2 (2024-09-03)

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

0.47.1 (2024-08-27)

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

0.47.0 (2024-08-20)

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

0.46.0 (2024-08-08)

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

0.45.0 (2024-07-30)

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

0.44.0 (2024-07-15)

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

0.43.0 (2024-06-11)

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

0.42.5 (2024-05-24)

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

0.42.4 (2024-05-14)

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

0.42.3 (2024-05-01)

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

0.42.2 (2024-04-03)

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

0.42.1 (2024-04-02)

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

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

0.41.1 (2024-02-22)

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

0.41.0 (2024-02-13)

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

0.40.5 (2024-02-05)

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

0.40.4 (2024-01-29)

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

0.40.3 (2024-01-11)

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

0.40.2 (2023-12-18)

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

0.40.1 (2023-12-05)

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

0.40.0 (2023-11-16)

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

0.39.4 (2023-11-02)

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

0.39.3 (2023-10-18)

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

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

0.39.0 (2023-09-25)

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

0.37.0 (2023-08-18)

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

0.36.0 (2023-08-18)

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

0.35.0 (2023-07-31)

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

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)
  • color-slider: announce new value on change after keydown (#3304) (d70d0ae), closes #3303

0.33.2 (2023-06-14)

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

0.33.1 (2023-06-14)

Bug Fixes

  • color-slider: use inset-block-_ and inset-inline-_ and fix RTL orientation and behavior #3301 (52aa328)

0.33.0 (2023-06-08)

Bug Fixes

  • color-slider: vertical variant orientation is upside down #3291 (67c7e0a)

0.32.0 (2023-06-01)

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

0.31.0 (2023-05-17)

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

0.30.0 (2023-05-03)

Bug Fixes

  • abstract "hasVisibleFocusInTree" functionality and return trigger focus after close (4f39f2c)
  • address westbrooks comments (634af60)
  • color-slider: use correct focus events in test (b974c12)
  • 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 (53221da)
  • 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)
  • simplify touch-action application (d23f735)
  • update colour slider (9acda67)
  • use hue normalized color in handle and allow focus (f9e1fa2)

Features

  • adopt DNA@7 base Spectrum CSS (e08cafd)
  • color-handle: use core tokens (e0c1468)
  • color-slider: add color-slider pattern (625f6fe)
  • 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.0 (2023-04-24)

Bug Fixes

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

Features

  • color-handle: use core tokens (e0c1468)

0.4.11 (2023-04-05)

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

0.4.10 (2023-03-22)

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

0.4.9 (2023-02-08)

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

0.4.8 (2023-01-23)

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

0.4.7 (2023-01-09)

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

0.4.6 (2022-12-08)

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

0.4.5 (2022-11-21)

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

0.4.4 (2022-11-14)

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

0.4.3 (2022-10-28)

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

0.4.2 (2022-10-17)

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

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

0.3.12 (2022-07-18)

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

0.3.11 (2022-06-29)

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

0.3.10 (2022-06-07)

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

0.3.9 (2022-05-12)

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

0.3.8 (2022-04-21)

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

0.3.7 (2022-03-30)

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

0.3.6 (2022-03-08)

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

0.3.5 (2022-03-04)

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

0.3.4 (2022-02-22)

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

0.3.3 (2022-01-26)

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

0.3.2 (2022-01-07)

Bug Fixes

  • simplify touch-action application (d23f735)

0.3.1 (2021-12-13)

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

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-slider: use correct focus events in test (b974c12)

0.1.12 (2021-09-20)

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

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

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

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

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 (53221da)
  • 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-slider

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-slider: add color-slider pattern (625f6fe)