View in Storybook

When to Use

Use Icon to reinforce meaning alongside text - in buttons, form fields, status messages, and navigation. Icons help users scan interfaces faster and understand actions without reading every label.

Avoid Icon for:

• Purely decorative illustrations - use an image instead
• Complex graphics or logos - use a dedicated image or SVG

Structure

The Icon component renders an SVG element with a single data prop from @equinor/eds-icons. It supports three sizing layers:

• Explicit size prop - highest priority, for precise control
• Parent Typography - automatically inherits the right size when placed inside Typography
• Dynamic fallback - scales at 1.5× relative to the surrounding font size

Guidelines

Sizes

Use the size prop for explicit sizing. Each size maps to an EDS design token, ensuring consistency across our interfaces.

Size	Spacious (default)	Comfortable (compact)
xs	16px	14px
sm	18px	16px
md	20px	18px
lg	24px	20px
xl	28px	24px
2xl	32px	28px
3xl	37px	32px
4xl	42px	37px
5xl	48px	42px
6xl	56px	48px

sm

md

lg

xl

2xl

3xl

4xl

5xl

6xl

7xl

View in Storybook

Auto-sizing with Typography

When placed inside a Typography component, icons automatically inherit the correct size via the --eds-typography-icon-size CSS variable. This is the recommended approach for icons inline with text.

Density modes

Icons respect the data-density attribute for density-aware sizing. The same size prop renders at different pixel values depending on the density context.

• Spacious (default) - larger icons for more breathing room
• Comfortable - smaller icons for compact UIs

Default sizing

When no size prop is set and the icon is outside a Typography component, it scales to 1.5× the surrounding font size. This provides a sensible default in any context.

Color

Icons inherit currentColor by default, making them adapt to text color automatically. You can also set a custom color using the color prop.

Inherits the text colour

View in Storybook

Inline text vs flex layout

How you use Icon depends on the layout context:

Context	Usage	Why
Inline text	<Icon data={save} />	Auto-sizes to 1.5em, negative margins for optical alignment
Flex/Button	<Icon data={save} size="md">	Fixed size from tokens, no margins - layout controlled by flex gap

The size prop removes negative margins, giving full control to your layout system.

Label lg with the default icon size

Label md with size="lg"

Label sm with size="md"

View in Storybook

Usage in Figma

There is no dedicated Icon component in Figma. Instead, icons are imported directly from the Assets panel.

Standalone icons — Import the icon from Assets and place it directly in your design. The icon size is controlled by the asset itself.

Inline with Typography — When placing an icon inline with text, wrap it in a container like "Leading Icon Item". This container applies negative padding to optically align the icon with the text baseline — matching how the code component behaves with negative margins for inline icons.

The container exposes variables for controlling size and negative padding:

Variable	Purpose
Selectable/Icon size	Controls the icon dimensions
Selectable/Icon container padding ↕︎	Negative vertical padding for optical alignment
Selectable/Icon container padding ↔︎	Negative horizontal padding (square containers only)

Which padding variables to use depends on the container shape:

• Rectangular containers (e.g., a button with text) — Only vertical padding (↕︎) is needed. Horizontal spacing is handled by the parent layout's gap.
• Square containers (e.g., an icon-only button) — Both vertical (↕︎) and horizontal (↔︎) padding are needed, set to the same value, since the icon fills the container in both directions.

Accessibility

Icons follow WCAG 2.1 AA guidelines with two distinct modes:

Decorative icons (no title prop)

• Rendered with aria-hidden="true"
• Hidden from screen readers entirely
• Use when the icon is accompanied by visible text that conveys the same meaning

Semantic icons (with title prop)

• Rendered with role="img" and aria-labelledby
• Announced by screen readers using the title text
• Use when the icon conveys meaning that is not available through surrounding text

Do's and Don'ts

Do

• Use title prop when an icon is the only element conveying meaning (e.g., icon-only buttons)
• Let icons inherit size from Typography when used inline with text
• Use the size prop in flex layouts where you control spacing with gap
• Rely on currentColor for icons that should match surrounding text color

Don't

• Don't use icons without a title when there is no accompanying text to convey the meaning
• Don't combine the size prop with Typography auto-sizing. The size prop takes priority and overrides the inherited size, so the Typography context has no effect
• Don't use custom pixel values for sizing - use the size prop or let tokens handle it