sp-icon

NPM 1.4.0

View Storybook
Overview API Changelog

Overview

<sp-icon> renders an icon to the page. By default the name attribute will pair with separately registered icon sets to deliver the icons. When not present, <sp-icon> will subsequently check for its src attribute which could populate the icon via an image, and then fallback to any slotted content for an element based icon.

Usage

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

yarn add @spectrum-web-components/icon

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

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

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

import { Icon } from '@spectrum-web-components/icon';

Example

Names of the icons on this page are provided by the <sp-icons-medium> icon set. Learn how to create your own via sp-iconset.

<sp-icons-medium></sp-icons-medium>
<sp-icon name="ui:Arrow100"></sp-icon>

Options

Sizes

Icons are available in various sizes in Spectrum ranging from s to xxl. By default an sp-icon without a size attribute will appear as if it were size="m". We can specify the size via size attribute.

<sp-icon size="s" name="ui:Arrow100"></sp-icon>
<sp-icon size="m" name="ui:Arrow100"></sp-icon>
<sp-icon size="l" name="ui:Arrow100"></sp-icon>
<sp-icon size="xl" name="ui:Arrow100"></sp-icon>
<sp-icon size="xxl" name="ui:Arrow100"></sp-icon>

Icon colors

Icons apply their color as currentColor, so change the color property of the element for customization.

<sp-icon name="ui:Arrow100" style="color: red;"></sp-icon>

Image icon

An image icon can be supplied via the src attribute. Remember that you cannot style the contents of an image via CSS, so use graphics that are appropriate for your application's design requirements.

<sp-icon
    label="Previous"
    src="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9Ii0yOTU3Ljk5NSAtNTUzMC4wMzIgNiAxMCI+PGRlZnM+PHN0eWxlPi5he2ZpbGw6bm9uZTtzdHJva2U6IzE0NzNlNjtzdHJva2UtbGluZWNhcDpyb3VuZDtzdHJva2UtbGluZWpvaW46cm91bmQ7c3Ryb2tlLW1pdGVybGltaXQ6MTA7c3Ryb2tlLXdpZHRoOjJweDt9PC9zdHlsZT48L2RlZnM+PHBhdGggY2xhc3M9ImEiIGQ9Ik0yNTEuMywzMzNsNC00LTQtNCIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoLTI3MDEuNjk1IC01MTk2LjAzMikgcm90YXRlKDE4MCkiLz48L3N2Zz4="
></sp-icon>

HTML/SVG Element icon

Icons can also be supplied via HTML elements and are applied via the default <slot>.

<sp-icon>
    <svg
        xmlns="http://www.w3.org/2000/svg"
        viewBox="0 0 22 22"
        role="img"
        fill="currentColor"
        height="18"
        width="18"
        aria-hidden="true"
    >
        <path
            d="M19.75,10.04h-15l5.97-5.97a.483.483,0,0,0,0-.7l-.35-.36a.513.513,0,0,0-.71,0L2.24,10.44a.513.513,0,0,0,0,.71l7.39,7.84a.513.513,0,0,0,.71,0l.35-.35a.513.513,0,0,0,0-.71L4.76,11.5H19.75a.25.25,0,0,0,.25-.25v-.96A.25.25,0,0,0,19.75,10.04Z"
        ></path>
    </svg>
</sp-icon>

Accessibility

If no meaning is lost by visually hiding an icon, it is considered decorative. Decorative icons should not have a label and should be hidden from assistive technology. aria-hidden is set to true by default for icons.

If an icon does add meaning, a label is required. Use the label attribute to set the label's text as the aria-label of the icon and remove the aria-hidden attribute.

<sp-icon name="ui:Arrow100" label="Arrow pointing to the right"></sp-icon>

Attributes and Properties

Property Attribute Type Default Description label label string '' name name string | undefined size size 'xxs' | 'xs' | 's' | 'm' | 'l' | 'xl' | 'xxl' | undefined src src string | undefined

Events

Name Type Description error Event

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/iconset@1.4.0
    • @spectrum-web-components/base@1.4.0

1.3.0

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/iconset@1.3.0
    • @spectrum-web-components/base@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/icon

1.1.1 (2025-01-29)

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

1.1.0 (2025-01-29)

Bug Fixes

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

Features

  • add an optional chromatic vrt action (7d2f840)

1.0.3 (2024-12-09)

Bug Fixes

  • toast: adds iconLabel to address accessibility (#4944) (8121057)

1.0.1 (2024-11-11)

Bug Fixes

  • icon: remove size300 suffix from chevron and checkmark icons in Spectrum 2 (#4904) (a22f42b)

1.0.0 (2024-10-31)

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

0.49.0 (2024-10-15)

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

0.48.1 (2024-10-01)

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

0.48.0 (2024-09-17)

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

0.47.2 (2024-09-03)

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

0.47.1 (2024-08-27)

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

0.47.0 (2024-08-20)

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

0.46.0 (2024-08-08)

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

0.45.0 (2024-07-30)

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

0.44.0 (2024-07-15)

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

0.43.0 (2024-06-11)

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

0.42.5 (2024-05-24)

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

0.42.4 (2024-05-14)

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

0.42.3 (2024-05-01)

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

0.42.2 (2024-04-03)

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

0.42.1 (2024-04-02)

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

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/icon

0.41.1 (2024-02-22)

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

0.41.0 (2024-02-13)

Features

  • icon: use core tokens (a11ef6b)

0.40.5 (2024-02-05)

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

0.40.4 (2024-01-29)

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

0.40.3 (2024-01-11)

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

0.40.2 (2023-12-18)

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

0.40.1 (2023-12-05)

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

0.40.0 (2023-11-16)

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

0.39.4 (2023-11-02)

Bug Fixes

  • infield-button: add infield-button package (057b885)

0.39.3 (2023-10-18)

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

0.39.2 (2023-10-13)

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

0.39.1 (2023-10-06)

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

0.39.0 (2023-09-25)

Bug Fixes

  • alert-dialog: add Alert Dialog package (#3501) (1062847)

0.38.0 (2023-09-05)

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

0.37.0 (2023-08-18)

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

0.36.0 (2023-08-18)

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

0.35.0 (2023-07-31)

Features

  • action-bar: use core tokens (4e21edf)

0.34.0 (2023-07-11)

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

0.33.2 (2023-06-14)

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

0.33.0 (2023-06-08)

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

0.32.0 (2023-06-01)

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

0.31.0 (2023-05-17)

Features

  • icon: image src invalid error api (19e06f9)
  • icon: review comment changes (ba75d94)
  • icon: review comment changes (4597713)
  • icon: review comment changes (19287fb)
  • icon: review comment changes (dee1929)
  • icon: review comment changes (cb41b33)
  • icon: skipping test case for webkit (fa4b903)

0.30.0 (2023-05-03)

Bug Fixes

  • allow "updateComplete" to resolve to a boolean like the LitElement default (6127946)
  • correct @element jsDoc listing across library (c97a632)
  • ensure browser understandable extensions (f4e59f7)
  • icon: clean up docs and types for available size values (c38850d)
  • icon: prevent async race resulting in multiple inner SVG elements (b05e2d5)
  • include "type" in package.json, generate custom-elements.json (1a8d716)
  • include default export in the "exports" fields (f32407d)
  • include the "types" entry in package.json files (b432f59)
  • manage updated node types (0517fc1)
  • normalize "event" and "error" argument names (8d382cd)
  • remove ":" based namespacing of events (d77a843)
  • update consumption of Spectrum CSS for latest version (ed2305b)
  • update latest Spectrum CSS beta releases (d8d3acc)
  • update side effect listings (8160d3a)
  • update to latest spectrum-css packages (a5ca19f)
  • use icons without "size" values (3fc7c91)
  • use latest @spectrum-css/* versions (c35eb86)

Features

  • action-button: add action button pattern (03ac00a)
  • adopt DNA@7 base Spectrum CSS (e08cafd)
  • icon: add UIIcon styles (6f03b1a)
  • icon: allow to accept a slotted icon (cbf7a07)
  • icons-workflow: vend fully registered icon components (941f3a4)
  • icon: update spectrum css input (42f17db)
  • include all Dev Mode files in side effects (f70817c)
  • leverage "exports" field in package.json (321abd7)
  • overlay: manage focus throwing and tab trapping (27a0b53)
  • shared pkg versions, devmode define warning, registry-conflicts docs (6e49565)
  • update lit-* dependencies, wip (377f3c8)
  • update to Spectrum CSS v3.0.0 (e8b3d8f)
  • use @adobe/spectrum-css@2.15.1 (3918888)
  • use latest exports specification (a7ecf4b)

Performance Improvements

  • use "sideEffects" listing in package.json (7271614)
  • use imported TypeScript helpers instead of inlining them (cc2bd0a)

Reverts

  • Revert "chore: release new versions" (a6d655d)

0.12.11 (2023-04-24)

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

0.12.10 (2023-04-05)

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

0.12.9 (2023-03-22)

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

0.12.8 (2023-02-08)

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

0.12.7 (2023-01-23)

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

0.12.6 (2023-01-09)

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

0.12.5 (2022-12-08)

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

0.12.4 (2022-11-21)

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

0.12.3 (2022-11-14)

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

0.12.2 (2022-10-28)

Bug Fixes

  • manage updated node types (0517fc1)

0.12.1 (2022-10-10)

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

0.12.0 (2022-08-09)

Features

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

0.11.12 (2022-08-04)

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

0.11.11 (2022-07-18)

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

0.11.10 (2022-06-29)

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

0.11.9 (2022-06-07)

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

0.11.8 (2022-05-27)

Bug Fixes

  • update consumption of Spectrum CSS for latest version (ed2305b)

0.11.7 (2022-05-12)

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

0.11.6 (2022-04-21)

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

0.11.5 (2022-03-08)

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

0.11.4 (2022-03-04)

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

0.11.3 (2022-02-22)

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

0.11.2 (2022-01-26)

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

0.11.1 (2021-12-13)

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

0.11.0 (2021-11-08)

Features

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

0.10.1 (2021-11-08)

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

0.10.0 (2021-11-02)

Bug Fixes

  • icon: prevent async race resulting in multiple inner SVG elements (b05e2d5)

Features

  • adopt DNA@7 base Spectrum CSS (e08cafd)

0.9.11 (2021-09-20)

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

0.9.10 (2021-08-24)

Bug Fixes

  • correct @element jsDoc listing across library (c97a632)

0.9.9 (2021-08-03)

Bug Fixes

  • allow "updateComplete" to resolve to a boolean like the LitElement default (6127946)

0.9.8 (2021-07-22)

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

0.9.7 (2021-06-16)

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

0.9.6 (2021-05-12)

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

0.9.5 (2021-04-09)

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

0.9.4 (2021-03-29)

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

0.9.3 (2021-03-22)

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

0.9.2 (2021-03-22)

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

0.9.1 (2021-03-05)

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

0.9.0 (2021-03-04)

Features

  • use latest exports specification (a7ecf4b)

0.8.3 (2021-02-11)

Bug Fixes

  • update to latest spectrum-css packages (a5ca19f)

0.8.2 (2021-02-02)

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

0.8.1 (2021-01-28)

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

0.8.0 (2021-01-21)

Bug Fixes

  • icon: clean up docs and types for available size values (c38850d)
  • include the "types" entry in package.json files (b432f59)
  • update latest Spectrum CSS beta releases (d8d3acc)
  • use icons without "size" values (3fc7c91)
  • use latest @spectrum-css/* versions (c35eb86)

Features

  • action-button: add action button pattern (03ac00a)
  • icon: update spectrum css input (42f17db)
  • icons-workflow: vend fully registered icon components (941f3a4)

0.7.0 (2021-01-13)

Bug Fixes

  • include the "types" entry in package.json files (b432f59)
  • update latest Spectrum CSS beta releases (d8d3acc)
  • use icons without "size" values (3fc7c91)
  • use latest @spectrum-css/* versions (c35eb86)

Features

  • action-button: add action button pattern (03ac00a)
  • icon: update spectrum css input (42f17db)
  • icons-workflow: vend fully registered icon components (941f3a4)

0.6.3 (2020-10-12)

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

0.6.2 (2020-10-12)

Bug Fixes

  • include default export in the "exports" fields (f32407d)

0.6.1 (2020-09-25)

Bug Fixes

  • update side effect listings (8160d3a)

0.6.0 (2020-08-31)

Features

  • update to Spectrum CSS v3.0.0 (e8b3d8f)

0.5.2 (2020-08-19)

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

0.5.1 (2020-07-24)

Bug Fixes

  • ensure browser understandable extensions (f4e59f7)

0.5.0 (2020-07-17)

Features

  • overlay: manage focus throwing and tab trapping (27a0b53)
  • leverage "exports" field in package.json (321abd7)

0.4.8 (2020-06-08)

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

0.4.7 (2020-05-08)

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

0.4.6 (2020-04-16)

Performance Improvements

  • use "sideEffects" listing in package.json (7271614)

0.4.5 (2020-04-07)

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

0.4.4 (2020-03-11)

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

0.4.3 (2020-01-06)

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

0.4.2 (2019-12-02)

Bug Fixes

  • normalize "event" and "error" argument names (8d382cd)

0.4.1 (2019-11-27)

Bug Fixes

  • include "type" in package.json, generate custom-elements.json (1a8d716)

0.4.0 (2019-11-19)

Features

  • use @adobe/spectrum-css@2.15.1 (3918888)

0.3.0 (2019-11-01)

Bug Fixes

  • remove ":" based namespacing of events (d77a843)

Features

  • icon: allow to accept a slotted icon (cbf7a07)

0.2.0 (2019-10-14)

Features

  • icon: add UIIcon styles (6f03b1a)

Performance Improvements

  • use imported TypeScript helpers instead of inlining them (cc2bd0a)

0.1.3 (2019-10-03)

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