Button

Buttons allow users to take actions and make choices with a single tap.

Button

Overview

Buttons communicate actions that users can take. They are typically placed throughout your UI in places such as dialogs, forms, cards, tables, toolbars, etc.

Usage

forge-button handles every level of action emphasis through variant, size, and theme, plus icons, anchor navigation, loading, and disabled states. Pick the variant that matches an action’s importance, reserve filled for the one primary action per view, and let theme, icon, and state carry the rest.

Rules

Use sentence case ("Start new").

Use short, actionable verbs ("Submit", "Save", "Delete").

Use the primary theme color.

One filled button per group, placed at the end (right).

Space adjacent buttons with --forge-spacing-medium (--forge-spacing-xsmall in dense layouts).

Don't

Don't use more than one filled button per page or dialog.

Don't put two filled buttons next to each other.

Don't use success or warning colors — use primary.

Don't pair overlapping actions ("Start over" + "Cancel").

Variants

Pick one variant per action, based on its level. Filled is the primary action — never more than one per page or dialog. Tonal is for secondary actions, and text is for tertiary actions like dismiss or skip. Outlined and raised are available but aren’t part of this hierarchy; see Grouping for how to combine levels.

The four button variants, ordered from lowest to highest emphasis.

<forge-button>
  Text
</forge-button>
<forge-button variant="outlined">
  Outlined
</forge-button>
<forge-button variant="tonal">
  Tonal
</forge-button>
<forge-button variant="filled">
  Filled
</forge-button>
<forge-button variant="raised">
  Raised
</forge-button>
<forge-button variant="link">
  Link
</forge-button>

Theme

Buttons default to the primary theme. Use theme="error" for destructive confirmations. Success and warning themes exist but should be reserved for status-conveying actions inside toolbars or lists — never for the primary submit on a form.

Primary is the default. Reserve error for destructive actions; the remaining themes exist but should be used sparingly.

<forge-button variant="raised">
  Primary
</forge-button>
<forge-button theme="secondary" variant="raised">
  Secondary
</forge-button>
<forge-button theme="tertiary" variant="raised">
  Tertiary
</forge-button>
<forge-button theme="success" variant="raised">
  Success
</forge-button>
<forge-button theme="warning" variant="raised">
  Warning
</forge-button>
<forge-button theme="error" variant="raised">
  Error
</forge-button>
<forge-button theme="info" variant="raised">
  Info
</forge-button>

Grouping

Buttons in a group follow an action hierarchy. Give each action a level, then use the matching variant:

Primary uses filled. This is the single main action. Use at most one per page or dialog.
Secondary uses tonal. This is an alternative to the primary action.
Tertiary uses text. This is a low-emphasis action.

Order buttons by level from right to left: primary at the end (right), secondary to its left, and tertiary leftmost. Space buttons with --forge-spacing-medium. For a destructive action, keep its level and add theme="error". Groups have at most 3 buttons; move any extra actions into a forge-menu.

Action levels

Level	Variant	Position
Primary	`filled`	Rightmost (end)
Secondary	`tonal`	Left of primary
Tertiary	`text`	Leftmost

Combinations

Actions	Layout (left to right)	Example
Primary + secondary (default)	`tonal`, `filled`	Cancel, Save
Primary + tertiary	`text`, `filled`	Skip, Continue
Primary + secondary + tertiary	`text`, `tonal`, `filled`	Cancel, Save draft, Submit
Secondary + tertiary	`text`, `tonal`	Dismiss, View details
Destructive primary	`tonal`, `filled` + `theme="error"`	Cancel, Delete

As a link

Wrap an <a> in a forge-button to get a navigation link styled as a button. Use this sparingly — buttons imply action, links imply navigation. If the action is “go somewhere”, prefer a plain link.

A button that navigates. Note the anchor child.

<forge-button variant="raised">
  <a href="javascript: void(0);">
    Anchor button
    <forge-icon slot="end" name="open_in_new">
    </forge-icon>
  </a>
</forge-button>

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

With an icon

Wrap an <forge-icon> in a forge-button to add an icon to the button. Icons can be placed at the start or end of the button label to reinforce the action.

Icons go in the start slot for actions, end slot for directional cues.

<forge-button variant="raised">
  <forge-icon name="forge_logo" slot="start" external>
  </forge-icon>
  Button
</forge-button>

Loading

Forge doesn’t ship a built-in loading state on forge-button. To indicate a pending action, swap in a forge-circular-progress alongside the label.

A spinner in the end slot conveys a pending action.

<forge-button variant="raised">
  Loading...
  <forge-circular-progress slot="end" aria-label="Loading something important">
  </forge-circular-progress>
</forge-button>

Disabled

Set disabled to remove a button from the tab order and prevent interaction — every variant supports it.

Every variant supports disabled.

<forge-button disabled>
  Text
</forge-button>
<forge-button variant="outlined" disabled>
  Outlined
</forge-button>
<forge-button variant="tonal" disabled>
  Tonal
</forge-button>
<forge-button variant="raised" disabled>
  Raised
</forge-button>

Buttons are used when a user needs to take an action. They can be used to trigger an action, navigate to a new location, and can be styled with a variety of themes and variants.

import "@tylertech/forge/button";

Properties

Property	Attribute	Type	Default	Description
`variant`	`variant`	`ButtonVariant`	`'text'`	Gets/sets the button variant.
`pill`	`pill`	`boolean`	`false`	Gets/sets whether the button is pill-shaped.
`theme`	`theme`	`ButtonTheme`	`'primary'`	Gets/sets the button theme.
`fullWidth`	`full-width`	`boolean`	`false`	Gets/sets whether the button is full-width.
`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.

Slots

Name	Description
`(default)`	This is a default/unnamed slot for the label text.
`start`	Elements to logically render before the label text.
`end`	Elements to logically render after the label text.

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-button-primary-color`	The primary color of the button.
`--forge-button-text-color`	The text color of the button. Inherits from primary color.
`--forge-button-disabled-color`	The disabled color of the button.
`--forge-button-padding`	The padding of the button.
`--forge-button-display`	The display of the button.
`--forge-button-justify`	The flex justify of the button.
`--forge-button-shape`	The shape of the button.
`--forge-button-height`	The height of the button.
`--forge-button-min-width`	The min-width of the button.
`--forge-button-spacing`	The spacing of the button.
`--forge-button-border-width`	The border-width of the button.
`--forge-button-border-style`	The border style of the button.
`--forge-button-border-color`	The border color of the button.
`--forge-button-shape-start-start-radius`	The shape start start radius of the button.
`--forge-button-shape-start-end-radius`	The shape start end radius of the button.
`--forge-button-shape-end-start-radius`	The shape end start radius of the button.
`--forge-button-shape-end-end-radius`	The shape end end radius of the button.
`--forge-button-padding-block`	The padding block of the button.
`--forge-button-padding-inline`	The padding inline of the button.
`--forge-button-background`	The background color of the button.
`--forge-button-hover-background`	The background color of the button on hover.
`--forge-button-active-background`	The background color of the button on active state.
`--forge-button-color`	The text color of the button.
`--forge-button-icon-size`	The size of the icon in the button.
`--forge-button-shadow`	The shadow of the button.
`--forge-button-hover-shadow`	The shadow of the button on hover.
`--forge-button-active-shadow`	The shadow of the button on active state.
`--forge-button-cursor`	The cursor type of the button.
`--forge-button-transition-duration`	The transition duration of the button.
`--forge-button-transition-timing`	The transition timing of the button.
`--forge-button-text-padding-inline`	The inline padding of the button when using the text variant.
`--forge-button-filled-background`	The background color of the filled button.
`--forge-button-filled-disabled-background`	The background color of the disabled filled button.
`--forge-button-filled-color`	The text color of the filled button.
`--forge-button-filled-disabled-color`	The text color of the disabled filled button.
`--forge-button-raised-background`	The background color of the raised button.
`--forge-button-raised-disabled-background`	The background color of the disabled raised button.
`--forge-button-raised-color`	The text color of the raised button.
`--forge-button-raised-disabled-color`	The text color of the disabled raised button.
`--forge-button-raised-shadow`	The shadow of the raised button.
`--forge-button-raised-hover-shadow`	The shadow of the raised button on hover.
`--forge-button-raised-active-shadow`	The shadow of the raised button on active state.
`--forge-button-raised-disabled-shadow`	The shadow of the disabled raised button.
`--forge-button-flat-background`	The background color of the flat button.
`--forge-button-flat-disabled-background`	The background color of the disabled flat button.
`--forge-button-flat-color`	The text color of the flat button.
`--forge-button-flat-disabled-color`	The text color of the disabled flat button.
`--forge-button-outlined-background`	The background color of the outlined button.
`--forge-button-outlined-color`	The text color of the outlined button.
`--forge-button-outlined-border-width`	The border width of the outlined button.
`--forge-button-outlined-border-style`	The border style of the outlined button.
`--forge-button-outlined-border-color`	The border color of the outlined button.
`--forge-button-link-color`	The text color of the link button.
`--forge-button-link-text-decoration`	The text decoration of the link button.
`--forge-button-link-height`	The height of the link button.
`--forge-button-link-padding`	The padding of the link button.
`--forge-button-link-line-height`	The line height of the link button.
`--forge-button-link-width`	The width of the link button.
`--forge-button-link-hover-text-decoration`	The text decoration of the link button on hover.
`--forge-button-link-active-opacity`	The opacity of the link button on active state.
`--forge-button-link-transition-duration`	The transition duration of the link button.
`--forge-button-link-transition-timing`	The transition timing of the link button.
`--forge-button-disabled-cursor`	The cursor type of the disabled button.
`--forge-button-disabled-text-color`	The text color of the disabled button.
`--forge-button-disabled-background`	The background color of the disabled button.
`--forge-button-disabled-border-color`	The border color of the disabled button.
`--forge-button-disabled-shadow`	The shadow of the disabled button.
`--forge-button-dense-height`	The height of the dense button.
`--forge-button-pill-shape`	The shape of the pill button.
`--forge-button-pill-padding-inline`	The inline padding of the pill button.

Methods

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

Keyboard interaction

Every button must be reachable by keyboard, with a visible focus indicator, and pressing Space or Enter while focused must activate it the same as a mouse click.

Accessible name

Give every button a visible label describing the action it performs. When there’s no visible text — an icon-only button — provide one via aria-label instead.

Contrast

Button text and its background must meet WCAG contrast requirements.