> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.
# NumberStepper
> Edit a number with optional bounds and increment or decrement buttons.
export const StoryEmbed = ({storyId, title, height = 240}) => <>
Open in Storybook
;
`NumberStepper` combines a compact numeric text field with decrement and increment buttons. It owns numeric editing, bounds, and step interactions. Your application chooses the limits and handles persistence.
## Uncontrolled value
Use `defaultValue` to set the initial quantity. The input owns subsequent changes.
```tsx theme={null}
import { Field, NumberStepper } from 'twenty-ui/primitives/input';
export const QuantityInput = () => (
Quantity
Choose up to ten items.
);
```
## Controlled value
Pass a number or `null` through `value` and update it in `onValueChange` to own the same quantity in React state. The callback receives the next numeric value and event details.
```tsx theme={null}
import { useState } from 'react';
import { Field, NumberStepper } from 'twenty-ui/primitives/input';
export const QuantityInput = () => {
const [quantity, setQuantity] = useState(3);
return (
Quantity
Choose up to ten items.
);
};
```
Clearing the field reports `null`. Incomplete text such as `-` or `+` remains editable without reporting an invalid number until it is replaced or stepped. By default, parseable numeric edits report the bounded value; the displayed draft is normalized on blur. Values equal to the current value do not call `onValueChange` again.
## Application validation
Set `allowOutOfRange` when the application needs the parsed value before applying its own limits or validation. `onValueChange` then receives typed and pasted numbers outside the range. Uncontrolled fields, or controlled fields that accept those values, preserve them on blur. Controlled fields that reject them return to their accepted value on blur. For example, replacing `60` with `45` reports `4` and then `45`, even when `min={30}`. The application can ignore the intermediate value without accidentally saving the minimum.
Buttons and keyboard adjustments still stop at `min` and `max`. Native form validation prevents submission while an accepted value is outside that range. `allowOutOfRange` defaults to `false`.
## Bounds and interaction
`min` and `max` are inclusive. Increment and decrement buttons stop at the matching bound. Arrow Up and Arrow Down adjust the focused input by `step`, which defaults to `1`. Home and End select the corresponding bound when provided; call `event.preventBaseUIHandler()` in `onKeyDown` to keep a key's text editing behavior instead. The same step applies when Shift or Alt is held. Displayed values support up to 15 fraction digits; use a positive step within that precision for decimal adjustments.
Values use Latin digits and show grouping separators from five integer digits, such as `12,500`. Typed and pasted group separators of the browser's locale are accepted.
`step` controls adjustments; it does not round typed values to a step. When `min` is set, native form validation also requires `min` plus a multiple of `step`: with the default `step` of `1`, a typed `2.5` blocks submission. Set `showButtons={false}` for text editing with the same keyboard behavior.
Each button has a default accessible name. Use `decrementLabel` and `incrementLabel` to provide contextual or translated names. Give the input a visible `Field.Label`, `aria-label`, or `aria-labelledby`.
## Forms and focus
Use `name` to include the numeric value in a form. `form` associates it with a form elsewhere in the document. The adjustment buttons use `type="button"`, so adjusting a value does not submit the form. `required` participates in native validation.
Use a controlled `value` when your application needs to reset the field. A native form reset does not reset the numeric state.
`disabled` prevents changes and excludes the value from form submission. `readOnly` prevents changes while keeping the input focusable and its value available to the form.
Native input attributes and handlers, `className`, `style`, and `ref` apply to the visible input. For example, call `ref.current?.focus()` to focus the field. Combine the input with `Field.Description` and `Field.Error` for guidance and validation messages.
## Front component renderer
The React and Preact renderer sandboxes support keyboard adjustments, bounds, and form values. Pointer stepping and text editing are currently blocked by missing input selection and native event support in the renderer. Pasting is not supported: without input selection, the pasted text is inserted around the whole value, that wrong number is reported, and the front component then stops rendering. These limitations do not affect normal React rendering.
## Props
Allows onValueChange to receive typed and pasted numbers outside the bounds. Native range validation still applies; buttons and keyboard adjustments remain bounded.
A user-friendly description of the input's role for assistive tech. This is a role
description, not an accessible name — use `Field.Label` or `aria-label` to name the control.
Class applied to the visible input.
Accessible name for the decrement button.
Initial number when the field owns its value.
Disables the input and both buttons, and omits the form value.
ID of the form that owns the submitted numeric value.
ID of the visible input. Generated when omitted.
Accessible name for the increment button.
Inclusive maximum. By default, onValueChange reports bounded numbers and out-of-range drafts normalize on blur.
Inclusive minimum. By default, onValueChange reports bounded numbers and out-of-range drafts normalize on blur.
Name of the numeric value submitted with a form.
Called with the next number or null and event details when the numeric value changes. Clearing reports null; incomplete text does not report a number.
Prevents numeric changes while keeping the input focusable.
Ref to the visible input element.
Allows you to replace the component's HTML element
with a different tag, or compose it with another component.
Accepts a `ReactElement` or a function that returns the element to render.
Requires a numeric value for native form submission.
Shows the decrement and increment buttons.
Amount added or subtracted by the buttons and arrow keys.
Inline styles applied to the visible input.
Controlled numeric value. Use null for an empty field.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.