Label

Labels attach an accessible caption and Forge typography to a specific set of label-aware Forge components, in place of a plain HTML label element.

Label

Usage

forge-label provides an accessible caption and Forge typography for a specific set of label-aware components — button, checkbox, icon button, radio, select, switch, and button toggle groups — through for (explicit ID association), legend, and non-interactive. It isn’t a general-purpose replacement for a plain <label> — it only works when paired with one of these specific elements, so reach for a native <label> (or aria-label) when labeling anything else, including text fields, which manage their own label internally.

Rules

Only use forge-label with the specific components it supports — check the list above before reaching for it.

Nest the associated element inside the label when you don't need it to render anywhere else, instead of wiring up for/id.

Use legend when labeling a group of radios, so it reads as the group's caption rather than one option's label.

Don't

Don't use forge-label on an element it doesn't support — use a native label or aria-label instead.

Don't duplicate a label both nested and via the for attribute on the same element.

ID associated

Set for to the id of the labeled element to associate them explicitly, without nesting one inside the other.

A label explicitly associated with an element via the for attribute.

<div class="flex items-center">
  <forge-label for="my-checkbox">
    Label
  </forge-label>
  <forge-checkbox id="my-checkbox" aria-label="Label">
  </forge-checkbox>
</div>

Nested

Nest the labelable element directly inside forge-label for implicit association — no for/id pair needed.

A label implicitly associated with a nested element.

<forge-label class="flex items-center">
  <span>
    Label
  </span>
  <forge-checkbox aria-label="Label">
  </forge-checkbox>
</forge-label>

Legend

Set legend to use the label as a group caption instead of labeling one specific element — the standard pattern for a group of radios.

A label used as a legend for a radio group.

<forge-radio-group class="flex items-center" aria-label="Choose an option">
  <forge-label legend non-interactive>
    Choose an option
  </forge-label>
  <forge-radio name="default">
    Option 1
  </forge-radio>
  <forge-radio name="default">
    Option 2
  </forge-radio>
  <forge-radio name="default">
    Option 3
  </forge-radio>
</forge-radio-group>

Aligned list

Pair a label with its associated element in a list, so a set of fields lines up consistently.

Labels aligned with their associated elements in a list.

<div class="grid grid-cols-[auto_auto] items-center w-fit">
  <forge-label for="one" class="w-full">
    Item One
  </forge-label>
  <forge-checkbox id="one" aria-label="Item One">
  </forge-checkbox>
  <forge-label for="two" class="w-full">
    Item Two with a longer label
  </forge-label>
  <forge-checkbox id="two" aria-label="Item Two with a longer label">
  </forge-checkbox>
  <forge-label for="three" class="w-full">
    Item Three
  </forge-label>
  <forge-checkbox id="three" aria-label="Item Three">
  </forge-checkbox>
  <forge-label for="four" class="w-full">
    Item Four
  </forge-label>
  <forge-checkbox id="four" aria-label="Item Four">
  </forge-checkbox>
  <forge-label for="five" class="w-full">
    Item 5
  </forge-label>
  <forge-checkbox id="five" aria-label="Item 5">
  </forge-checkbox>
</div>

With icon button

Label an icon button to give it a persistent, visible caption alongside its accessible name.

A label captioning an icon button.

<forge-label class="inline-flex items-center flex-col">
  <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>

The Label component is used to associate a text label with a compatible Forge component.

import "@tylertech/forge/label";

Properties

Property	Attribute	Type	Default	Description
`for`	`for`	`string \| null \| undefined`	`null`	The id of the associated element.
`forElement`	—	`HTMLElement \| null \| undefined`	`null`	The associated element.
`clickTarget`	—	`HTMLElement \| null \| undefined`	`null`	The element that a click should be simulated on. If not defined clicks act on the associated element.
`dynamic`	`dynamic`	`boolean`	`false`	Propagates changes in the label's text content to the associated element.
`nonInteractive`	`non-interactive`	`boolean`	`false`	Removes click handling from the label.
`legend`	`legend`	`boolean`	`false`	Whether or not the label should be associated with an ancestor element.

Methods

Name	Returns	Description
`update()`	`void`	Updates the targeted element with the label's current text content.

Accessibility documentation coming soon.