;
}
};
```tsx lines expandable theme={null}
import { NumberField } from "@servicetitan/anvil2";
function App() {
return (
);
}
export default App;
```
## Common Examples
```tsx theme={null}
import { NumberField } from "@servicetitan/anvil2";
function ExampleComponent() {
return ;
}
```
### Default values
A default value can given to `NumberField` to use the field in an uncontrolled mode.
```tsx lines expandable theme={null}
import { NumberField } from "@servicetitan/anvil2";
function App() {
return ;
}
export default App;
```
### 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.
```tsx lines expandable theme={null}
import { NumberField, Flex, Button } from "@servicetitan/anvil2";
import { useState } from "react";
function App() {
const [value, setValue] = useState(null);
const handleChange = (value: number | null) => {
setValue(value);
};
return (
);
}
export default App;
```
### 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.
```tsx lines expandable theme={null}
import { NumberField, Flex, Button } from "@servicetitan/anvil2";
import { useState } from "react";
function App() {
const [value, setValue] = useState(null);
const handleChange = (value: number | null) => {
setValue(value);
};
return (
);
}
export default App;
```
### 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.
```tsx lines expandable theme={null}
import { NumberField } from "@servicetitan/anvil2";
function App() {
return ;
}
export default App;
```
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`.
```tsx lines expandable theme={null}
import { NumberField } from "@servicetitan/anvil2";
function App() {
return (
);
}
export default App;
```
`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](#errors) for an example.
```tsx lines expandable theme={null}
import { NumberField } from "@servicetitan/anvil2";
function App() {
return (
);
}
export default App;
```
### Negative values
The `NumberField` defaults to a minimum of `0`, but supports negative number inputs by setting a lower `minValue`.
```tsx lines expandable theme={null}
import { NumberField } from "@servicetitan/anvil2";
function App() {
return ;
}
export default App;
```
### Fractional values
The `NumberField` defaults to integers, but supports decimal number inputs with the `maximumFractionDigits` and `minimumFractionDigits` props.
```tsx lines expandable theme={null}
import { NumberField } from "@servicetitan/anvil2";
function App() {
return (
);
}
export default App;
```
Be careful! Forgetting to set `minimumFractionDigits` or `maximumFractionDigits` can result in your numbers being rounded unexpectedly.
```tsx lines expandable theme={null}
import { NumberField } from "@servicetitan/anvil2";
function App() {
return ;
}
export default App;
```
### Hiding increment/decrement buttons
```tsx lines expandable theme={null}
import { NumberField } from "@servicetitan/anvil2";
function App() {
return ;
}
export default App;
```
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.
```tsx lines expandable theme={null}
import { NumberField } from "@servicetitan/anvil2";
import { useState } from "react";
function App() {
const [value, setValue] = useState(0);
return (
);
}
export default App;
```
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](#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` ``).
```tsx lines expandable theme={null}
import { Flex, NumberField } from "@servicetitan/anvil2";
function App() {
return (
);
}
export default App;
```
### 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.
```tsx lines expandable theme={null}
import { Flex, NumberField } from "@servicetitan/anvil2";
function App() {
return (
);
}
export default App;
```
```tsx theme={null}
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
Default value for uncontrolled number field.
Whether to hide the increment/decrement buttons.
Maximum number of decimal places to display and allow.
Maximum allowed value for the number field.
Minimum number of decimal places to display.
Minimum allowed value for the number field.
Callback fired when the value changes.
Step value for increment/decrement operations.
Controlled value of the number field.
### Additional field props
The component also support the following props which are common to most field components:
Descriptive text displayed below the input field
Whether the number field is disabled
ARIA live region setting for error announcements
Error message or element to display below the input
Visually hides the label while keeping it accessible to screen readers via `aria-label`.
Hint text displayed below the input field
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.
Additional props to pass to the `Label` component
Whether to show a loading spinner in the input field
Additional information to display with the label
Placeholder text when no value is present
Whether the number field is read-only
Whether the number field is required
Size variant of the number field
