> ## Documentation Index
> Fetch the complete documentation index at: https://anvil.servicetitan.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Field Label - Web

> Field Label provides accessible form labels with optional required indicators and help tooltips.

> [!NOTE]
>
> For development, import `FieldLabel` from
> `@servicetitan/anvil2`. For design, find it in the
> [Anvil2 file](https://www.figma.com/design/xaNQsvRKczoxu7pj0M6QT8/Anvil2-v3).

![](https://mintcdn.com/servicetitan/gLoz1MFH6ICVCCBs/images/docs/web/components/field-label/overview-image.png?fit=max\&auto=format\&n=gLoz1MFH6ICVCCBs\&q=85\&s=f157603987ad2a1d617c7690c92b0e3b)

## Anatomy

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

![Anatomy of the Field Label component](https://mintcdn.com/servicetitan/gLoz1MFH6ICVCCBs/images/docs/web/components/field-label/design/field-label-anatomy.png?fit=max\&auto=format\&n=gLoz1MFH6ICVCCBs\&q=85\&s=e11346fce08a9186f2a5d4a6b7e0c839)

1. **Label text** - The primary label content that identifies the form field
2. **Required indicator** (Optional) - A red asterisk displayed when the field is required, with screen reader announcement
3. **More info icon** (Optional) - An information icon that displays additional context in a tooltip when hovered or focused
4. **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

fieldlabel-required

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/fieldlabel-required?file=src/App.tsx)

```tsx lines theme={null}
import { FieldLabel, Flex } from "@servicetitan/anvil2";

function App() {
  return (
    <Flex direction="column" gap="2">
      <FieldLabel htmlFor="name" required>
        Full Name
      </FieldLabel>
      <input id="name" type="text" required />
    </Flex>
  );
}

export default App;
```

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.

### More Info Tooltip

fieldlabel-moreinfo

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/fieldlabel-moreinfo?file=src/App.tsx)

```tsx lines theme={null}
import { FieldLabel, Flex } from "@servicetitan/anvil2";
import { useState } from "react";

function App() {
  const [isOpen, _setIsOpen] = useState(true);

  return (
    <Flex direction="column" gap="2">
      <FieldLabel
        htmlFor="password"
        required
        moreInfo="Password must be at least 8 characters and include a number."
        moreInfoOpen={isOpen}
      >
        Password
      </FieldLabel>
      <input id="password" type="password" required />
    </Flex>
  );
}

export default App;
```

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

fieldlabel-visual-states

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/fieldlabel-visual-states?file=src/App.tsx)

```tsx lines theme={null}
import { FieldLabel, Flex } from "@servicetitan/anvil2";

function App() {
  return (
    <Flex direction="column" gap="4">
      <Flex direction="column" gap="2">
        <FieldLabel htmlFor="email">Email Address</FieldLabel>
        <input id="email" type="email" />
      </Flex>

      <Flex direction="column" gap="2">
        <FieldLabel htmlFor="name" required>
          Full Name
        </FieldLabel>
        <input id="name" type="text" required />
      </Flex>

      <Flex direction="column" gap="2">
        <FieldLabel
          htmlFor="password"
          required
          moreInfo="Password must be at least 8 characters and include a number."
        >
          Password
        </FieldLabel>
        <input id="password" type="password" required />
      </Flex>
    </Flex>
  );
}

export default App;
```

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.

### Tooltip Interaction

fieldlabel-moreinfo

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/fieldlabel-moreinfo?file=src/App.tsx)

```tsx lines theme={null}
import { FieldLabel, Flex } from "@servicetitan/anvil2";
import { useState } from "react";

function App() {
  const [isOpen, _setIsOpen] = useState(true);

  return (
    <Flex direction="column" gap="2">
      <FieldLabel
        htmlFor="password"
        required
        moreInfo="Password must be at least 8 characters and include a number."
        moreInfoOpen={isOpen}
      >
        Password
      </FieldLabel>
      <input id="password" type="password" required />
    </Flex>
  );
}

export default App;
```

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](#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](#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](#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](#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.

fieldlabel-required-do

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/fieldlabel-required-do?file=src/App.tsx)

```tsx lines theme={null}
import { FieldLabel, Flex } from "@servicetitan/anvil2";

function App() {
  return (
    <Flex direction="column" gap="2">
      <FieldLabel htmlFor="name" required>
        Full Name
      </FieldLabel>
      <input id="name" type="text" required />
    </Flex>
  );
}

export default App;
```

**Do**

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.

fieldlabel-moreinfo-supplementary-do

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/fieldlabel-moreinfo-supplementary-do?file=src/App.tsx)

```tsx lines theme={null}
import { FieldLabel, Flex } from "@servicetitan/anvil2";
import { useState } from "react";

function App() {
  const [isOpen, _setIsOpen] = useState(true);

  return (
    <Flex direction="column" gap="2">
      <FieldLabel
        htmlFor="tax-id"
        required
        moreInfo="Your tax ID is used for reporting purposes and may be required for certain transactions."
        moreInfoOpen={isOpen}
      >
        Tax ID
      </FieldLabel>
      <input id="tax-id" type="text" required />
    </Flex>
  );
}

export default App;
```

**Do**

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.

fieldlabel-moreinfo-essential-dont

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/fieldlabel-moreinfo-essential-dont?file=src/App.tsx)

```tsx lines theme={null}
import { FieldLabel, Flex } from "@servicetitan/anvil2";
import { useState } from "react";

function App() {
  const [isOpen, _setIsOpen] = useState(true);

  return (
    <Flex direction="column" gap="2">
      <FieldLabel
        htmlFor="password"
        required
        moreInfo="Must be at least 8 characters and include a number."
        moreInfoOpen={isOpen}
      >
        Password
      </FieldLabel>
      <input id="password" type="password" required />
    </Flex>
  );
}

export default App;
```

**Don’t**

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.

fieldlabel-moreinfo-essential-do

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/fieldlabel-moreinfo-essential-do?file=src/App.tsx)

```tsx lines theme={null}
import { FieldLabel, FieldMessage, Flex } from "@servicetitan/anvil2";

function App() {
  return (
    <Flex direction="column" gap="2">
      <FieldLabel htmlFor="password" required>
        Password
      </FieldLabel>
      <input
        id="password"
        type="password"
        required
        aria-describedby="password-hint"
      />
      <FieldMessage
        id="password-hint"
        hint="Must be at least 8 characters and include a number."
      />
    </Flex>
  );
}

export default App;
```

**Do**

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-playground

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/fieldlabel-playground?file=src/App.tsx)

```tsx lines expandable theme={null}
import { FieldLabel, Flex } from "@servicetitan/anvil2";

function App() {
  return (
    <Flex direction="column" gap="2">
      <FieldLabel htmlFor="email">Email Address</FieldLabel>
      <input id="email" type="email" />
    </Flex>
  );
}

export default App;
```

## Common Examples

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

```tsx theme={null}
import { FieldLabel } from "@servicetitan/anvil2";

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

> [!WARNING]
>
> ### You might not need `FieldLabel`
>
> The `FieldLabel` component is used to display a label for a form component. Please look to our [Form Patterns](https://anvil.servicetitan.com/docs/patterns/forms/web.md#relationship-between-hint-description-and-error-text) 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.

fieldlabel-required

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/fieldlabel-required?file=src/App.tsx)

```tsx lines expandable theme={null}
import { FieldLabel, Flex } from "@servicetitan/anvil2";

function App() {
  return (
    <Flex direction="column" gap="2">
      <FieldLabel htmlFor="name" required>
        Full Name
      </FieldLabel>
      <input id="name" type="text" required />
    </Flex>
  );
}

export default App;
```

### With More Info Tooltip

Add additional context with a help tooltip.

fieldlabel-moreinfo

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/fieldlabel-moreinfo?file=src/App.tsx)

```tsx lines expandable theme={null}
import { FieldLabel, Flex } from "@servicetitan/anvil2";
import { useState } from "react";

function App() {
  const [isOpen, _setIsOpen] = useState(true);

  return (
    <Flex direction="column" gap="2">
      <FieldLabel
        htmlFor="password"
        required
        moreInfo="Password must be at least 8 characters and include a number."
        moreInfoOpen={isOpen}
      >
        Password
      </FieldLabel>
      <input id="password" type="password" required />
    </Flex>
  );
}

export default App;
```

### 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`](https://anvil.servicetitan.com/docs/components/checkbox/web) and [`Radio.Group`](https://anvil.servicetitan.com/docs/components/radio/web) instead of composing `FieldLabel` yourself for those components.

fieldlabel-el

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/fieldlabel-el?file=src/App.tsx)

```tsx lines expandable theme={null}
import { FieldLabel, Flex } from "@servicetitan/anvil2";

function App() {
  return (
    <Flex direction="column" gap="6">
      <FieldLabel htmlFor="field">Label</FieldLabel>

      <fieldset>
        <FieldLabel el="legend" required>
          Payment Method
        </FieldLabel>
      </fieldset>
    </Flex>
  );
}

export default App;
```

### Controlled Tooltip State

Control the tooltip's open state programmatically.

fieldlabel-controlled

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/fieldlabel-controlled?file=src/App.tsx)

```tsx lines expandable theme={null}
import { FieldLabel, Flex } from "@servicetitan/anvil2";
import { useState } from "react";

function App() {
  const [isOpen, _setIsOpen] = useState(false);

  return (
    <Flex direction="column" gap="2">
      <FieldLabel
        htmlFor="field"
        moreInfo="This tooltip can be controlled externally."
        moreInfoOpen={isOpen}
      >
        Controlled Label
      </FieldLabel>
    </Flex>
  );
}

export default App;
```

### 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.

fieldlabel-markdownlabel

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/fieldlabel-markdownlabel?file=src/App.tsx)

```tsx lines expandable theme={null}
import { FieldLabel, Flex } from "@servicetitan/anvil2";

function App() {
  return (
    <Flex direction="column" gap="4">
      <FieldLabel htmlFor="a">**Bold** label</FieldLabel>
      <FieldLabel htmlFor="b">*Italic* label</FieldLabel>
      <FieldLabel htmlFor="c">***Bold and italic*** label</FieldLabel>
      <FieldLabel htmlFor="d">==Highlight== label</FieldLabel>
      <FieldLabel htmlFor="e">`Code` label</FieldLabel>
    </Flex>
  );
}

export default App;
```

## 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](https://anvil.servicetitan.com/docs/accessibility/labels-and-ctas.md#input-field-context-association).

**FieldLabel Props**

```tsx theme={null}
<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:

**aiMark** `boolean | AiMarkWithTooltipOrPopoverConfig`

Displays an AI indicator icon next to the label. See [AI Marks](https://anvil.servicetitan.com/docs/utilities/web/ai-marks.md) for full API documentation and usage examples.

**children** `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.
\[!WARNING] Passing `ReactNode` is deprecated — use a plain string with inline markdown instead. `children` will be required to be a `string` in v4.0.0.

**el** `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`).

**id** `string`

Unique identifier for the label element.

**moreInfo** `ReactNode`

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

**moreInfoOpen** `boolean` (default: false)

Controls the open state of the more info tooltip.

**required** `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:

**htmlFor** `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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.