Text Field

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

Anatomy

Text Field consists of six primary elements that work together to collect a single line of text.

Label - Names the field. A required field adds an asterisk and a screen-reader “Required”. An info button can follow the label when extra context belongs in a tooltip.
Field - The single-line input. Focus draws a ring. An error turns the border critical. A loading spinner can sit inside the field, after the value.
Prefix (Optional) - Short text before the value, such as @ on a username. It is visual only and is not announced.
Placeholder (Optional) - A low-contrast prompt inside an empty field. It disappears as soon as the user types and does not replace the label.
Suffix (Optional) - A unit or short marker after the value, such as “days”. It is visual only and is not announced.
Messages (Optional) - Copy under the field. The diagram marks description. Messages stack in this order: hint, description, error, then warning. A character counter sits with those messages when the counter is enabled. Hint stays visible even when an error or warning is showing.

Options

Text Field supports the following configurations to fit different single-line inputs.

Sizes

Size	Height
Small	32px
Default	40px
Large	48px

Medium is the default. Choose a size that matches the surrounding fields. Do not mix sizes in the same form group.

Prefix

Prefix shows a fixed marker before free text, such as @ on a username. Currency and other numeric amounts belong on a Number Field. Because the prefix is not announced, repeat that meaning in the label or hint.

Suffix

Suffix shows the unit of the value, such as days, weeks, or months. Keep it to one short word or symbol. Repeat the unit in the label or hint so screen-reader users hear it.

Hint, description, error, and warning

Hint is the persistent instruction. It stays on screen when validation messages appear. Description adds secondary context under the hint, such as who will see the value. Error marks the field invalid, turns the border critical, and states what to fix. Warning cautions the user without marking the field invalid. Error and warning can appear together. The error is announced immediately. The warning is announced politely.

Required

Required adds an asterisk on the label and announces “Required” to screen readers. The input is also marked required, so an empty field fails native form validation on submit.

Character limit

A character limit stops further typing at the maximum for text-like types. Browsers do not enforce it when the type is number. Use Number Field when the value itself must stay inside a numeric range. The counter shows how many characters are entered out of that maximum. Show the counter when the limit is easy to hit, such as a short name or a note. The visible counter is hidden from assistive technology. While the user is typing, the remaining count is announced instead.

Highlighted

A highlighted field uses a subdued primary background to draw attention, for example a value that needs review. Highlight does not mean invalid. Pair it with a hint or warning when the user needs to know why the field stands out. Hide the label only when the accessible name is repeated nearby, such as a pair of name fields in a tight row. The label string is still the accessible name. Placeholder text repeats it visually and disappears while typing.

Behavior

Text Field responds to focus, typing, and validation with the states below.

Visual states

Enabled — The field accepts input. Focus shows a ring.
Disabled — The field is dimmed and cannot be focused, edited, or copied.
Read-only — The value can be focused, selected, and copied. The background is subdued so it does not look editable. Use read-only to display a value the user should review. Use disabled only when the control is unavailable.
Error — The border turns critical and the message under the field states the problem. An error with no message still styles the field as invalid.
Loading — A spinner appears inside the field, after the value. The field stays editable unless it is also disabled.

Clicking the prefix, suffix, or the padding around the text focuses the input.

Widths

Size the field to the value you expect. A ZIP code field should be short. A note field can use the full row. Unless the parent sets a width, Text Field fills the available horizontal space.

Overflow

A value longer than the field scrolls horizontally inside the input. The visible portion follows the cursor. The field does not grow in height and does not wrap onto a second line.

Usage Guidelines

Standard	Requirement
DoSingle-line text input	Use the Text Field when a user needs to type a single line of free text, such as a name, email, or short note.
Don’tMultiple lines of text	Use Textarea for several lines of text instead.
Don’tQuantities and measurements	Use Number Field for values that need a step or a min and max instead.
Don’tSearch or filter	Use Search Field instead.
Don’tFree text with suggestions	Use Typeahead Text Field instead.
Don’tOne choice from a fixed list	Use Select Field instead.

When to Use

Use the Text Field when:

Single-line text – Users enter a custom string of text on one line.
Form input – A Form collects free-form text that fits on one line.

When not to use

Avoid using the Text Field for:

Multiple lines of text – Use a Textarea for longer, freeform text.
Quantities and numeric IDs – Use a Number Field for numeric input such as item counts or account numbers.
Times and dates – Use a Time Field for a time or a Date Field Single for a date.
Suggested values – Use a Typeahead Text Field when suggestions help users complete the entry.
Search and filtering – Use a Search Field for search or filter experiences.

How to Use

For guidance on labels and help text, check out our Labels and Help pattern. For form validation guidance, check out our Form Errors and Validation pattern.

Content

Content within the Text Field should tell the user what to enter, in the label, and how to enter it, in the hint.

Labels

Write a label of one to three words in sentence case, usually a noun: “Job name”, “Email”. Do not use the label as a call to action, and do not put the format rules in the label when a hint can carry them.

Placeholder

Placeholder text has low contrast, disappears while typing, and is a poor accessible name. Use it only to echo a hidden label or to show an example value. Put requirements in the hint.

Hint and description

Hint states a format or constraint that must stay visible: “Use the address on the work order”. Description adds outcome or context: “Customers see this note”. Do not repeat the label in either one.

Prefix and suffix

Keep prefix and suffix to a symbol or one word. Put the same meaning in the label or hint, because prefix and suffix are not read aloud.

Errors and warnings

An error tells the user how to fix the value: “Enter an email address”. A warning flags a risk that does not block submit: “This name is already used on another job”. Do not use a warning as a second error.

More info

More info is a short tooltip, one phrase or sentence, for context that does not fit the hint. Do not repeat the label. For anything longer, use the description or link out.

Keyboard Interaction

Users can navigate the Text Field using standard single-line text controls.

Tab moves focus to the more-info button when that button is present, then to the input. Without the button, Tab moves focus directly to the input.
Character keys, arrows, Home, and End move and edit the caret inside the value. The field does not accept a newline.
Focus or hover on the more-info button opens its tooltip. Escape closes it, and so does moving focus away.
Prefix and suffix are not in the tab order. Activating them focuses the input.

Code

Implementation
TextField Props

Common Examples

Import TextField from @servicetitan/anvil2 and pass a string label. The label is associated with the input. Unlisted attributes such as name are forwarded to the input, so the field participates in a native form submit.

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

function ExampleComponent() {
  return (
    <TextField
      label="Label"
      placeholder="Placeholder"
      hint="Hint text"
      moreInfo="More info"
      required
    />
  );
}

Managing text field state

TextField keeps the input controlled internally. Omit value for an uncontrolled field, and pass defaultValue for an initial value. Pass value with onChange to control it. Do not pass value and defaultValue together.

Uncontrolled text fields

Give the field a name and submit it with a Button set to type="submit". Read the value from the form event, as in the example above.

Controlled text fields

Store the string in React state and pass it back through value. onChange receives the input’s change event.

Show character counter

Use the maxLength and showCounter props to display a character counter below the text field.

Markdown in labels

The label prop supports inline markdown: bold (**text**), italic (*text*), bold and italic (***text***), highlight (==text==), and code (`text`).

Hide the label

Use hideLabel to visually hide the label. The label string is converted to an aria-label on the input so it remains accessible to screen readers — any inline markdown is stripped to plain text.

React Accessibility

TextField renders a native input and a label whose htmlFor matches the input id. When id is omitted, one is generated.

Pass a string label. That string is the accessible name. Omitting label is deprecated. On that deprecated path, placeholder is copied to aria-label when aria-label is also omitted.
hideLabel removes the visible label and sets aria-label from the label string, with inline markdown stripped. An explicit aria-label is ignored in that case.
When the label is visible, an explicit aria-label replaces the label as the accessible name. Omit aria-label so the visible label is announced.
prefix and suffix are aria-hidden. Put that meaning in label or hint.
required sets the input’s required attribute and adds a visual asterisk plus screen-reader text “Required” on the label.
A truthy error sets aria-invalid. Error text is announced with aria-live="assertive". Warning text is announced with aria-live="polite". errorAriaLive is ignored.
Hint, description, error, and warning are grouped in one region referenced by aria-describedby. Hint stays in that region when an error or warning is also shown.
moreInfo adds a button labeled “More information” after the label. The tooltip content is also exposed through aria-describedby.
The character counter is aria-hidden. While the user is typing and maxLength is set, a live region announces the remaining characters, or that the maximum has been reached.

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

<TextField
  label="Label"
  description="Description"
  hint="Hint text"
  error="Error message"
  warning="Check this value"
  loading={false}
  moreInfo="More info"
  prefix="Prefix"
  required={false}
  size="medium"
  suffix="Suffix"
  type="text"
  showCounter
  maxLength={100}
  placeholder="Placeholder"
/>

`TextField` Props

className and style apply to the root element. Layout utilities such as flex, gap, and the responsive sm through xxl props apply there as inline styles. Attributes that are not listed below, including name, autoComplete, and readOnly, spread onto the underlying input.type accepts only the values listed below. There is no width prop. The root is a column flex container and stretches to the width of its parent.

string

Accessible name for the input. When hideLabel is true and label is a string, this value is ignored and the label (with inline markdown removed) is used instead. When label is visible, aria-label replaces the label as the accessible name. When label is omitted, placeholder is used if aria-label is also omitted.

string

Class name on the root element, not the input.

string

Tracking id placed on the input. When omitted, a tracking id is generated from the label, labelProps other than aiMark, prefix, hint, description, size, and type.

string | number | readonly string[]

Initial value for an uncontrolled field. The input stays controlled internally. Do not pass value and defaultValue together.

ReactElement | string

Secondary copy rendered below hint.

boolean

default:"false"

Prevents interaction and dims the field.

boolean | string | ReactElement | string[]

Applies error styling and sets aria-invalid when truthy. true styles the field without a message. A string or string[] renders one or more error messages below the field. A React element still renders, but that form is deprecated. Pass a string or string[].

"off" | "assertive" | "polite"

Deprecated and ignored. Error messages always use aria-live="assertive".

boolean

default:"false"

Hides the visible label. label must be a string. That string, with inline markdown removed, is set as the input aria-label.

ReactElement | string

Always-visible instruction below the field. Stays rendered when an error or warning is also shown.

string

Id of the input and the target of the label htmlFor. Generated when omitted.

boolean

default:"false"

Applies a subdued primary background to draw attention to the field.

ReactNode

Accessible name shown above the field. A string supports inline markdown: bold (**text**), italic (*text*), bold and italic (***text***), highlight (==text==), and code (`text`).

Omitting label is deprecated and the prop will be required in v4.0.0. Use hideLabel to hide it visually. Passing a ReactNode other than a string is also deprecated. Use a string with inline markdown.

FieldLabelProps

Extra props for the visible FieldLabel, such as className or aiMark. These props spread after htmlFor, required, and moreInfo, so they can override those values.

boolean

default:"false"

Shows a spinner inside the field, after the input. The field stays editable.

number

Maximum number of characters the input accepts. Required when showCounter is true. The same value drives the visible counter and the “characters left” announcement while the user is typing. Browsers ignore this limit when type is "number". Use NumberField for a numeric range.

ReactNode

Tooltip content for the info button after the label. The same content is exposed to assistive technology through aria-describedby.

(event: ChangeEvent<HTMLInputElement>) => void

Called with the native change event after the field updates its value.

string

Prompt shown while the input is empty. This is not a replacement for label. It becomes the accessible name only when label and aria-label are both omitted.

string

Text rendered before the input. Hidden from assistive technology. Include the same meaning in label or hint.

boolean

default:"false"

Marks the input required and adds an asterisk plus screen-reader text “Required” on the label.

boolean

default:"false"

Shows an aria-hidden counter (current/maxLength) below the field. When true, maxLength is required.

"small" | "medium" | "large"

default:"medium"

Field height. "small" is 32px, "medium" is 40px, and "large" is 48px.

CSSProperties

Inline styles on the root element, merged with layout utilities. Not applied to the input.

string | ReactElement

Content rendered after the input. Hidden from assistive technology. Include the same meaning in label or hint.

default:"text"

HTML input type. Other input types are not supported.

string | number | readonly string[]

Controlled value. When passed, the field uses this value instead of internal state.

string | string[]

Warning copy rendered below errors, with a warning icon. Announced with aria-live="polite". Does not apply error styling.

Concepts & Guidelines

Anvil2

Resources

Text Field - Web

Anatomy

Options

Sizes

Prefix

Suffix

Hint, description, error, and warning

Required

Character limit

Highlighted

Behavior

Visual states

Widths

Overflow

Usage Guidelines

When to Use

When not to use

How to Use

Content

Labels

Placeholder

Hint and description

Prefix and suffix

Errors and warnings

More info

Keyboard Interaction

Code

Common Examples

Managing text field state

Uncontrolled text fields

Controlled text fields

Show character counter

Markdown in labels

Hide the label

React Accessibility

`TextField` Props

​Anatomy

​Options

​Sizes

​Prefix

​Suffix

​Hint, description, error, and warning

​Required

​Character limit

​Highlighted

​Visually hidden label

​Behavior

​Visual states

​Widths

​Overflow

​Usage Guidelines

​When to Use

​When not to use

​How to Use

​Content

​Labels

​Placeholder

​Hint and description

​Prefix and suffix

​Errors and warnings

​More info

​Keyboard Interaction

​Code

​Common Examples

​Managing text field state

​Uncontrolled text fields

​Controlled text fields

​Show character counter

​Markdown in labels

​Hide the label

​React Accessibility

​TextField Props

Anatomy

Options

Sizes

Prefix

Suffix

Hint, description, error, and warning

Required

Character limit

Highlighted

Visually hidden label

Behavior

Visual states

Widths

Overflow

Usage Guidelines

When to Use

When not to use

How to Use

Content

Labels

Placeholder

Hint and description

Prefix and suffix

Errors and warnings

More info

Keyboard Interaction

Code

Common Examples

Managing text field state

Uncontrolled text fields

Controlled text fields

Show character counter

Markdown in labels

Hide the label

React Accessibility

`TextField` Props