Icon Button

Icon buttons are buttons that contain only an icon, and are used to represent actions or commands.

Overview

Icon buttons communicate actions using visual icons instead of text labels. They pair with tooltips which show the action name for clarity and should be placed close to the content they act on. Icon buttons are ideal for saving space while maintaining functionality.

Usage

forge-icon-button handles action emphasis through variant, theme, shape, and density, plus toggle, anchor, and badge support. Since there’s no visible label, always set an accessible name with aria-label and pair the button with a tooltip so its action is clear on hover or focus. Reach for a text button instead when the action isn’t widely recognizable from an icon alone.

Rules

Use icon buttons for globally familiar, easily recognized actions (undo, edit, save, close).

Always set an accessible label with aria-label, since the button has no visible text.

Pair an icon button with a tooltip so its action is clear without relying on the icon alone.

Don't

Don't use when the icon meaning might be ambiguous to users.

Don't use when actions require a detailed explanation that can't be conveyed through a simple icon and tooltip.

Don't use an icon button for a domain-specific or unfamiliar action — use a text button instead.

Don't mix icon buttons and text buttons within the same group or table row.

Variants

Pick the variant that matches the action’s emphasis, same as a text button: icon (the default, lowest emphasis) for most toolbar and row-level actions, outlined or tonal for secondary emphasis, filled for a stronger fill, and raised for the one primary action in a view.

The five icon button variants, ordered from lowest to highest emphasis.

<forge-icon-button aria-label="Default icon button">
  <forge-icon name="favorite">
  </forge-icon>
</forge-icon-button>
<forge-icon-button variant="outlined" aria-label="Outlined icon button">
  <forge-icon name="favorite">
  </forge-icon>
</forge-icon-button>
<forge-icon-button variant="tonal" aria-label="Tonal icon button">
  <forge-icon name="favorite">
  </forge-icon>
</forge-icon-button>
<forge-icon-button variant="filled" aria-label="Filled icon button">
  <forge-icon name="favorite">
  </forge-icon>
</forge-icon-button>
<forge-icon-button variant="raised" aria-label="Raised icon button">
  <forge-icon name="favorite">
  </forge-icon>
</forge-icon-button>

<script type="module">
import { IconRegistry } from "@tylertech/forge/icon";
import { tylIconFavorite } from "@tylertech/tyler-icons";
IconRegistry.define([tylIconFavorite]);
</script>

Theme

Icon buttons default to a neutral theme. Set theme to a semantic or brand color to reinforce the action’s meaning.

Every theme available on an icon button.

<forge-icon-button aria-label="Default theme icon button" variant="icon">
  <forge-icon name="forge_logo">
  </forge-icon>
</forge-icon-button>
<forge-icon-button theme="primary" aria-label="Primary theme icon button" variant="icon">
  <forge-icon name="forge_logo">
  </forge-icon>
</forge-icon-button>
<forge-icon-button theme="secondary" aria-label="Secondary theme icon button" variant="icon">
  <forge-icon name="forge_logo">
  </forge-icon>
</forge-icon-button>
<forge-icon-button theme="tertiary" aria-label="Tertiary theme icon button" variant="icon">
  <forge-icon name="forge_logo">
  </forge-icon>
</forge-icon-button>
<forge-icon-button theme="success" aria-label="Success theme icon button" variant="icon">
  <forge-icon name="forge_logo">
  </forge-icon>
</forge-icon-button>
<forge-icon-button theme="warning" aria-label="Warning theme icon button" variant="icon">
  <forge-icon name="forge_logo">
  </forge-icon>
</forge-icon-button>
<forge-icon-button theme="error" aria-label="Error theme icon button" variant="icon">
  <forge-icon name="forge_logo">
  </forge-icon>
</forge-icon-button>
<forge-icon-button theme="info" aria-label="Info theme icon button" variant="icon">
  <forge-icon name="forge_logo">
  </forge-icon>
</forge-icon-button>

<script type="module">
import { IconRegistry } from "@tylertech/forge/icon";
import { tylIconForgeLogo } from "@tylertech/tyler-icons";
IconRegistry.define([tylIconForgeLogo]);
</script>

Toggle

Set toggle for an icon button that represents a persistent on/off state — such as marking a favorite — and provide an on slot icon to swap in when pressed is true. Any icon can technically fill either slot, but the convention is an outlined-style icon for the default “off” state and a filled-style version of the same icon for the “on” slot, so the visual weight itself reinforces the state change.

A toggle icon button in each variant, swapping icons between its default and on slot.

<forge-icon-button toggle aria-label="Default toggle icon button">
  <forge-icon name="favorite_border">
  </forge-icon>
  <forge-icon slot="on" name="favorite">
  </forge-icon>
</forge-icon-button>
<forge-icon-button toggle variant="outlined" aria-label="Outlined toggle icon button">
  <forge-icon name="favorite_border">
  </forge-icon>
  <forge-icon slot="on" name="favorite">
  </forge-icon>
</forge-icon-button>
<forge-icon-button toggle variant="tonal" aria-label="Tonal toggle icon button">
  <forge-icon name="favorite_border">
  </forge-icon>
  <forge-icon slot="on" name="favorite">
  </forge-icon>
</forge-icon-button>
<forge-icon-button toggle variant="filled" aria-label="Filled toggle icon button">
  <forge-icon name="favorite_border">
  </forge-icon>
  <forge-icon slot="on" name="favorite">
  </forge-icon>
</forge-icon-button>
<forge-icon-button toggle variant="raised" aria-label="Raised toggle icon button">
  <forge-icon name="favorite_border">
  </forge-icon>
  <forge-icon slot="on" name="favorite">
  </forge-icon>
</forge-icon-button>

<script type="module">
import { IconRegistry } from "@tylertech/forge/icon";
import { tylIconFavorite, tylIconFavoriteBorder } from "@tylertech/tyler-icons";
IconRegistry.define([tylIconFavorite, tylIconFavoriteBorder]);
</script>

As a link

Wrap an <a> inside a forge-icon-button to get a navigation link styled as an icon button.

An icon button that navigates. Note the anchor child.

<forge-icon-button>
  <a href="javascript: alert('Icon button with anchor works!');" aria-label="Anchor link icon button">
    <forge-icon name="open_in_new">
    </forge-icon>
  </a>
</forge-icon-button>

<script type="module">
import { IconRegistry } from "@tylertech/forge/icon";
import { tylIconOpenInNew } from "@tylertech/tyler-icons";
IconRegistry.define([tylIconOpenInNew]);
</script>

With a badge

Pass a badge into the badge slot to overlay a count or dot indicator, most often for unread or new content.

A numeric badge overlaid on an icon button.

<forge-icon-button aria-label="Icon button with badge">
  <forge-icon name="notifications">
  </forge-icon>
  <forge-badge slot="badge" theme="default">
    3
  </forge-badge>
</forge-icon-button>

<script type="module">
import { IconRegistry } from "@tylertech/forge/icon";
import { tylIconNotifications } from "@tylertech/tyler-icons";
IconRegistry.define([tylIconNotifications]);
</script>

Loading

Swap in a forge-circular-progress in place of the icon to indicate a pending action.

A circular progress indicator replaces the icon while the action is pending.

<forge-icon-button aria-label="Loading">
  <forge-circular-progress aria-label="Progress label">
  </forge-circular-progress>
</forge-icon-button>

Label aware

Wrap an icon button in a forge-label to give it a persistent, visible caption alongside its accessible label — useful when an icon alone may not be immediately familiar to every user.

A forge-label caption sits beneath the icon button.

<forge-label style="display: flex; flex-direction: column; width: min-content; align-items: center;">
  <forge-icon-button aria-label="Settings">
    <forge-icon name="settings">
    </forge-icon>
  </forge-icon-button>
  <span>
    Settings
  </span>
</forge-label>

<script type="module">
import { IconRegistry } from "@tylertech/forge/icon";
import { tylIconSettings } from "@tylertech/tyler-icons";
IconRegistry.define([tylIconSettings]);
</script>

Icon buttons are buttons that contain **only** an icon, and are used to represent actions or commands. Always provide an accessible label when using icon buttons.

import "@tylertech/forge/icon-button";

Properties

Property	Attribute	Type	Default	Description
`toggle`	`toggle`	`boolean`	`false`	Gets/sets whether the icon button can be toggled.
`pressed`	`pressed`	`boolean`	`false`	Gets/sets whether the toggle button is pressed. Only applies when `toggle` is `true`.
`on`	`on`	`unknown`	`false`	Alias for `pressed` _(deprecated)_. Whether or not the toggle button is pressed. Only applies when `toggle` is `true`.
`variant`	`variant`	`IconButtonVariant`	`"icon"`	Gets/sets the variant of the button. Valid values are `text`, `outlined`, `filled`, and `raised`.
`theme`	`theme`	`IconButtonTheme`	`"default"`	Gets/sets the theme of the button. Valid values are `text`, `outlined`, `filled`, and `raised`.
`shape`	`shape`	`IconButtonShape`	`"circular"`	Gets/sets the shape of the button. Valid values are `circular` and `squared`.
`density`	`density`	`IconButtonDensity`	`"large"`	Gets/sets the density of the button. Valid values are `small`, `medium`, and `large`.
`type`	`type`	`ButtonType`	`'button'`	Gets/sets the type of button.
`disabled`	`disabled`	`boolean`	`false`	Gets/sets whether the button is disabled.
`dense`	`dense`	`boolean`	`false`	Gets/sets whether the button is dense.
`popoverIcon`	`popover-icon`	`boolean`	`false`	Gets/sets whether to show a popover icon.
`name`	`name`	`string`	`''`	Gets/sets the button name for form association.
`value`	`value`	`string`	`''`	Gets/sets the button value for form submission.
`command`	`command`	`CommandType`	`''`	Indicates to the targeted element which action to take.
`commandFor`	`command-for`	`string`	`''`	Targets another element to be invoked.
`commandForElement`	—	`HTMLElement \| undefined`	`undefined`	Targets another element to be invoked.

Events

Name	Type	Description
`click`	`PointerEvent`	Fires when the button is clicked.
`forge-icon-button-toggle`	`CustomEvent<boolean>`	Fires when the icon button is toggled. Only applies in `toggle` mode.

Slots

Name	Description
`(default)`	This is a default/unnamed slot for the icon.
`on`	The icon to show when in `toggle` mode when toggled "on".
`start`	Elements to logically render before the icon.
`end`	Elements to logically render after the icon.
`badge`	Absolutely positions the element in the top-end corner of the button (typically reserved for badge-like content).

CSS Parts

Name	Description
`::part(root)`	The root container element.
`::part(focus-indicator)`	The focus-indicator indicator element.
`::part(state-layer)`	The state-layer surface element.

CSS Custom Properties

Name	Description
`--forge-icon-button-display`	The display property of the button.
`--forge-icon-button-size`	The height and min-width of the button.
`--forge-icon-button-gap`	The gap between the icon content.
`--forge-icon-button-icon-color`	The color of the icon.
`--forge-icon-button-background-color`	The background color of the button.
`--forge-icon-button-icon-size`	The size of the icon.
`--forge-icon-button-cursor`	The cursor of the button.
`--forge-icon-button-padding`	The inline padding of the button.
`--forge-icon-button-border`	The border of the button.
`--forge-icon-button-shadow`	The shadow of the button.
`--forge-icon-button-transition-duration`	The transition duration of the button.
`--forge-icon-button-transition-timing`	The transition timing of the button.
`--forge-icon-button-shape`	The shape of the button.
`--forge-icon-button-shape-start-start`	The start-start border-radius of the button.
`--forge-icon-button-shape-start-end`	The start-end border-radius of the button.
`--forge-icon-button-shape-end-start`	The end-start border-radius of the button.
`--forge-icon-button-shape-end-end`	The end-end border-radius of the button.
`--forge-icon-button-shape-squared`	The squared border-radius of the button.
`--forge-icon-button-outlined-border-width`	The border width when in the outlined variant.
`--forge-icon-button-outlined-border-style`	The border style when in the outlined variant.
`--forge-icon-button-outlined-border-color`	The border color when in the outlined variant.
`--forge-icon-button-tonal-icon-color`	The icon color when in the tonal variant.
`--forge-icon-button-tonal-background-color`	The background color when in the tonal variant.
`--forge-icon-button-filled-icon-color`	The icon color when in the filled variant.
`--forge-icon-button-filled-background-color`	The background color when in the filled variant.
`--forge-icon-button-raised-shadow`	The shadow when in the raised variant.
`--forge-icon-button-raised-hover-shadow`	The shadow when in the raised variant and hovered.
`--forge-icon-button-raised-active-shadow`	The shadow when in the raised variant and active.
`--forge-icon-button-raised-disabled-shadow`	The shadow when in the raised variant and disabled.
`--forge-icon-button-density-small-size`	The size of the button when in the small density.
`--forge-icon-button-density-small-padding`	The padding of the button when in the small density.
`--forge-icon-button-density-small-icon-size`	The size of the icon when in the small density.
`--forge-icon-button-density-medium-size`	The size of the button when in the medium density.
`--forge-icon-button-density-medium-padding`	The padding of the button when in the medium density.
`--forge-icon-button-density-large-size`	The size of the button when in the large density.
`--forge-icon-button-toggle-on-background-color`	The background color of the when in toggle mode and toggled on.
`--forge-icon-button-toggle-on-icon-color`	The color of the icon when in toggle mode and toggled on.
`--forge-icon-button-outlined-toggle-on-background-color`	The background color when in the outlined variant and toggled on.
`--forge-icon-button-outlined-toggle-on-icon-color`	The icon color when in the outlined variant and toggled on.
`--forge-icon-button-tonal-toggle-background-color`	The background color when in the tonal variant and toggled.
`--forge-icon-button-tonal-toggle-on-background-color`	The background color when in the tonal variant and toggled on.
`--forge-icon-button-tonal-toggle-on-icon-color`	The icon color when in the tonal variant and toggled on.
`--forge-icon-button-filled-toggle-background-color`	The background color when in the filled variant and toggled.
`--forge-icon-button-filled-toggle-icon-color`	The icon color when in the filled variant and toggled.
`--forge-icon-button-filled-toggle-on-background-color`	The background color when in the filled variant and toggled on.
`--forge-icon-button-filled-toggle-on-icon-color`	The icon color when in the filled variant and toggled on.
`--forge-icon-button-disabled-cursor`	The cursor when the button is disabled.
`--forge-icon-button-disabled-opacity`	The opacity when the button is disabled.
`--forge-icon-button-popover-icon-padding`	The padding of the popover icon.
`--forge-icon-button-focus-indicator-color`	The color of the focus indicator.

Methods

Name	Returns	Description
`click()`	`void`
`focus(options)`	`void`

Labeling and keyboard activation

Make sure every icon button can be reached by keyboard navigation, with a visible focus cue.
Give it an aria-label or aria-labelledby describing its purpose — an icon alone isn’t enough for assistive technology.
Pressing Space or Enter while an icon button is focused should activate it the same way a mouse click would.
If color is used to convey state (like a toggled-on state), pair it with an additional cue for users with color perception deficiencies.