> ## 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 Message - Web

> Field Message is a subcomponent used by form field components to show hint, error, warning, and description text to a user.

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

## Anatomy

The Field Message consists of primary elements that work together to show hint, error, warning, and description text to users.

![Field Message anatomy
diagram](https://mintcdn.com/servicetitan/j3rmC6LC2VZf-6y6/images/docs/web/components/field-message/design/field-message-anatomy-diagram.png?fit=max\&auto=format\&n=j3rmC6LC2VZf-6y6\&q=85\&s=3b6eba7b604136ee42e5a75c8f8782af)

1. Hint text (always visible, persists alongside errors and warnings)
2. Description text (max 3 lines of content)
3. Error message
4. Warning message

## Options

The Field Message supports hint, error, warning, and description text configurations to accommodate various form field messaging scenarios.

fieldmessage-props

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

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

function App() {
  return (
    <Flex direction="column" gap="6">
      <FieldMessage
        hint="Hint text, should be max 1 line"
        description="Description text, can be max 3 lines explaining what the purpose of the field is to the user"
      />

      <Divider />

      <FieldMessage
        hint="Hint text"
        description="Description text, can be max 3 lines explaining what the purpose of the field is to the user"
        error="Field message in error state"
      />

      <Divider />

      <FieldMessage hint="Hint text" warning="Field message in warning state" />

      <Divider />

      <FieldMessage hint="Hint text only" />
    </Flex>
  );
}

export default App;
```

## Behavior

The Field Message displays all messages simultaneously in a consistent order: hint, description, error(s), then warning(s). No message type replaces another.

fieldmessage-behavior

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

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

function App() {
  return (
    <FieldMessage
      hint="Hint text"
      description="Description text, can be max 3 lines explaining what the purpose of the field is to the user"
      error="Field message in error state"
      warning="This email is associated with another account"
    />
  );
}

export default App;
```

Hint text always remains visible, even when error or warning messages are present. Description text appears between the hint and any error or warning messages. All messages are displayed in a consistent order: hint, description, error(s), then warning(s).

## Usage Guidelines

| Standard | Requirement |
| - | - |
| DoUse in non-Anvil custom field components | Use Field Message in custom field components that are not part of Anvil. |
| Don'tAdd it separately to built-in Anvil fields | Field Message is already built into a number of Anvil field components, such as Text Field and Date Field Single — don't add a separate Field Message alongside them. |

### How to Use

Field Message is a subcomponent built into a number of our field components that handles communicating to users how to fill out a form, what the form field is for, and when relevant, why a field has errored.

Field Message has four inputs:

* Hint text
* Description text
* Error text
* Warning text

Each serves a different use case for users:

* **Hint text:** Communicates how a user should fill out a field. For example, "Enter time in increments of 30 minutes, e.g., 9:30 AM." Always visible, even when errors or warnings are present.
* **Description text:** Communicates the way a field will be used. For example, "Sets the appointment time for the customer. Communicated out by SMS 24 hours before appointment time."
* **Error text:** Communicates what the user has done wrong in filling out the field. For example, "Time entered not in an increment of 30 minutes." Supports multiple error messages.
* **Warning text:** Communicates non-blocking issues that the user should be aware of. For example, "This email is associated with another account."

#### How not to use

When using Anvil form field components such as `Combobox`, `DateField`, `DaysOfTheWeek`, `TextField`, or `Textarea`, you don't need to use Field Message—Field Message is already built into the 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 hints, descriptions, and errors for your use case.

## Content

Content within the Field Message should clearly communicate how to fill out the field, what the field is for, and when relevant, why a field has errored or what the user should be cautious about.

## Keyboard Interaction

Users can navigate the Field Message using standard keyboard controls.

## Code

**Implementation**

fieldmessage-playground

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

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

function App() {
  return (
    <Flex direction="column" gap="6">
      <FieldMessage hint="Hint text" description="Description text" />

      <Divider />

      <FieldMessage
        hint="Hint text"
        description="Description text"
        errorMessage="Please provide a valid email."
      />
    </Flex>
  );
}

export default App;
```

## Common Examples

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

function ExampleComponent() {
  return (
    <FieldMessage
      hint="Hint text"
      description="Description text"
      error="Please provide a valid email."
    />
  );
}
```

### Multiple Errors

The `error` prop accepts a string array to display multiple errors at once.

```tsx theme={null}
<FieldMessage
  error={[
    "Password must be at least 8 characters.",
    "Password must contain a special character.",
  ]}
/>
```

### Warning Messages

The `warning` prop accepts a string or string array.

```tsx theme={null}
<FieldMessage
  warning="This password is not very strong."
/>
```

### Errors and Warnings Together

```tsx theme={null}
<FieldMessage
  hint="Format: name@example.com"
  error="Please provide a valid email address."
  warning="This email is associated with another account."
/>
```

> [!WARNING]
>
> ### You might not need `FieldMessage`
>
> The `FieldMessage` component is used to display description text, help text, error messages, and warning messages beneath form components. 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 hints, descriptions, and errors for your use case.
>
> However, many form components in Anvil2 already have `FieldMessage` built into them, such as `Combobox`, `DateField`, `DaysOfTheWeek`, `TextField`, and `Textarea`. For all of these components, you do **NOT** need to use the `FieldMessage` component, just use the existing props such as `description`, `hint`, `error`, and `warning` on your Anvil2 form components.

fieldmessage-avoid

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

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

function App() {
  return (
    <Flex direction="column" gap="6">
      <TextField
        label="TextField Label"
        placeholder="Placeholder"
        hint="Hint text"
        description="TextField already has this built in!"
      />

      <Divider />

      <DateFieldSingle
        defaultValue={new Date().toISOString()}
        label="DateField Label"
        description="DateField has this built in too!"
        error="Please enter a valid date."
      />
    </Flex>
  );
}

export default App;
```

### Persistent Hints

Hints are now always visible, even when errors or warnings are present. Previously, the hint was hidden when an `errorMessage` was displayed. This change makes hints more useful as persistent contextual guidance.

```tsx theme={null}
<FieldMessage
  hint="Format: name@example.com"
  error="Please provide a valid email address."
/>
{/* Both the hint and the error are visible */}
```

### Accessibility

Error messages always use `aria-live="assertive"` and warning messages always use `aria-live="polite"`. These values are hardcoded to ensure a consistent and accessible experience.

For accessibility, the `FieldMessage` component accepts an `id` prop that can be used to establish a relationship between the contents of the `FieldMessage` and the form component you are associating it with. To do this, you will likely need to use an ARIA attribute such as `aria-describedby`. See [MDN docs](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby).

```tsx theme={null}
import { useId } from "react";

function ExampleComponent() {
  const id = useId();

  return (
    <Flex direction="column" gap="2">
      <Button aria-describedby={id}>Move to trash</Button>

      <FieldMessage
        id={id}
        description="Items in the trash will be permanently removed after 30 days."
      />
    </Flex>
  );
}
```

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

### Related

* [Errors and Warnings pattern](https://anvil.servicetitan.com/docs/patterns/errors-and-warnings/web.md) -- Guidance on surfacing errors and warnings across the app.
* [Forms pattern](https://anvil.servicetitan.com/docs/patterns/forms/web.md) -- Best practices for form layout, labels, and help text.

**FieldMessage Props**

```tsx theme={null}
<FieldMessage
  hint="Hint text"
  description="Description text"
  error="Error message"
  warning="Warning message"
  id="field-message-1"
/>
```

## `FieldMessage` Props

**hint** `ReactElement | string`

Hint text or element to display. Always visible regardless of error or warning state.

**description** `ReactElement | string`

**error** `string | string[] | ReactElement`

Error message(s) to display. All error messages use `aria-live="assertive"`. Passing a `ReactElement` is deprecated; prefer strings.

**warning** `string | string[] | ReactElement`

Warning message(s) to display. All warning messages use `aria-live="polite"`. Passing a `ReactElement` is deprecated; prefer strings.

**id** `string`

Unique identifier to associate with form fields using `aria-describedby`.

**errorMessage** `ReactElement | string` *deprecated*

Use the `error` prop instead.

**errorAriaLive** `"off" | "assertive" | "polite"` *deprecated*

No longer used. Error messages always use `aria-live="assertive"`.


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