Icons communicate messages, enhance interactivity, and highlight critical information. Use them as visual representations of concepts, objects, or actions efficiently.

<sl-icon name="angle-down" size="2xs"></sl-icon>
<sl-icon name="face-smile"></sl-icon>
<sl-icon name="triangle-exclamation-solid" size="xl" style="color:red"></sl-icon>
<sl-icon name="pinata" size="4xl"></sl-icon>

When to Use

Icons are important for user understanding and interaction

Intuitive Content

Icons enhance usability, facilitating a quick understanding by providing a visual representation of information. They can communicate complex messages to the user effectively in a simple and concise manner, resulting in a more intuitive and user-friendly experience.

Labeling Icons

It is challenging to find icons that are universally understood without some form of textual explanation. Therefore, it is best practice to add a label in combination with an icon. Incorporating labels can enhance usability, and a larger clickable area reduces interaction costs. Some icons, such as the save iconor the close iconare so common that they can be used without a label if there is no space for one.

When not to Use

Our focus is on functionality and accessibility, ensuring icons convey meaningful information and enhance usability.

Not for Decoration

Avoid using the icon component for purely decorative purposes. The main objective is to enhance the user's understanding of the actions within the interactive elements. When icons are utilized solely for ornamentation without contributing to the clarity or functionality of the interface, it can lead to visual clutter and detract from the overall usability of the interface. Use icons to convey meaningful information or facilitate user interactions to maintain usability and effectiveness.


We use the icons library Font Awesome to ensure that all the icons look similar and are easy to use. However, it is possible to implement custom icons.

  • Font Awesome: By default, we provide the Font Awesome icons library to choose the icons from them. You only need to check and copy the icon name to the icon layer.

  • Custom: You can also create specific SVG icons, but we encourage using Font Awesome. If it is necessary to have a custom icon because it's mandatory for your app, contact us to tell you the next steps.

Figma Options

With these options, you can tweak the appearance of the icon in Figma. They are available in the Design Panel so you can compose the icon to exactly fit the user experience need for the use case you are working on.

Icon'fa', 'svg'Choose the variant of the icon, Font Awesome or Custom (SVG).
FontAwesome'Icon Name'Write down the name of the icon from Font Awesome.
  import { faTruckFast } from '@fortawesome/pro-regular-svg-icons';

<sl-icon name="face-smile"></sl-icon>
<sl-icon name="triangle-exclamation-solid" size="xl" style="color:var(--sl-color-palette-danger-500)"></sl-icon>
<sl-icon name="far-truck-fast" size="4xl"></sl-icon>

Using included icons

There are a number of icons included in the design system as SVG, provided via the sl-icon component. These can be either Font Awesome icons that are used in SLDS components or icons that have been created by (y)our designers. There is no difference in how to use these icons, both can be used by setting the name of the icon property without additional steps. You can find the list of available icons in your theme on our Storybook page.

Using additional Font Awesome Pro icons

In addition to the provided icons you can use all icons available in Font Awesome Pro[1]. Firstly you will need to add the install the icon styles you want to use:

npm install @fortawesome/pro-regular-svg-icons

yarn add @fortawesome/pro-regular-svg-icons

The icons need to be registered in order for them to load and be available in you application. You can choose the icon you want to use on the Font Awesome website to find the name and pakage. Then you will need to import that icon from the corresponding package:

import { faTruckFast } from '@fortawesome/pro-regular-svg-icons';

To add the icon[2] to the registry that is used in the browser you use the function on the Icon component:


These two steps will make the Truck Fast icon from the regular (outline) style available. Because you can use a mixture of icons from different styles in one page Font Awesome uses a prefix per style to avoid conflicts. This causes the name of the icon you need to use in the sl-icon component to slightly differ from the icon you imported in previous step. There is an overview of which style uses which prefix available on the Font Awesome website.

Now you can use the icon:

<sl-icon name="far-truck-fast"></sl-icon>

Where you import and register the icon is up to you, but it is advised to do this on the highest shared "parent" of all places that use the icon. So a very generally used icon could be registered in the same place you have the setup() for you theme, but an icon that is used only in dashboards can be registred in the dashboard-module.


  1. There is a Sanoma wide Pro-license available in order to use the whole library. You will need a token both locally and in your build environment. Contact us via Slack or email to obtain this token.
  2. It is also possible to pass multiple icons into the register function at once: Icon.register(faTruckFast, faPinata);


Component has a range of properties to define the experience in different use cases.


labellabelstring | undefinedThe label of the icon; Describes the icon for assistive devices. If not present, the icon is considered
to be purely presentational.
namenamestring | undefinedThe name of the icon; either the name from Font Awesome or the name of the custom icon in Figma.
sizesize'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl'The size of the icon.


registericons: IconDefinition | IconDefinition[]voidAdd icon(s) to the icon registry

CSS Properties

--sl-icon-container-sizeThe size of the icon container, defaults to md
--sl-icon-fill-accentAccent color, only used for multicolor icons
--sl-icon-fill-defaultDefault fill color
--sl-icon-sizeThe size of the svg element, defaults to md


The label only needs to be set when there is no accompanying text with the icon, as the assistive technology will read this label as well as the accompanying text. It can however be used in the rare cases the icon adds additional information to the label.


AttributeValueDescriptionUser suppliedSpecifies whether the attribute is always set in the component (no) or it needs to be provided by the developer (yes)
aria-labelstringSet by using the label property on the element.no
aria-hiddenbooleanWhen no label is set we assume the icon is purely presentational and we hide it from assistive technology.no
role'img', undefinedWhen a label is set this means the icon will be part of the accessibility tree and thus we need to declare it as an icon.no
Interactive example