Documentation

Documentation

Icons

Lumo and Vaadin icons and how to use them in your projects.

The icon component can render SVG and font icons. Two icon collections are available out-of-the-box.

Open in a
new tab
<vaadin-icon icon="lumo:photo"></vaadin-icon>
<vaadin-icon icon="vaadin:phone"></vaadin-icon>

Default Icon Collections

Two icon collections are available through Vaadin dependencies: Vaadin Icons and Lumo Icons. The Flow API provides enumations for these collections that makes them easy to use.

Vaadin Icons

Vaadin Icons is a collection of over six-hundred icons.

Open in a
new tab
<vaadin-icon icon="vaadin:phone"></vaadin-icon>
<vaadin-icon icon="vaadin:calendar"></vaadin-icon>
<vaadin-icon icon="vaadin:alarm"></vaadin-icon>
<vaadin-button theme="icon">
  <vaadin-icon icon="vaadin:bell"></vaadin-icon>
</vaadin-button>

The Default Icons tab contains a list of the full Vaadin Icons collection.

Lumo Icons

Lumo Icons are used in the default Lumo theme for Vaadin components.

Open in a
new tab
<vaadin-icon icon="lumo:photo"></vaadin-icon>
<vaadin-icon icon="lumo:calendar"></vaadin-icon>
<vaadin-icon icon="lumo:clock"></vaadin-icon>
<vaadin-button theme="icon">
  <vaadin-icon icon="lumo:bell"></vaadin-icon>
</vaadin-button>

Lumo Icons are rendered on a 24×24 pixel canvas, with a 16×16 pixel active area for the icon itself and 4 pixels of whitespace around the icon.

The Default Icons contains a list of the full Lumo Icons collection.

Using Third-Party Icons

Third-party icons can be rendered with the icon component. Three common formats are supported: standalone SVG files; SVG sprites; and icon fonts.

Standalone SVG Images

Standalone SVG images can be rendered as inline SVG icons using the icon component.

Open in a
new tab
<vaadin-icon src="${codeBranchIcon}"></vaadin-icon>

Thanks to inline SVG rendering, an icon can be styled with CSS. For example, you could change its fill color or stroke.

The advantage of standalone SVG images is that only the icons actually needed in the UI are loaded into the browser.

SVG Sprites

SVG sprites are SVG files containing multiple images wrapped in <symbol> tags. An id attribute on the symbol tag is used to identify the images.

Using an image from an SVG sprite is similar to using a standalone SVG image — append the symbol id to the file path, prefixed by #:

Open in a
new tab
<vaadin-icon src=${solidSprite} symbol="code-branch"></vaadin-icon>
<vaadin-icon src=${solidSprite} symbol="user"></vaadin-icon>

Like standalone SVG images, sprite icons are also rendered as inline SVG for styling support.

The advantage of using an SVG sprite is that only one file needs to be loaded into the browser. Custom SVG sprites that contain only the icons needed in the application, can provide performance benefits compared to standalone SVG images.

Many third-party tools for creating SVG sprites are available.

Icon Fonts

Icon fonts are loaded into the UI through a combination of a few factors:

  • First, a font file — usually placed in the theme folder;

  • Second, a @font-face declaration — usually in a stylesheet provided with the font and imported into your theme’s master stylesheet, styles.css; and

  • Optionally, a stylesheet with CSS classes representing the font and the icons in it — usually also imported into styles.css, which may be included in same stylesheet as the @font-face declaration.

The desired icon can be specified in three different ways, depending on the font and stylesheets provided:

  • Icon-specific CSS class (e.g., fa-calendar), which requires a stylesheet defining CSS classes for each icon, usually bundled with the icon font;

  • Ligature (e.g., calendar), which requires an icon font that supports ligatures; and

  • Character code (e.g., f199), corresponding to the code point of the icon’s glyph in the font.

Open in a
new tab
<vaadin-icon icon-class="fa fa-code-branch"></vaadin-icon>
<vaadin-icon icon-class="fa fa-user"></vaadin-icon>
themes/
  └── my-theme/
      ├── styles.css
      └── fontawesome/
          ├── fontawesome.css (classes for individual icons in the font)
          ├── solid.css (stylesheet with @font-face declaration)
          └── fa-solid-900.woff2 (icon font)
...
@import url('fontawesome/solid.css');
@import url('fontawesome/fontawesome.css');
@font-face {
  font-family: 'Font Awesome 6 Free';
  font-style: normal;
  font-weight: 900;
  font-display: block;
  src: url("fa-solid-900.woff2") format("woff2"), url("fa-solid-900.ttf") format("truetype");
}

The @font-face declaration defining the icon font family must be placed in a global stylesheet, not in a Shadow DOM stylesheet.

Note
Icon Font Stylesheets Inside a Shadow Root

To use CSS classes for icon fonts inside a Shadow DOM, such as that of a Lit template, they must be loaded separately into it. The easiest way to do this is to load them as part of the application’s theme, and apply the theme inside the Shadow DOM with applyTheme().

The font can also be defined using its font-family name — as defined in the @font-face declaration.

<vaadin-icon font-family="Material Icons" ligature="home"></vaadin-icon>

Note that the rendering quality of icon fonts is inferior to SVGs, especially in smaller sizes.

Icon Configuration

You may configure a few properties or styles for the icons.

Color & Other Styles

The icon’s fill color can be set to any CSS color value.

Open in a
new tab
<vaadin-icon src="${codeBranch}" style="color: red"></vaadin-icon>
<vaadin-icon icon-class="fa fa-user" style="color: red"></vaadin-icon>

Size & Padding

The icon component has a property for setting the desired outer size of the icon in pixels. This automatically sets the icon’s width and height to the same value, as icons are rendered in a square (i.e., 1:1) aspect ratio, by default.

Open in a
new tab
<vaadin-icon src="${codeBranch}"></vaadin-icon>
<vaadin-icon
  src="${codeBranch}"
  style="height: var(--lumo-icon-size-l); width: var(--lumo-icon-size-l);"
></vaadin-icon>
<vaadin-icon src="${codeBranch}" style="height: 48px; width: 48px;"></vaadin-icon>

The internal padding of the icon can be adjusted to compensate for the lack of surrounding whitespace in the icon itself.

Open in a
new tab
<vaadin-icon src="${codeBranch}"></vaadin-icon>
<vaadin-icon src="${codeBranch}" style="padding: 0.25em"></vaadin-icon>
<vaadin-icon src="${codeBranch}" style="padding: 0.5em"></vaadin-icon>

Custom Icon Collection APIs

Within the application context, various icon libraries — including FontAwesome, Material Symbol, and others — may be utilized. Implementing custom icon libraries, as exemplified by the VaadinIcon enumeration, simplifies developer workflows by eliminating the need to recall specific URL paths, or to remember which CSS classes to apply when working with font icons:

public enum FontAwesomeIcons {
    CODE_BRANCH("fa-code-branch"), USER("fa-user");

    private String iconClass;

    FontAwesomeIcons(String iconClass) {
        this.iconClass = iconClass;
    }

    public FontIcon create() {
        return new FontIcon("fa", iconClass);
    }
}

...

FontIcon codeBranch = FontAwesomeIcons.CODE_BRANCH.create();
add(codeBranch);

Accessibility

Screen readers are not able to announce icons correctly, by default. In fact, the icon component is built in a way that is completely ignored by assistive technologies.

However, in most cases, there shouldn’t be a need to make icons themselves screen reader friendly. Instead, the component (e.g., Button) in which the icon is used, should provide a screen reader friendly accessible name.

Open in a
new tab
<vaadin-button aria-label="Close dialog" theme="icon">
  <vaadin-icon icon="vaadin:close" slot="prefix"></vaadin-icon>
</vaadin-button>

In situations where icons are used to convey information on their own (e.g., in a table column to convey a value in a graphical manner), they need to be given an accessible name and an ARIA image role attribute in order to be announced correctly by screen readers.

<vaadin-icon icon="vaadin:star" role="img" aria-label="Favorite"></vaadin-icon>

47B97C93-9646-4D2A-882F-C4F709D3D099