Field Message

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

Anatomy

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

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

Options

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

Behavior

The Field Message displays all messages simultaneously in a consistent order: hint, description, error(s), then warning(s). No message type replaces another. 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 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 Props

Common Examples

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.

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

<FieldMessage
  warning="This password is not very strong."
/>

Errors and Warnings Together

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

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

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.

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

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.

Errors and Warnings pattern — Guidance on surfacing errors and warnings across the app.
Forms pattern — Best practices for form layout, labels, and help text.

<FieldMessage
  hint="Hint text"
  description="Description text"
  error="Error message"
  warning="Warning message"
  id="field-message-1"
/>

`FieldMessage` Props

ReactElement | string

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

ReactElement | string

string | string[] | ReactElement

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

string | string[] | ReactElement

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

string

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

ReactElement | string

deprecated

Use the error prop instead.

"off" | "assertive" | "polite"

deprecated

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

Concepts & Guidelines

Anvil2

Resources

Field Message - Web

Anatomy

Options

Behavior

Usage Guidelines

How to Use

How not to use

Content

Keyboard Interaction

Code

Common Examples

Multiple Errors

Warning Messages

Errors and Warnings Together

You might not need `FieldMessage`

Persistent Hints

Accessibility

`FieldMessage` Props

​Anatomy

​Options

​Behavior

​Usage Guidelines

​How to Use

​How not to use

​Content

​Keyboard Interaction

​Code

​Common Examples

​Multiple Errors

​Warning Messages

​Errors and Warnings Together

​You might not need FieldMessage

​Persistent Hints

​Accessibility

​Related

​FieldMessage Props

Anatomy

Options

Behavior

Usage Guidelines

How to Use

How not to use

Content

Keyboard Interaction

Code

Common Examples

Multiple Errors

Warning Messages

Errors and Warnings Together

You might not need `FieldMessage`

Persistent Hints

Accessibility

Related

`FieldMessage` Props