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

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';

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>

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>

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>

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>

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>

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>

API

Changelog

• #2786 a434c9a Thanks @pfulton! - Align selectors with the specificity that exists in S1 today

• #2786 57709c0 Thanks @pfulton! - Pull in the corner radii updates for S2

• Updated dependencies [57709c0]:
  • @spectrum-css/tokens@15.0.0-s2-foundations.22

• #2786 11a0032 Thanks @pfulton! - Bug fixes to S1 & Express theming across all components

• Updated dependencies [11a0032]:
  • @spectrum-css/tokens@15.0.0-s2-foundations.21

• #2786 f38c66a Thanks @pfulton! - Fix icon sizing and checkbox border colors

• #2786 5546ec6 Thanks @pfulton! - - Accordion: Flatten sizing variables in theme layer
  • ActionButton: Fix typo in variable name "*-defaul-selectedt"
  • Move out rtl logical transform from theme to index.css for: calendar, pagination, treeview

• Updated dependencies [5546ec6]:
  • @spectrum-css/tokens@15.0.0-s2-foundations.13

• #2786 b0862e1 Thanks @pfulton! - Updated build to set cssnano to discardUnused: false

• Updated dependencies [b0862e1]:
  • @spectrum-css/tokens@15.0.0-s2-foundations.12

• #2786 0844aad Thanks @pfulton! - Fixes to index.css imports to ensure appropriate system mappings get loaded

• Updated dependencies [0844aad]:
  • @spectrum-css/tokens@15.0.0-s2-foundations.10

• #2786 494da11 Thanks @pfulton! - ## Feature [@spectrum-css/icon]

  Update source files to load the mappings from component-level to global tokens for size and transform values. This will allow for more consistent and predictable behavior when using the size and transform props on icons when switching between contexts for S1, S2, and Express.

  Patch [@spectrum-css/typography]

  #Section titled Patch [@spectrum-css/typography]

  Remove the sourcemap footer from compiled assets.

• #2786 84c8721 Thanks @pfulton! - Push out the latest release to the components

• #2786 0a0dace Thanks @pfulton! - Across the board version update to latest build system state

• #2786 681ba47 Thanks @pfulton! - Doing a widespread release on all packages to ensure the latest compiled CSS is published.

• Updated dependencies [681ba47, 84c8721, 0a0dace]:

  • @spectrum-css/tokens@15.0.0-s2-foundations.9

• #2786 2633985 Thanks @pfulton! - Update system property tooling (splitinator) to leverage the selector parser

• Updated dependencies [2633985]:
  • @spectrum-css/tokens@15.0.0-s2-foundations.8

• #2786 24a51cc Thanks @pfulton! - Revert themes asset naming to simplify code review; bug fixes in custom property loading from theme assets

• Updated dependencies [24a51cc]:
  • @spectrum-css/tokens@15.0.0-s2-foundations.7

• #2786 4d88749 Thanks @pfulton! - Inject missing tokens into theme files and adjust logic in the splitinator tool to replace nested variable references to the new system mappings

• Updated dependencies [130e137, 4d88749]:

  • @spectrum-css/tokens@15.0.0-s2-foundations.6

• #2786 de1d39f Thanks @pfulton! - Fix to how the system mapped custom property names are generated; adding support for pseudo functions, combinators, and complex selectors

• Updated dependencies [de1d39f]:

  • @spectrum-css/tokens@15.0.0-s2-foundations.5

• #2786 485128c Thanks @pfulton! - Corrects a faulty regex that was negatively affecting compilation of custom properties

• Updated dependencies [485128c]:

  • @spectrum-css/tokens@15.0.0-s2-foundations.4

• #2786 6b12d37 Thanks @pfulton! - fixes a compilation issue in the tokens dist artifacts

• Updated dependencies [6b12d37]:
  • @spectrum-css/tokens@15.0.0-s2-foundations.3

• #2786 b00388b Thanks @pfulton! - Preserves themes folder in dist artifacts for easier downstream consumption

• Updated dependencies [b00388b]:
  • @spectrum-css/tokens@15.0.0-s2-foundations.2

• #2786 39bbd6c Thanks @pfulton! - Fixes an issue where vars.css was not being populated with the correct values

• Updated dependencies [39bbd6c]:
  • @spectrum-css/tokens@15.0.0-s2-foundations.1

• #2786 5e9953d Thanks @pfulton! - S2 colors + grays foundation

• Updated dependencies [5e9953d]:
  • @spectrum-css/tokens@15.0.0-s2-foundations.0

• #3107 83d5a17 Thanks @castastrophe! - Incorporate glob export for the dist directory in all component packages as well as glob markdown exports (to include both CHANGELOG and READMEs).

  Sort keys in the package.json assets.

• #3045 5d6e03f Thanks @castastrophe! - Improve changeset suggestions by using exports instead of files in component packages

• #2974 fd00178 Thanks @jawinn! - Removes legacy normalization CSS for Icon SVGs that changed the overflow property. This is to fix a reported issue with clipping in iOS mobile for Express and Safari for MacOS. The original CSS declaration was for Internet Explorer 9/10/11 and could be removed because IE 11 is not supported.

• #2677 d83200c Thanks @castastrophe! - Leveral local workspace versioning to prevent misalignment

• #2616 7f45ea9 Thanks @castastrophe!

Output for all component CSS files is now being run through a lightweight optimizer (cssnano) which significantly reduces unnecessary whitespace. These changes reduce file size but should not have any impact on the rendering of the component. By removing unnecessary whitespace from var functions, we are making it easier to effectively minify our provided CSS assets.

• Updated peerDependencies [7f45ea9]:
  • @spectrum-css/tokens@>=14

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

🗓 2024-04-18 • 📝 Commits

*feat!: postcss config build and script; remove gulp (#2466)(b0f337b), closes#2466

### 🛑 BREAKING CHANGES

* - Removes component-builder & component-builder-simple for script leveraging postcss

• Imports added to index.css and themes/express.css

🗓 2024-03-07 • 📝 Commits

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

🗓 2024-02-26 • 📝 Commits

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

🗓 2024-02-15 • 📝 Commits

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

🗓 2024-02-12 • 📝 Commits

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

🗓 2024-02-06

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

🗓 2024-02-05 • 📝 Commits

*refactor(icon)!: tokens migration (#2347)(b63631a), closes#2347

### 🛑 BREAKING CHANGES

* migrate Icon from DNA tokens to Spectrum tokens.

Additionally:

• refactor(icon): migrate css to spectrum tokens

Migrates Icon CSS from using DNA/vars tokens to Spectrum tokens. Refactors UI Icons to be a little cleaner and not need placeholders.

Icons now change the value of the property "--spectrum-icon-size" to set their width and height. They also have three additional mods available for setting the size (both width and height) or the individual width and height.

• refactor(icon): remove legacy xvar css and plugin for combined icons

• Remove 'xvar' and 'x--' code within UI icon CSS, along with the build plugins that were used only for this. This was only only needed previously when the build did not allow 'var()' and '--property' here.

• Simplify and better document code used for combined UI icons and the medium/large platform scale. Remove old browser support here that is no longer needed with the browsers and features that are currently supported by the library. The old fallback to set display inline was pre Firefox version 56 [2017].

• refactor(icon): remove gripper icon classes

Removing the gripper icon classes as they were incorrect and not used, and there are no tokens defined yet to set the actual classes to.

The gripper icon classes used previously were wrong in several ways. For one, they were using '100' size naming in the classes which are not currently used or displayed. These icons are without the number size. The old alias values being applied to them also looked incorrect when looking at the widths, and the CSS was swapping width for height.

That there is no size applied to these icons was obfuscated by the fact that the attribute width="10" is being applied to icons in Storybook.

Note: SWC is currently showing these icons with workflow sizing. These gripper icons do not have size tokens defined yet, but they may be added in the future "as they are needed"; when these icons start being used.

• docs(icon): storybook - add kitchen sink style story for chromatic

Cover the various types of icons in a Chromatic only story. Covers different icon sets, sizes, and color in the VRTs.

• feat(icon): adjust icon sizing custom properties

Make sure we always have custom properties that contains the width and height, that we can rely upon for CSS calculations. Regardless of whether the individual dimensions are specified or just the size is specified (that applies to both dimensions).

• fix(icon): storybook - remove inline width attribute

The icons in Storybook were adding an inline "width" attribute set to 10, which was previously obfuscating issues with sizing. Removes this attribute and leaves sizing up to CSS.

• feat(icon): support for xs workflow icon size

Added extra small workflow icon size. This has a token, is defined on some of the design redlines (Action Button), and is currently used in the Contextual Help component, as seen in the VRT run.

• feat(icon): remove theme files without content

Recent updates to main make it no longer necessary to include empty theme files for the build to work.

• feat(icon): storybook - use ui icon size numbers

Disables the size control for UI icons and adds each size number to the list of available UI icon names in Storybook.

UI icons have specific sizing and don't use the t-shirt sizing that Workflow icons do. They have more size numbers than there are t-shirt sizes, so they can't be directly mapped to each other. The different UI icons have different size numbers, so the size numbers can't use a single control.

• feat(icon): storybook - show all ui icons in chromatic template

Show all UI icons, including number sizing, in the Chromatic template. Condenses and improves some of the template logic.

• fix(icon): wrong workflow icons appearing for arrow and chevron

Fix bug where the wrong icon was being rendered for workflow arrow and chevron. These are both icons with names that exist in both icon sets. There was logic being applied to the workflow icons that should have only have been applied to the UI icon.

• chore(icon): manual version bump for beta release

• feat(icon): add xxs size for migration and use renamed xxl property

Add XXS size to support existing SWC size. Uses the values from --spectrum-global-dimension-size-150, as used in SWC's custom icon CSS.

Included comments to note that xxs and xxl are planned to be deprecated in Spectrum 2, as they are not a part of the design spec.

• chore(icon): set current beta versions already released

• build(icon): minimum tokens version with xxl and xxs sizing

Update required tokens version with a minimum of the latest release that includes the new custom-vars for the xxl and xxs workflow icon sizes.

🗓 2024-01-29 • 📝 Commits

• **overlay,commons:**deprecate overlay; migrate references to commons (#2429)(7eecd96)

🗓 2024-01-16 • 📝 Commits

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

🗓 2023-12-12 • 📝 Commits

*feat(icon,ui-icons)!: migrate the icon compiler to a distinct package (#2343)(d73d594), closes#2343

### 🛑 BREAKING CHANGES

* - @spectrum-css/icon will no longer contain SVG assets; it will be a purely CSS package with all SVG assets migrated to the new @spectrum-css/ui-icons package.

• NEW: @spectrum-css/ui-icons package for all SVG icons in the UI set.

🗓 2023-11-15 • 📝 Commits

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

🗓 2023-11-13 • 📝 Commits

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

🗓 2023-09-18 • 📝 Commits

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

🗓 2023-09-13 • 📝 Commits

*gulp and build updates (#2121)(03a37f5), closes#2099

🗓 2023-08-16 • 📝 Commits

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

🗓 2023-08-07 • 📝 Commits

*feat(sidenav)!: use spectrum-tokens (#1901)(8851dd9), closes#1901

### 🛑 BREAKING CHANGES

* Migrates Side Nav to use @adobe/spectrum-tokens

Additionally:

• chore(sidenav): initial build changes

• chore(sidenav)!: wip add new tokens

• chore(sidenav)!: wip migrate tokens

• chore(sidenav)!: wip migrate tokens

• chore(sidenav): migrates tokens part 3

• fix(sidenav): typo

• chore(sidenav): add description and migration guide

• chore(sidenav): add highcontrast custom properties

• chore(sidenav): properties rename and organize

• chore(sidenav): wip adjust stories

• chore(sidenav): add mods

• chore(sidenav): rename and docs

• feat(sidenav): adds all variants to storybook

• fix(sidenav): icon and category story bugs

• feat(sidenav): icon pass through custom properties

• fix(sidenav): custom properties for icon

• fix(sidenav): correct gap usage

• fix(sidenav): dont't use pass through properties for icon

• chore(sidenav): add span to doc site side nav

• feat(sidenav): add icon styling

• chore(sidenav): whcm

• chore(sidenav): use new header tokens

• chore(sidenav): mods auto updates

• fix(sidenav): whcm icon hover

• fix(sidenav): addresses nesting icons in storybook

• feat(sidenav): use new tokens for heading layout

• fix(sidenav): spectrum link

• fix(sidenav): address design feedback

• fix(sidenav): whcm

• feat(sidenav): adds in icon variant to storybook

• chore(sidenav): remove stylelint disables

• chore(sidenav): address PR feedback

• chore(sidebav): address PR feedback part 2

• feat(sidenav): hard code line height

• fix(sidenav): hover on dark

• chore(sidenav): manual version increase for beta release

• chore(sidenav): new value for text bottom margin

• chore(sidenav): remove custom tokens

• Revert "chore(sidenav): remove custom tokens"

This reverts commit a404f9505d8125277ed5eda0312289a0468a527f.

• chore(sidenav): tokens version

• feat(sidenav): width set to 100%

• chore(sidenav): manual version increase for beta release

• fix(sidenav): line height properties

• fix(sidenav): adds padding for focus ring

• chore(sidenav): add comment

• chore(sidenav): remove added padding

• chore(sidenav): manual version increase for beta release

🗓 2023-07-24 • 📝 Commits

*icon sizing in Storybook story templates (#2037)(c90c8a3)

🗓 2023-06-21 • 📝 Commits

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

🗓 2023-06-15 • 📝 Commits

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

🗓 2023-06-12 • 📝 Commits

*restore files to pre-formatted state(491dbcb)

🗓 2023-06-02 • 📝 Commits

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

🗓 2023-06-01 • 📝 Commits

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

🗓 2023-05-23 • 📝 Commits

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

🗓 2023-05-17 • 📝 Commits

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

🗓 2023-05-02 • 📝 Commits

• icon: correct storybook icon sizing substitution (3da3f41)

🗓 2023-04-26 • 📝 Commits

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

🗓 2023-04-25 • 📝 Commits

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

🗓 2023-04-25 • 📝 Commits

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

🗓 2023-04-17 • 📝 Commits

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

🗓 2023-04-14 • 📝 Commits

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

🗓 2023-04-03 • 📝 Commits

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

🗓 2023-03-13 • 📝 Commits

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

🗓 2023-03-09 • 📝 Commits

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

🗓 2023-02-21 • 📝 Commits

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

🗓 2023-02-06 • 📝 Commits

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

🗓 2023-02-01 • 📝 Commits

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

🗓 2023-02-01 • 📝 Commits

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

🗓 2023-01-27 • 📝 Commits

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

🗓 2023-01-25 • 📝 Commits

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

🗓 2023-01-18 • 📝 Commits

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

🗓 2023-01-13 • 📝 Commits

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

🗓 2022-12-16 • 📝 Commits

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

🗓 2022-11-11 • 📝 Commits

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

🗓 2022-06-16 • 📝 Commits

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

🗓 2022-06-07 • 📝 Commits

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

🗓 2022-04-28 • 📝 Commits

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

🗓 2022-04-08 • 📝 Commits

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

🗓 2022-03-22 • 📝 Commits

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

🗓 2022-03-17 • 📝 Commits

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

🗓 2022-03-07 • 📝 Commits

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

🗓 2022-03-07 • 📝 Commits

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

🗓 2022-02-23 • 📝 Commits

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

🗓 2022-02-16 • 📝 Commits

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

🗓 2022-01-26 • 📝 Commits

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

🗓 2022-01-05 • 📝 Commits

• update peer dependencies (97810cf)

🗓 2022-01-05 • 📝 Commits

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

🗓 2021-12-14 • 📝 Commits

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

🗓 2021-12-06 • 📝 Commits

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

🗓 2021-11-16 • 📝 Commits

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

🗓 2021-11-10 • 📝 Commits

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

🗓 2021-11-09 • 📝 Commits

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

🗓 2021-11-08 • 📝 Commits

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

🗓 2021-10-25 • 📝 Commits

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

🗓 2021-09-29 • 📝 Commits

• make SVG icons adjust to text color (42c343a)
• updating version number on vars (f535b49)

🗓 2021-08-16 • 📝 Commits

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

🗓 2021-06-17 • 📝 Commits

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

🗓 2021-05-12 • 📝 Commits

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

🗓 2021-04-27 • 📝 Commits

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

🗓 2021-04-15 • 📝 Commits

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

🗓 2021-03-10 • 📝 Commits

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

🗓 2021-02-02 • 📝 Commits

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

🗓 2020-12-04 • 📝 Commits

• remove deprecated icon sizes (0ea3a53)

• correct icon sizing for small cards (5b570f4)
• update main, resolved conflicts (d7880a2)

• .spectrum-Icon--sizeL is now .spectrum-Icon--sizeXXL and will likely be removed later
• XXS, XS, and XXL icon sizes are no longer supported and have been removed

🗓 2020-10-20 • 📝 Commits

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

🗓 2020-09-23 • 📝 Commits

• change icon sizes to match Spectrum (ceff437)

• updating tokens beta with breaking changes (9043417)

• icon sizes have changed, all instances of spectrum-Icon--sizeS should be replaced with spectrum-Icon--sizeM, check other sizes as well

🗓 2020-05-14 • 📝 Commits

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

🗓 2020-03-12 • 📝 Commits

• make Icon support RTL (1e3ce00)

🗓 2020-03-06 • 📝 Commits

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

🗓 2020-02-10 • 📝 Commits

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

🗓 2019-12-14 • 📝 Commits

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

🗓 2019-11-08 • 📝 Commits

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

🗓 2019-11-07 • 📝 Commits

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

🗓 2019-10-08

• move to individually versioned packages with Lerna (#265) (cb7fd4b), closes #231 #214 #229 #240 #239 #161 #242 #246 #219 #235 #189 #248 #232 #248 #218 #237 #255 #256 #258 #257 #259