@spectrum-web-components/icons-ui

Overview

Deliver Spectrum UI Icons as either:

• Registered custom elements (<sp-icon-arrow75>)
• Unregistered class definitions (IconArrow75)
• Functions with customizable template tags to be used across various frameworks (Arrow75Icon())

Search a full list of icons to find an icon for your project or find technical information about extended use cases, like consuming this package in various UI frameworks below.

Remember to consult Spectrum's Iconography Guidelines when planning how to leverage these icons in the visual delivery of your application.

Usage

yarn add @spectrum-web-components/icons-ui

Import the side effectful registration of a single element (e.g. <sp-icon-arrow75>) via:

import '@spectrum-web-components/icons-ui/icons/sp-icon-arrow75.js';

Leverage a single icon base class (e.g. IconArrow75) as a type, or for extension purposes, do so, via:

import { IconArrow75 } from '@spectrum-web-components/icons-ui/src/elements/IconArrow75.js';

Find an icon

Search the available Spectrum Workflow icons below.

Complete search experience available at: https://opensource.adobe.com/spectrum-web-components/components/icons-ui/.

Alternative usage

You can import raw icons (e.g. Arrow75Icon()) via:

import { Arrow75Icon } from '@spectrum-web-components/icons-ui/src/icons/Arrow75.js';

@spectrum-web-components/icons-ui exports all icons. If your build process tree-shakes dependencies, you can import from it directly:

import { Arrow75Icon } from '@spectrum-web-components/icons-ui';

These icon literals are prepared with the html template tag from lit-html, the default value of an icon export will be as follows:

import { LitElement, html } from 'lit-element';
import '@spectrum-web-components/icon';
import { Arrow75Icon } from '@spectrum-web-components/icons-ui';

class ElementWithIcon extends LitElement {
    protected override render(): TemplateResult {
        return html`
            <sp-icon>
                ${Arrow75Icon()}
            </sp-icon>
        `
    }
}

customElements.define('element-with-icon', ElementWithIcon);

Every icons can be customized via the following options:

{
    width: 24, // number outlining the width to deliver the SVG element with
    height: 24, // number outlining the height to delivery the SVG element with
    hidden: false, // boolean representing whether to apply the `aria-hidden` attribute
    title: 'Icon title', // string of the title to deliver the icon with
}

Extended use cases

The default exports of this package are pre-wrapped via setCustomTemplateLiteralTag in the html template tag from lit-html, and work like the following::

import { Arrow75Icon } from '@spectrum-web-components/icons-ui';

console.log(Arrow75Icon());

/***
TemplateResult {strings: Array[1], values: Array[0], type: "html", processor: DefaultTemplateProcessor, constructor: Object}
***/

When working in the context of other frameworks, it is possible to import the icons with a generic template tag as follows:

import { Arrow75Icon } from '@spectrum-web-components/icons-ui/src/icons.js';

console.log(Arrow75Icon());

/***
<svg
    xmlns="http://www.w3.org/2000/svg"
    viewBox="0 0 36 36"
    role="img"
    fill="currentColor"
    height="24"
    width="24"
    aria-hidden="false"
    aria-label="Circle"
>
    <path
      d="M9.26 4.406L6.528 1.672A.84.84 0 005.34 2.859L6.64 4.16H1.396a.84.84 0 000 1.68H6.64l-1.301 1.3a.84.84 0 001.188 1.188l2.734-2.734a.84.84 0 000-1.188z"
    />
</svg>
***/

What's more, if you're already working with a specific parser in your project, you can assign it as the one to use when delivering the icons in order to be sure that the SVG content is delivered as parsed content to your final template. The means if you were working with Preact via the htm tag as bound to the provided hyperscript function:

import {
    Arrow75Icon,
    setCustomTemplateLiteralTag,
} from '@spectrum-web-components/icons-ui/src/icons.js';
import htm from 'htm';
import { h } from 'preact';

const hPreact = htm.bind(h);

setCustomTemplateLiteralTag(hPreact);

console.log(Arrow75Icon());

/***
VNode {nodeName: "svg", children: Array[1], attributes: Object, key: undefined, constructor: Object}
***/

In this way, the icons exported by @spectrum-web-components/icons-ui can be leveraged in projects powered by the likes of hyperHTML, lighterhtml, lit-html, Preact, React, Vanilla JS, Vue.js, and more!

Accessibility

Review the accessibility guidelines for the icon.

Changelog

1.9.0 (2025-10-13)

Minor Changes

sp-icons-workflow: - Upgraded to @adobe/spectrum-css-workflow-icons@5.0.0. - Includes changes from previous a4u upstream releases: - Added S2_Icon_HeartFilled_20_N.svg, updated S2_Icon_SpeedFast_20_N.svg. - Replaced all 22×20px Cloud State icons with 20px variants. - Removed deprecated multi-colored error icon. Added new Cloud State icons (Disconnected, Error, InProgress, Online, Paused, Pending, SlowConnection). - Updated several other icons (CloseCaptions, CommentHide, Community, etc.).

• For the full changelog, see: https://github.com/adobe/spectrum-css-workflow-icons/pull/50

Patch Changes

sp-button: - Fixed: Aria-label handling in <sp-button> component.

• Fixed: Moved aria-label updates to occur after slot content changes are processed to prevent timing issues
• Added: Enhanced label property support for programmatic aria-label control
• Added: Comprehensive tests for aria-label behavior during content and pending state changes
• Fixed: Removed duplicate aria-label update logic in update() method

These changes ensure that aria-labels are properly managed and preserved across component state changes, improving accessibility for screen reader users.

sp-combobox: - Fixed: Pending state handling and accessibility in <sp-combobox> component.

• Changed: Removed dependency on PendingStateController and implemented inline pending state handling
• Fixed: Updated aria-labelledby attribute ordering to improve screen reader experience (label applied-label pending-label)
• Fixed: Updated progress circle implementation to use role="presentation" instead of aria-valuetext
• Added: Direct pending state visual rendering with improved accessibility

These changes improve accessibility for pending states while reducing unnecessary component dependencies.

sp-menu: - Fixed: MenuItem focus stealing from input elements on mouseover by enhancing MenuItem's handleMouseover method to detect when an input element currently has focus and prevent stealing focus in those cases.

sp-alert-dialog: - Fixed: Make the divider color transparent only for Spectrum 2 theme

sp-picker: - Fixed: Picker border color should be hidden in S2 theme

sp-textfield: - Fixed: Update border radius and border width for different t-shirt sizes for textfield component for S2 and Express themes

sp-textfield: - Fixed: Update border color and block padding inside the textfield and textarea components for S2 and Express themes

sp-picker: - Fixed: Pending state handling and accessibility in <sp-picker> component.

• Changed: Removed dependency on PendingStateController and implemented inline pending state handling
• Fixed: Updated aria-labelledby attribute ordering to improve screen reader experience (icon label applied-label pending-label)
• Fixed: Updated progress circle implementation to use role="presentation" instead of aria-valuetext
• Added: Direct pending state visual rendering with improved accessibility

These changes improve accessibility for pending states while reducing unnecessary component dependencies.

sp-progress-circle: - Fixed: Accessibility warning logic in <sp-progress-circle> component.

• Fixed: Updated accessibility warning logic to only apply when role="progressbar" is explicitly set
• Fixed: Improved label validation for better accessibility compliance

These changes ensure accessibility warnings are only shown when appropriate and improve overall accessibility compliance.

sp-reactive-controllers: - Fixed: Accessibility and caching in PendingStateController.

• Fixed: Updated progress circle to use role="presentation" for better accessibility compliance
• Fixed: Improved aria-label caching logic to better handle dynamic label changes
• Added: Documentation noting the controller is primarily used by <sp-button> component
• Fixed: Enhanced caching mechanism to preserve user-set aria-labels during pending states

These changes improve accessibility compliance and aria-label management for components using the pending state controller.

sp-help-text: - Fixed: Update block paddings for S2 and Express themes

sp-field-label: - Fixed: Update block paddings for S2 and Express themes