Spin button Preview

A spin button is a specialized input that lets someone easily increase or decrease a value within a set range, like dates in a month.

Spin buttons are good for precise increments in small ranges. If the range is very large or very small (less than three values), use an input instead. If the values can be imprecise and a visual representation of the value on the range is helpful, try a slider.

Loading...
Open in CodeSandbox
Spin button storybook
React guidance
Spin button pattern
WAI guidance

Properties

appearance

Controls the colors and borders of the input.

“outline” “underline” “filled-darker” “filled-lighter”
Default:
“‘outline’”

as

“input”
Default:
none

decrementButton

Renders the decrement control.

WithSlotShorthandValue<{ as?: "button"; } & Pick<DetailedHTMLProps<ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "key" | keyof ButtonHTMLAttributes<...>> & { ...; } & { ...; }>
Default:
none

defaultValue

Initial value of the control (assumed to be valid). Updates to this prop will not be respected.

Use this if you intend for the SpinButton to be an uncontrolled component which maintains its own value. For a controlled component, use value instead. (Mutually exclusive with value .)

Use null to indicate the control has no value.

number null
Default:
none

displayValue

String representation of value .

Use this when displaying the value to users as something other than a plain number. For example, when displaying currency values this might be “$1.00” when value is 1 .

Only provide this if the SpinButton is a controlled component where you are maintaining its current state and passing updates based on change events. When SpinButton is used as an uncontrolled component this prop is ignored.

string
Default:
none

incrementButton

Renders the increment control.

WithSlotShorthandValue<{ as?: "button"; } & Pick<DetailedHTMLProps<ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "key" | keyof ButtonHTMLAttributes<...>> & { ...; } & { ...; }>
Default:
none

input

Input that displays the current value and accepts direct input from the user. Displayed value is formatted.

This is the primary slot.

({ as?: "input"; } & Omit<Pick<DetailedHTMLProps<InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, "key" | keyof InputHTMLAttributes<...>> & { ...; }, "children"> & { ...; })
Default:
none

onChange

Callback for when the committed value changes.

  • User presses the up/down buttons (on single press or every spin)
  • User presses the up/down arrow keys (on single press or every spin)
  • User commits edits to the input text by focusing away (blurring) or pressing enter. Note that this is NOT called for every key press while the user is editing.
((event: SpinButtonChangeEvent, data: SpinButtonOnChangeData) => void)
Default:
none

precision

How many decimal places the value should be rounded to.

The default is calculated based on the precision of step : i.e. if step = 1, precision = 0. step = 0.0089, precision = 4. step = 300, precision = 2. step = 23.00, precision = 2.

number
Default:
none

root

The root element of SpinButton is a container <div> . The root slot receives the className and style specified on the <SpinButton> . All other native props are applied to the primary slot: input .

WithSlotShorthandValue<{ as?: "span"; } & Pick<DetailedHTMLProps<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "key" | keyof HTMLAttributes<...>> & { ...; } & { ...; }>
Default:
none

size

Size of the input.

“small” “medium”
Default:
“‘medium’”

stepPage

Large difference between two values. This should be greater than step and is used when users hit the Page Up or Page Down keys.

number
Default:
1

value

Current value of the control (assumed to be valid).

Only provide this if the SpinButton is a controlled component where you are maintaining its current state and passing updates based on change events; otherwise, use the defaultValue property.

Use null to indicate the control has no value.

Mutually exclusive with defaultValue .

number null
Default:
none