Number Field

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

Anatomy

The Number Field consists of seven primary elements that work together to accept numerical input.

Label
Field
Placeholder
Increment/Decrement buttons
Prefix
Suffix
Helper texts

Options

The Number Field supports the following configurations to accommodate various numerical input scenarios.

Sizes

Size	Height
Small	2rem (32px)
Medium (default)	2.5rem (40px)
Large	3rem (48px)

Prefix

Suffix

Behavior

The Number Field responds to user interaction with distinct visual states and flexible width behaviors.

Overflow

For long number entries, the content within a Number Field will scroll horizontally. The visible portion of the text will automatically follow the cursor, ensuring the user can always see what they’re typing.

Visual States

Widths

Number Fields should generally be sized to the expected length of the value a user will enter. Unless a specific width is set, the field will automatically fill all available horizontal space.

Usage Guidelines

Number Field is the standard component for any numeric input that doesn’t have a dedicated component. It’s designed for general-purpose numeric values and allows you to use decimals, define step values, and set boundary limits.

Standard	Requirement
DoEntering quantities	Use Number Field for counts, such as the number of items in an order.
DoEntering measurements	Use Number Field for values like height, weight, or distance, and add a suffix to show the unit.
DoEntering numeric IDs and codes	Use Number Field for numerical identifiers, such as account numbers.

Note: Dedicated components such as Percentage Field and Currency Field are planned to handle those specific use cases.

How to Use

Read-only

Using a read-only Number Field is the recommended way to display information that users can review but not change. Unlike a disabled field, a read-only field remains fully accessible: users can still copy the text, focus the input, and interact with it using a screen reader. Additionally, it maintains the necessary contrast for optimal readability.

Prefixes and suffixes

Prefixes and suffixes provide clear context for a Number Field, preventing any misunderstanding of the value being entered.

Prefix

Use a prefix to add a descriptive label to the left of the input. For example, using Qty: helps a user immediately understand the purpose of the number they are entering.

Suffix

Use a suffix to provide a unit of measurement or another clarifying label to the right of the input. This is useful for units like items, minutes, or lbs.

Hiding/Showing the +/- controls

Hide the +/- controls when the value is something a user needs to type precisely rather than step through, such as an account number or ID. In those cases, the buttons add no value and should be omitted. Show the +/- buttons when the value has a meaningful, predictable step, such as a quantity. When users will nudge a value up or down by a consistent amount and the range is small enough to navigate that way, the buttons make the interaction faster and more forgiving than typing. This works well when the value has a defined step and range.

Labels and Help text

For guidance on labels and help text, check out our Labels and Help pattern.

Validation

For form validation guidance, check out our Form Errors and Validation pattern.

Content

Content within the Number Field should clearly communicate the expected numerical value through labels, prefixes, and suffixes.

Keyboard Interaction

Users can navigate the Number Field using standard keyboard controls.

Code

Implementation
NumberField Props

Common Examples

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

function ExampleComponent() {
  return <NumberField label="Quantity" />;
}

Default values

A default value can given to NumberField to use the field in an uncontrolled mode.

Controlled usage

The NumberField can be controlled. This means you can maintain the state outside the component. Listen for new values with onChange and supply state back into the value prop.

Empty

The NumberField allows not only 0, but also the ability for the input to be completely cleared out. This is represented by null in the onChange, value, and defaultValue props.

Step value

The increment and decrement functionality of the NumberField defaults to adding or subtracting 1, but can be modified to add or subtract another number. This value applies to the visual +/- buttons as well as keyboard up/down keys.Note that step does not enforce that the value is a multiple of the step. Instead, it will add to or subtract from the current value.

Min and max values

The minValue and maxValue props define the bounds of the NumberField. The stepper buttons and keyboard up/down keys clamp the value between minValue and maxValue: if value + step > maxValue, the result of incrementing is maxValue, and if value - step < minValue, the result is minValue.

minValue and maxValue do not strongly prevent the user from entering an out-of-bounds value by typing or pasting. The component does not validate input internally. When bounds must be enforced, handle validation in your own code and surface feedback via the error prop. See Errors for an example.

Negative values

The NumberField defaults to a minimum of 0, but supports negative number inputs by setting a lower minValue.

Fractional values

The NumberField defaults to integers, but supports decimal number inputs with the maximumFractionDigits and minimumFractionDigits props.

Be careful! Forgetting to set minimumFractionDigits or maximumFractionDigits can result in your numbers being rounded unexpectedly.

Hiding increment/decrement buttons

The +/- buttons can be optionally hidden using the hideControls prop. When hidden, users can still change the value by typing directly into the input or using keyboard up/down arrow keys.

Errors

Error messages can be applied to the component via the error prop.

The component does not do validation internally. For example, it may be possible for a user to enter a value outside the minValue/maxValue without knowing it unless you provide an error message. See Min and max values for details.

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.

<NumberField
  label="Quantity"
  minValue={0}
  maxValue={100}
  step={1}
  maximumFractionDigits={0}
  minimumFractionDigits={0}
  value={10}
  defaultValue={0}
  hideControls={false}
  onChange={(value) => console.log(value)}
  description="Enter a quantity"
  error="Invalid value"
  hint="Must be between 0 and 100"
  size="medium"
  loading={false}
  disabled={false}
  readOnly={false}
  required={false}
  placeholder="Enter quantity"
/>

`NumberField` Props

Properties

number | null

Default value for uncontrolled number field.

boolean

default:"false"

Whether to hide the increment/decrement buttons.

number

default:"0"

Maximum number of decimal places to display and allow.

number

Maximum allowed value for the number field.

number

default:"0"

Minimum number of decimal places to display.

number

Minimum allowed value for the number field.

(value: number | null) => void

Callback fired when the value changes.

number

default:"1"

Step value for increment/decrement operations.

number | null

Controlled value of the number field.

Additional field props

The component also support the following props which are common to most field components:

string

Descriptive text displayed below the input field

boolean

default:"false"

Whether the number field is disabled

"off" | "polite" | "assertive"

default:"assertive"

ARIA live region setting for error announcements

ReactElement | string | boolean

Error message or element to display below the input

boolean

default:"false"

Visually hides the label while keeping it accessible to screen readers via aria-label.

string

Hint text displayed below the input field

boolean

default:"false"

When true, applies a subdued primary background to draw attention to the field.

string

Label for the field. Supports inline markdown formatting.

Omitting label is deprecated and will be required in v4.0.0. Use hideLabel to visually hide it.

object

Additional props to pass to the Label component

boolean

default:"false"

Whether to show a loading spinner in the input field

string

Additional information to display with the label

string

Placeholder text when no value is present

string | ReactElement

boolean

default:"false"

Whether the number field is read-only

boolean

default:"false"

Whether the number field is required

"small" | "medium" | "large"

default:"medium"

Size variant of the number field

string | ReactElement

Concepts & Guidelines

Anvil2

Resources

Number Field - Web

Anatomy

Options

Sizes

Prefix

Suffix

Behavior

Overflow

Visual States

Widths

Usage Guidelines

How to Use

Read-only

Prefixes and suffixes

Prefix

Suffix

Hiding/Showing the +/- controls

Labels and Help text

Validation

Content

Keyboard Interaction

Code

Common Examples

Default values

Controlled usage

Empty

Step value

Min and max values

Negative values

Fractional values

Hiding increment/decrement buttons

Errors

Markdown in labels

Hide the label

`NumberField` Props

Properties

Additional field props

​Anatomy

​Options

​Sizes

​Prefix

​Suffix

​Behavior

​Overflow

​Visual States

​Widths

​Usage Guidelines

​How to Use

​Read-only

​Prefixes and suffixes

Prefix

Suffix

Hiding/Showing the +/- controls

​Labels and Help text

​Validation

​Content

​Keyboard Interaction

​Code

​Common Examples

​Default values

​Controlled usage

​Empty

​Step value

​Min and max values

​Negative values

​Fractional values

​Hiding increment/decrement buttons

​Errors

​Markdown in labels

​Hide the label

​NumberField Props

​Properties

​Additional field props

Anatomy

Options

Sizes

Prefix

Suffix

Behavior

Overflow

Visual States

Widths

Usage Guidelines

How to Use

Read-only

Prefixes and suffixes

Labels and Help text

Validation

Content

Keyboard Interaction

Code

Common Examples

Default values

Controlled usage

Empty

Step value

Min and max values

Negative values

Fractional values

Hiding increment/decrement buttons

Errors

Markdown in labels

Hide the label

`NumberField` Props

Properties

Additional field props