Field Label

For development, import FieldLabel from @servicetitan/anvil2. For design, find it in the Anvil2 file.

Anatomy

The Field Label consists of three primary elements that work together to provide clear, accessible labels for form fields.

Label text - The primary label content that identifies the form field
Required indicator (Optional) - A red asterisk displayed when the field is required, with screen reader announcement
More info icon (Optional) - An information icon that displays additional context in a tooltip when hovered or focused
More info tooltip (Optional) - A tooltip that displays additional context about the form field when hovered or focused

Options

The Field Label supports the following configurations to accommodate various form labeling scenarios.

Required Indicator

When a form field is required, Field Label displays a red asterisk after the label text. The asterisk provides a visual indicator for sighted users, while screen readers announce “Required” to ensure accessibility. Field Label supports an optional help tooltip that displays additional context about the form field. The tooltip appears when users hover over or focus the information icon, providing guidance without cluttering the label area.

Behavior

The Field Label responds to user interaction with distinct visual states and tooltip interactions.

Visual States

Field Label maintains consistent typography and spacing across all states. The required indicator uses a danger color to draw attention, while the more info icon remains visually distinct but unobtrusive. When the more info tooltip is present, the icon becomes interactive and responds to hover and focus states. The more info tooltip opens on hover or focus of the information icon. The tooltip positions itself above the icon by default, with fallback placements to ensure visibility when space is limited. Tooltip content is also available to screen readers through a screen reader-only element, ensuring all users receive the additional context.

Usage Guidelines

Use the Field Label when you need to associate labels with form inputs, indicate required fields, provide additional context, create fieldset legends, or build custom form components that require explicit label control.

Standard	Requirement
DoAssociating labels with inputs	Associate labels with form inputs using semantic HTML
DoIndicating required fields	Indicate required fields with a visual and accessible indicator
DoProviding additional context	Provide additional context about form fields through help tooltips
DoCreating fieldset legends	Create fieldset legends for grouping related form controls
DoBuilding custom form components	Build custom form components that require explicit label control
DoShowing required indicators consistently	Use required indicators consistently across all forms so users understand form expectations at a glance; see Show required indicators consistently.
DoUsing more info for supplementary content	Use more info for supplementary context, definitions, or examples, kept to 1-2 lines; see Use more info for supplementary information only.
DoPutting essential info in hint text	Put essential information like requirements and formatting rules in hint text or descriptions where users can see it while filling out the form; see Use more info for supplementary information only.
Don’tBuilt-in form components	Use built-in label props when available. For Checkbox Group and Radio Group, prefer their `legend` props instead of composing Field Label yourself
Don’tNon-form contexts	Use text components for labels that don’t associate with form inputs
Don’tDecorative text	Use appropriate text components for non-functional label text
Don’tEssential info in tooltips	Don’t put essential information in more info tooltips — users must recall tooltip content when completing the field, which creates cognitive load; see Use more info for supplementary information only.

Alternatives

Field Label vs Built-in Labels

Many Anvil2 form components include label functionality through props like label and required. Checkbox Group and Radio Group also provide a legend prop. Use these built-in options when available, as they handle label association and styling automatically. Use Field Label directly when building custom form components or when you need explicit control over label rendering and positioning.

Label vs Legend

Use Field Label as a label when associating text with a single form control. Use Field Label as a legend when naming a group of related controls inside a fieldset. Checkbox Group and Radio Group already expose a legend prop for this pattern — prefer that prop instead of composing Field Label yourself for those components.

How to Use

Show required indicators consistently

Use the required indicator to help users understand which fields are mandatory before they start filling out the form. Consistent use of required indicators across all forms creates predictable patterns that reduce user confusion and form abandonment. Use required indicators consistently across all forms. When some fields are required, clearly mark all required fields to help users understand form expectations at a glance.

Use more info for supplementary information only

More info tooltips are best for supplemental information that enhances understanding but isn’t essential to complete the field. Essential information should be visible in the label, hint text, or description rather than hidden in a tooltip. Use more info for supplementary context, definitions, or examples that help users understand the field better. Keep tooltip content to 1-2 lines and avoid repeating information already visible in the label. Don’t put essential information in more info tooltips. Users must recall tooltip content when completing the field, which creates cognitive load. Use hint text or descriptions for information users need to see while filling out the form. Put essential information like requirements and formatting rules in hint text or descriptions where users can see it while filling out the form. This reduces cognitive load and helps users complete fields correctly.

Content

Content within the Field Label should be clear, concise, and descriptive.

Use sentence case for label text
Keep labels brief but descriptive enough to identify the field purpose
Write tooltip content that provides actionable guidance or clarifies field requirements
Ensure required indicators are used consistently across forms
Match label terminology with the form field’s purpose and expected input

Keyboard Interaction

Users can navigate the Field Label using standard keyboard controls.

Key	Description
Tab	Moves focus to the associated form input. When more info icon is present and the input is focused, the tooltip opens automatically
Escape	Closes the more info tooltip when open

Accessibility

Field Label implements accessibility features to ensure all users receive proper form field context. The component uses semantic HTML elements (label or legend) to create proper associations with form controls. Required fields include both visual indicators and screen reader announcements. The more info tooltip content is available to screen readers through a screen reader-only element, ensuring assistive technology users receive the same contextual information as sighted users.

Code

Implementation
FieldLabel Props

Common Examples

The FieldLabel component is typically used internally by form components, but can also be used directly when building custom form fields.

import { FieldLabel } from "@servicetitan/anvil2";

function ExampleComponent() {
  return (
    <>
      <FieldLabel htmlFor="email">Email Address</FieldLabel>
      <input id="email" type="email" />
    </>
  );
}

You might not need `FieldLabel`

The FieldLabel component is used to display a label for a form component. Please look to our Form Patterns page for guidance on how to use labels for your use case.However, many form components in Anvil2 already have FieldLabel built into them, such as Checkbox.Group, DateFieldYearless, DaysOfTheWeek, NumberField, and ProgressBar. For all of these components, you do NOT need to use the FieldLabel component, just use the existing props such as label on your Anvil2 form components.

Required Fields

Add a visual required indicator (red asterisk) and screen reader announcement.Add additional context with a help tooltip.

Polymorphic Element

The FieldLabel component can render as different HTML elements using the el prop. Choose the element based on whether you are labeling a single control or a group of related controls.

`el` value	When to use	Notes
`"label"` (default)	Labeling a single form control	Set `htmlFor` to the control’s `id`
`"legend"`	Labeling a group of related controls inside a `<fieldset>`	Omit `htmlFor`; place `FieldLabel` as the first child of the `<fieldset>`

Use el="legend" when building a custom fieldset (for example a group of native inputs or third-party controls that share one accessible name). Prefer the built-in legend prop on Checkbox.Group and Radio.Group instead of composing FieldLabel yourself for those components.Control the tooltip’s open state programmatically.

Markdown in labels

The children prop supports limited inline Markdown: bold (**text**), italic (*text*), bold and italic (***text***), highlight (==text==), and code (`text`). This markdown is stripped from the accessible text so screen readers receive a plain string.

React Accessibility

Uses semantic HTML (<label> by default, or <legend> when el="legend")
Required fields include both a visual asterisk and “Required” text for screen readers
The moreInfo content is available to screen readers via SrOnly
Associates with a single control via htmlFor when el="label"; as a <legend>, associates with the enclosing <fieldset> group instead

For more guidance on form field labels and context, see input field context association best practices.

<FieldLabel
  el="label"
  htmlFor="input-id"
  required={true}
  moreInfo="Additional context for users"
>
  Label Text
</FieldLabel>

`FieldLabel` Props

The FieldLabel component is polymorphic and accepts props based on the element type specified by el. In addition to standard HTML attributes for the chosen element, it accepts:

boolean | AiMarkWithTooltipOrPopoverConfig

Displays an AI indicator icon next to the label. See AI Marks for full API documentation and usage examples.

ReactNode

The label text. When passed as a plain string, supports limited inline Markdown for bold (**text**), italic (*text*), bold and italic (***text***), highlight (==text==), and code (`text`) formatting. Markdown is stripped from the accessible text exposed to screen readers.

Passing ReactNode is deprecated — use a plain string with inline markdown instead. children will be required to be a string in v4.0.0.

ElementType

default:"label"

The HTML element to render. Use "label" (default) for a single control with htmlFor. Use "legend" as the first child of a <fieldset> when naming a group of related controls (omit htmlFor).

string

Unique identifier for the label element.

ReactNode

Additional information to display in a tooltip next to the label text.

boolean

default:"false"

Controls the open state of the more info tooltip.

boolean

default:"false"

Whether the field is required. Shows a red asterisk (*) and announces “Required” to screen readers.

When `el="label"` (default)

Standard label props are available:

string

The ID of the form element this label is associated with.

When `el="legend"`

Standard legend props are available. Use as the first child of a <fieldset> when labeling a group of related controls. Omit htmlFor — the legend names the group, not a single control.

Concepts & Guidelines

Anvil2

Resources

Field Label - Web

Anatomy

Options

Required Indicator

More Info Tooltip

Behavior

Visual States

Tooltip Interaction

Usage Guidelines

Alternatives

Field Label vs Built-in Labels

Label vs Legend

How to Use

Show required indicators consistently

Use more info for supplementary information only

Content

Keyboard Interaction

Accessibility

Code

Common Examples

You might not need `FieldLabel`

Required Fields

With More Info Tooltip

Polymorphic Element

Controlled Tooltip State

Markdown in labels

React Accessibility

`FieldLabel` Props

When `el="label"` (default)

When `el="legend"`

​Anatomy

​Options

​Required Indicator

​More Info Tooltip

​Behavior

​Visual States

​Tooltip Interaction

​Usage Guidelines

​Alternatives

​Field Label vs Built-in Labels

​Label vs Legend

​How to Use

​Show required indicators consistently

​Use more info for supplementary information only

​Content

​Keyboard Interaction

​Accessibility

​Code

​Common Examples

​You might not need FieldLabel

​Required Fields

​With More Info Tooltip

​Polymorphic Element

​Controlled Tooltip State

​Markdown in labels

​React Accessibility

​FieldLabel Props

​When el="label" (default)

​When el="legend"

Anatomy

Options

Required Indicator

More Info Tooltip

Behavior

Visual States

Tooltip Interaction

Usage Guidelines

Alternatives

Field Label vs Built-in Labels

Label vs Legend

How to Use

Show required indicators consistently

Use more info for supplementary information only

Content

Keyboard Interaction

Accessibility

Code

Common Examples

You might not need `FieldLabel`

Required Fields

With More Info Tooltip

Polymorphic Element

Controlled Tooltip State

Markdown in labels

React Accessibility

`FieldLabel` Props

When `el="label"` (default)

When `el="legend"`