XiodUI
HomeDocs
OverviewComponentsStyling & CustomizationChangelog

Components

  • Accordion
  • Agent Steps
  • Alert
  • Alert Dialog
  • Aspect Ratio
  • Autocomplete
  • Avatar
  • Badge
  • Breadcrumb
  • Button
  • Button Group
  • Button Split
  • Calendar
  • Card
  • Carousel
  • Checkbox
  • Circular Progress
  • Collapsible
  • Color Picker
  • Combobox
  • Command
  • Context Menu
  • Copy To Clipboard
  • Corner Badge
  • Dashboard Grid
  • Date Picker
  • Dialog
  • Dot Matrix
  • Draggable
    Updated
  • Drawer
  • Empty
  • Field
  • Fieldset
  • File Upload
    Updated
  • Form
  • Frame
  • Gauge
  • Grid
  • Group
  • Input
  • Input Group
  • Input OTP
  • Input Payment
  • Input Phone
    Updated
  • Input Sensitive
  • Kbd
  • Kinetic Click
  • Label
  • List Box
    Updated
  • Loader
  • Marker
  • Menu
  • Menubar
  • Message
  • Meter
  • Morphic Toast
  • Navigation Menu
  • Number Field
  • Option Picker
  • Orb
  • Pagination
  • Popover
  • Preview Card
    Updated
  • Progress
  • Radio
  • Resizable
  • Ruler Picker
  • Scroll Area
  • Scroll Bar
  • Select
  • Separator
  • Sidebar
  • Skeleton
  • Slider
  • Sortable
  • Switch
  • Table
  • Tabs
  • Text
  • Textarea
  • Timeline
  • Toast
  • Toggle
  • Toggle Group
  • Toolbar
  • Tooltip
  • Waveform
  • Wheel Picker

Loading...

Preview Skeleton

Installation Skeleton

Usage Skeleton

API Reference Skeleton

Sponsors

Support the development of XiodUI and help us build the best component library on Earth.

+++
Sponsor on GitHub

Number Field

Previous: Navigation MenuNext: Option Picker

A numeric input with increment and decrement buttons.

Preview

Loading Preview...

Installation

bun add xiod-ui

Usage

Imports

1import {2  NumberField,3  NumberFieldDecrement,4  NumberFieldGroup,5  NumberFieldIncrement,6  NumberFieldInput,7  NumberFieldScrubArea8} from "xiod-ui/number-field";

Anatomy

1<NumberField>2  <NumberFieldGroup>3    <NumberFieldDecrement />4    <NumberFieldInput />5    <NumberFieldIncrement />6  </NumberFieldGroup>7</NumberField>

API Reference

Detailed documentation of properties and options.

NumberField

Accepts className, style and render, plus every native attribute of the element it renders.

PropTypeDefaultDescription
allowOutOfRange
boolean
false

When true, direct text entry may be outside the min/max range without clamping, so native range underflow/overflow validation can occur. Step-based interactions (keyboard arrows, buttons, wheel, scrub) still clamp.

allowWheelScrub
boolean
false

Whether to allow the user to scrub the input value with the mouse wheel while focused and hovering over the input.

NumberFieldDecrement

Accepts className, style and render, plus every native attribute of the element it renders.

PropTypeDefaultDescription
icon
ReactNode
–

Replaces this icon. Accepts any node; null renders no icon. Takes precedence over IconProvider.

nativeButton

NumberFieldGroup

Accepts className, style and render, plus every native attribute of the element it renders.

NumberFieldIncrement

Accepts className, style and render, plus every native attribute of the element it renders.

PropTypeDefaultDescription
icon
ReactNode
–

Replaces this icon. Accepts any node; null renders no icon. Takes precedence over IconProvider.

nativeButton

NumberFieldInput

Accepts className, style and render, plus every native attribute of the element it renders.

PropTypeDefaultDescription
aria-roledescription
string
'Number field'

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.

NumberFieldScrubArea

Accepts className, style and render, plus every native attribute of the element it renders.

PropTypeDefaultDescription
labelReq
string
–

The label text. Dragging across it changes the value.

direction
"horizontal"
Navigation MenuOption Picker
defaultValue
number
–

The uncontrolled value of the field when it's initially rendered.

To render a controlled number field, use the value prop instead.

disabled
boolean
false

Whether the component should ignore user interaction.

form
string
–

Identifies the form that owns the hidden input. Useful when the number field is rendered outside the form.

format
NumberFormatOptions
–

Options to format the input value.

id
string
–

The id of the input element.

inputRef
Ref<HTMLInputElement>
–

A ref to access the hidden input element.

largeStep
number
10

The large step value of the input element when incrementing while the shift key is held. Snaps to multiples of this value when snapOnStep is enabled.

locale
LocalesArgument
–

The locale of the input element. Defaults to the user's runtime locale.

max
number
–

The maximum value of the input element.

min
number
–

The minimum value of the input element.

name
string
–

Identifies the field when a form is submitted.

onValueChange
((value: number | null, eventDetails: NumberFieldRootChangeEventDetails) => void)
–

Callback fired when the number value changes.

The eventDetails.reason indicates what triggered the change:

  • 'input-change' for parseable typing or programmatic text updates
  • 'input-clear' when the field becomes empty
  • 'input-blur' when formatting (and clamping, if enabled) occurs on blur
  • 'input-paste' for paste interactions
  • 'keyboard' for arrow-key/Home/End stepping (typing digits uses 'input-change'/'input-clear')
  • 'increment-press' / 'decrement-press' for button presses on the increment and decrement controls
  • 'wheel' for wheel-based scrubbing
  • 'scrub' for scrub area drags
onValueCommitted
((value: number | null, eventDetails: NumberFieldRootCommitEventDetails) => void)
–

Callback function that is fired when the value is committed. It runs later than onValueChange, when:

  • The input is blurred after typing a value.
  • The pointer is released after scrubbing or pressing the increment/decrement buttons.

It runs simultaneously with onValueChange when interacting with the keyboard or the mouse wheel.

**Warning**: This is a generic event not a change event.

readOnly
boolean
false

Whether the user should be unable to change the field value.

required
boolean
false

Whether the user must enter a value before submitting a form.

size
"lg"|"sm"|"default"
default

The size of the component.

smallStep
number
0.1

The small step value of the input element when incrementing while the alt key is held. Snaps to multiples of this value when snapOnStep is enabled.

snapOnStep
boolean
false

Whether the value should snap to the nearest step when incrementing or decrementing.

step
number|"any"
1

Amount to increment and decrement with the buttons and arrow keys, or to scrub with pointer movement in the scrub area. To always enable step validation on form submission, specify the min prop explicitly in conjunction with this prop. Specify step="any" to always disable step validation; interactive stepping then uses a base amount of 1, while the alt and shift keys still step by smallStep and largeStep.

value
number|null
–

The raw numeric value of the field.

boolean
true

Whether the component renders a native <button> element when replacing it via the render prop. Set to false if the rendered element is not a button (for example, <div>).

boolean
true

Whether the component renders a native <button> element when replacing it via the render prop. Set to false if the rendered element is not a button (for example, <div>).

|"vertical"
'horizontal'

Cursor movement direction in the scrub area.

pixelSensitivity
number
2

Determines how many pixels the cursor must move before the value changes. A higher value will make scrubbing less sensitive.

teleportDistance
number
–

If specified, determines the distance that the cursor may move from the center of the scrub area before it will loop back around.