The page navigation is complete. You may now navigate the page content as you wish.
Skip to main content

Icon

Added in v4.9.0
Figma GitHub

Displays an icon from the Helios icon library to enhance the communication of text and UI elements.

What is an icon

An icon is used to provide additional meaning to text and, in some rare contexts, meaning on its own.

You can see all the available icons ("glyphs") in our icon library, also known as Flight Icons library.

Types

There are four types of icons: Outlined, Filled, Off, and Contained.

Outlined

Outlined icons are icons with a standard outline.

Use Outlined icons by default.

Example of outlined icons

Filled

Filled icons are icons with a solid fill and are indicated by -fill in the icon name.

Use Filled icons to show a toggled state or for contrast with Outlined icons.

Example of filled icons

Indicating a toggled state

For objects that can be toggled on/off, show the Outlined icon for off and the Filled icon for on.

Example of toggled state icons

Using for contrast

If contrast against other icons is important, use Filled for the more important icon(s).

For example, when showing one failure in a list of 20 otherwise successful builds, use x-square-fill while keeping the remaining icons in the Outlined style so the failure is more prominent.

Example of contrasting icons

Off

Off icons are icons including a strike-through and are indicated by -off in the icon name.

Use Off icons to indicate something is disabled, unavailable, or will return a toggled icon off.

Example of off icons

Indicating a disabled or unavailable icon

When needing to indicate an action is disabled or unavailable, consider pairing an Off icon with the color style Foreground/Disabled and cursor property value not-allowed.

Return toggled state back off

If an object is toggled on and it can be toggled off, consider showing the Off icon on hover to indicate that clicking the icon again will toggle the object back off.

Example of toggling icons off

Contained

Contained icons are icons with a containing shape and are indicated by their shape type in the icon name, e.g., -circle, -square, etc.

Use contained icons for emphasis in the hierarchy.

Examples of contained icons

If an object can have multiple states, use a Contained icon for the overall parent state and the Outlined icon(s) for the children’s state(s).

Example of contained icons in context

Animated

Animated icons are icons with an animated effect that show a transition between two states.

Example of animated icons

Use animated icons to communicate activity happening in the background. For example, when an object is updated, the loading icon could appear after the save action is triggered, indicating that the changes are in progress.

Example of best practice for animated icons

Sizes

Icons are optimized for two icon sizes: 16px and 24px.

Use 16px icons by default in product interfaces and 24px icons for empty states.

Resizing icons

There may be cases where 16px and 24px sizes don’t fit a design. Icons can be resized but be aware that the design is not optimized for resizing. Therefore, only resize icons as necessary and sparingly.

Example of available icon sizes

States

Icons frequently represent different states within product interfaces, most commonly as states of an object or states of feedback.

States of an object

Some objects can return a state, e.g., a Build, Run, Cluster, etc. Objects are typically displayed in lists or as cards and include their state when presented to the user.

Examples of object states

States of feedback

Feedback is presented in response to user interaction, such as a displaying a success message after submitting a form or a warning when a user nears their usage limit.

Examples of feedback states

Common icons

Some icons represent common actions within our products.

Editing actions

Examples of common edit icons

Examples of common navigation icons

Help actions

  • Use learn-link when linking to tutorials.

  • Use docs-link when linking to documentation pages and installation guides.

  • Use support when referencing HashiCorp support.

Examples of common help icons

How to use this component

The most basic invocation of the Icon component requires only the @name property to be passed with a value matching an existing name in the Icon library:

<Hds::Icon @name="alert-circle" />

It renders to this (where the id will be unique each time):

<svg
  id="icon-ember115"
  class="hds-icon icon-alert-circle"
  width="16"
  height="16"
  viewBox="0 0 16 16"
  xmlns="http://www.w3.org/2000/svg"
  fill="currentColor"
  aria-hidden="true"
  data-test-icon="alert-circle"
>
  <use href="/@hashicorp/flight-icons/icons/sprite.svg#alert-circle-16"></use>
</svg>

Because the icons are hidden to assistive technology, they cannot be used on their own and must be used inside of an element with an accessible name. See the Accessibility section for more details on how to best use this component in different contexts.

Size

The default size is 16px. To use the alternative 24px icon size, set the @size value:

<Hds::Icon @name="zap" @size="24" />

Color

The default value is currentColor which uses the inherited text color as the icon color. When setting a custom value, we recommend using one of the pre-defined variables to ensure consistency with our design language:

<Hds::Icon @name="zap" @color="var(--token-color-foreground-success)" />

Other accepted values include named colors and color values themselves (e.g., hex, rgb, etc).

<Hds::Icon @name="zap" @color="rebeccapurple" />

<Hds::Icon @name="zap" @color="rgb(46, 113, 229)" />

Stretched

To have the icon fill the parent container (width: 100%, height: 100%), set the @stretched attribute to true:

<div class="doc-icon-demo--constrain-max-width">
  <Hds::Icon @name="zap" @size="24" @stretched={{true}} />
</div>

Block vs. inline display

To change the default display from block to inline-block, set @isInline to true:

<Hds::Icon @name="triangle" @isInline={{true}} />
<Hds::Icon @name="triangle-fill" @isInline={{true}} />

Aligning icons

Because the Hds::Icon component has a block display value by default (changeable using the @isInline argument), the icon behaves like a block element. So, if you want to horizontally align it in relation to other sibling elements, you will have to use CSS to achieve the expected result.

For example, to visually center an icon with a generic text node, you will need to use a parent flex container with align-items: center.

Avoid using vertical-align: middle

Just setting vertical-align: middle in the parent container doesn’t necessarily achieve a vertical alignment.

This is because the middle alignment is not calculated in relation to the whole text “block” but to its “x-height”. To learn more, read about how vertical-align works in CSS.

Animated icons

The loading and running icons are animated by default, meaning no additional properties are needed:

<Hds::Icon @name="loading" @size="24" />

If you need the non-animated version of these icons, use the corresponding loading-static and running-static:

<Hds::Icon @name="loading-static" @size="24" />

Note on accessibility

A prefers-reduced-motion media query will automatically disable the animation if users set this preference in their environment.

Component API

name string
Required
The name of the icon you wish to use. If the value does not match an existing icon name, an error will be thrown. Search for existing icon names in the Icon library.
color string
  • currentColor (default)
The @color argument can be used to change the color. It works by setting the value of the icon SVG’s fill property.
size number
  • 16 (default)
  • 24
Sets the size of the icon in pixels. Only two sizes are supported. (Setting a non-standard size will cause the SVG to render at the specified size but it will be invisible.)
stretched boolean
  • false (default)
Determines whether the icon will stretch to fill the parent container. Setting it to true will make the icon have a height and width of 100%.
isInline boolean
  • false (default)
Sets the display style for the icon. Setting it to true will make the icon have a display of inline-block.
title string
Use to add accessible text to standalone icons. This will also change the aria-hidden value to false instead of the default value of true.

Conformance rating

Conformant

When used as recommended, there should not be any accessibility issues with this component.

Browser accessibility support

Accessibility support for SVGs is inconsistent across browsers and assistive technology. Currently, the best practice is to set the aria-hidden attribute to true on the SVG itself (as we do by default for the Hds::Icon component). This means that the icon (both the singular icon and the icon component) will need to be used in context. The icons themselves are for presentation purposes only and should never be used on their own.

<h2>
  Activity report <Hds::Icon @name="activity" />
</h2>

If you make a custom element, or want to use a Hds::Icon inside of a native HTML element like a <button> element, ensure that an aria-label attribute is added, like this:

<button aria-label="Check activity">
  <Hds::Icon @name="activity" />
</button>

Resources

Here is a list of resources that are associated with our HDS icon component.

Icon Library

A list of all icons our component supports.

Go to Icon library

Figma library

For internal use only, the Figma library of icons that designers can leverage in their designs.

Go to Figma library

SVG assets

A ZIP file containing all SVG assets of our icons.

Download SVG assets

HDS support

If you are unable to find a specific icon, or notice a problem with an existing one, reach out to HDS support.

Request an icon or report an issue

4.9.0

Added

Added the Hds::Icon component. It replaces the FlightIcon component.

In the process of converting the FlightIcon component to the Hds::Icon component, we have taken the decision to change the default default layout from display: inline-block to display: block, and to rename the argument that control this option from @isInlineBlock to @isInline.

This RFC document highlights the reasons for this choice: DS-083: Migrate FlightIcon Component into HDS.

How to migrate

We now recommend migrating the existing FlightIcon instances to the Hds::Icon component.

You can automate this migration using the codemod v4/icon (see readme file). This codemod provides also a special flag to preserve the old display layout for the icon (but we suggest to avoid using it, it's likely not needed at all).

If you have already started to use the FlightIconSignature in TypeScript, you will have to replace the signature with the equivalent HdsIconSignature (note: the isInlineBlock argument has now become isInline)

Related

On this page: