Design System

Button Icon

Soft

Soft is the default variant. The button has a permanent neutralLight background with hover and active overlays. Use soft when the button needs to be visually present at rest, for example a toolbar where all actions should be equally discoverable.

1
<Inline
2
    space="small"
3
    alignY="center">
4
    <ButtonIcon
5
        icon="magnifying-glass"
6
        label="Search"
7
    />
8
    <ButtonIcon
9
        icon="envelope"
10
        label="Contact"
11
    />
12
    <ButtonIcon
13
        icon="rss"
14
        label="RSS feed"
15
    />
16
    <ButtonIcon
17
        icon="books"
18
        label="Reading list"
19
    />
20
</Inline>

Transparent

Transparent has no background at rest. The circular surface only appears on hover and active, making the icon appear to float in the layout. Bleed is automatically applied for transparent buttons, removing the padding from layout flow while keeping the full touch target. The icon aligns flush with surrounding text and other elements.

1
<Inline
2
    space="small"
3
    alignY="center">
4
    <ButtonIcon
5
        icon="list"
6
        label="Open menu"
7
        variant="transparent"
8
    />
9
    <ButtonIcon
10
        icon="close"
11
        label="Close"
12
        variant="transparent"
13
    />
14
    <ButtonIcon
15
        icon="magnifying-glass"
16
        label="Search"
17
        variant="transparent"
18
    />
19
</Inline>

Ghost

Ghost has no background and no hover or active circle. Only the press animation fires on click. Use ghost when you want interaction feedback without any visible surface at rest or on hover, for example alongside plain text links in a navigation bar.

1
<Inline
2
    space="small"
3
    alignY="center">
4
    <ButtonIcon
5
        icon="magnifying-glass"
6
        label="Search"
7
        variant="ghost"
8
    />
9
    <ButtonIcon
10
        icon="envelope"
11
        label="Contact"
12
        variant="ghost"
13
    />
14
    <ButtonIcon
15
        icon="rss"
16
        label="RSS feed"
17
        variant="ghost"
18
    />
19
</Inline>

Sizes

Three sizes: small (4px padding), standard (6px padding, default), large (6px padding with a larger icon). The touch target is always expanded to a minimum of 44×44px via a ::after pseudo-element regardless of visual size.

1
<Inline
2
    space="moderate"
3
    alignY="center">
4
    <ButtonIcon
5
        icon="magnifying-glass"
6
        label="Search"
7
        size="small"
8
    />
9
    <ButtonIcon
10
        icon="magnifying-glass"
11
        label="Search"
12
        size="standard"
13
    />
14
    <ButtonIcon
15
        icon="magnifying-glass"
16
        label="Search"
17
        size="large"
18
    />
19
</Inline>

Disabled

Disabled buttons are non-interactive and visually dimmed. Both variants support the disabled state.

1
<Inline
2
    space="small"
3
    alignY="center">
4
    <ButtonIcon
5
        icon="magnifying-glass"
6
        label="Search"
7
        disabled
8
    />
9
    <ButtonIcon
10
        icon="magnifying-glass"
11
        label="Search"
12
        variant="transparent"
13
        disabled
14
    />
15
</Inline>

Invoker commands

The commandFor and command props wire ButtonIcon to any dialog or popover by ID using the HTML Invoker Commands API. Here a transparent ButtonIcon opens MobileNavigation. This is the same pattern used in the site header.

1
<ButtonIcon
2
    icon="list"
3
    label="Open navigation menu"
4
    variant="transparent"
5
    commandFor="demo-mobile-navigation"
6
    command="show-modal"
7
/>
8

9
<MobileNavigation
10
    id="demo-mobile-navigation"
11
    title="Lloyd Atkinson"
12
    links={[
13
        { title: 'Articles', to: '/articles/' },
14
        { title: 'Notes', to: '/notes/' },
15
        { title: 'Speaking', to: '/speaking/' },
16
        { title: 'About', to: '/about/' },
17
    ]}
18
    iconLinks={[
19
        { title: 'Read', to: '/reading/', icon: 'books' },
20
        { title: 'RSS Feed', to: '/rss.xml', icon: 'rss' },
21
        { title: 'Contact', to: '/inbox/', icon: 'envelope' },
22
    ]}
23
/>