Number Field

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

defaultValue

number | null

Default value for uncontrolled number field.

hideControls

boolean

default:"false"

Whether to hide the increment/decrement buttons.

maximumFractionDigits

number

default:"0"

Maximum number of decimal places to display and allow.

maxValue

number

Maximum allowed value for the number field.

minimumFractionDigits

number

default:"0"

Minimum number of decimal places to display.

minValue

number

Minimum allowed value for the number field.

onChange

(value: number | null) => void

Callback fired when the value changes.

step

number

default:"1"

Step value for increment/decrement operations.

value

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:

description

string

Descriptive text displayed below the input field

disabled

boolean

default:"false"

Whether the number field is disabled

errorAriaLive

"off" | "polite" | "assertive"

default:"assertive"

ARIA live region setting for error announcements

error

ReactElement | string | boolean

Error message or element to display below the input

hideLabel

boolean

default:"false"

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

hint

string

Hint text displayed below the input field

isHighlighted

boolean

default:"false"

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

label

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.

labelProps

object

Additional props to pass to the Label component

boolean

default:"false"

Whether to show a loading spinner in the input field

moreInfo

string

Additional information to display with the label

placeholder

string

Placeholder text when no value is present

prefix

string | ReactElement

readOnly

boolean

default:"false"

Whether the number field is read-only

required

boolean

default:"false"

Whether the number field is required

size

"small" | "medium" | "large"

default:"medium"

Size variant of the number field

suffix

string | ReactElement

​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

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