Number Field

A specialized input for numeric values with increment/decrement controls.

<script lang="ts">
import {
	NumberField,
	NumberFieldDecrement,
	NumberFieldGroup,
	NumberFieldIncrement,
	NumberFieldInput,
} from "coss-svelte";

let value = $state<number | null>(0);
</script>

<NumberField bind:value aria-label="Amount">
	{#snippet children()}
		<NumberFieldGroup>
			<NumberFieldDecrement />
			<NumberFieldInput />
			<NumberFieldIncrement />
		</NumberFieldGroup>
	{/snippet}
</NumberField>

Installation

Install the component package, shared coss-svelte theme, and Bits UI peer.

npm install coss-svelte @coss-svelte/theme bits-ui

Usage

Import the Svelte component exports directly from the package.

import { NumberField, NumberFieldDecrement, NumberFieldGroup, NumberFieldIncrement, NumberFieldInput, NumberFieldScrubArea } from "coss-svelte";

Anatomy

NumberField
NumberFieldDecrement
NumberFieldGroup
NumberFieldIncrement
NumberFieldInput
NumberFieldScrubArea

API Reference

NumberField

A specialized input for numeric values with increment/decrement controls.

Signatures

{ value?: number | null; onValueChange?: ((value: number | null, details: NumberFieldChangeDetails) => void); onValueCommit?: ((value: number | null, details: NumberFieldChangeDetails) => void) }

Prop	Type	Default	Description
`bind:ref`	`HTMLDivElement \| null`	`null`	Bindable reference to the owned root div.
`defaultValue`	`number \| null`	`null`	Initial value and the captured native form-reset baseline.
`bind:value`	`number \| null`	`defaultValue`	Current finite numeric value. External writes are displayed without callbacks or silent clamping.
`min`	`number`	-	Minimum value for the control.
`max`	`number`	-	Maximum value for the control.
`step`	`number`	`1`	Discrete increment for keys, buttons, wheel, and scrubbing; direct text is not snapped.
`smallStep`	`number`	`0.1`	Fine-grained increment used by Alt+Arrow keys.
`largeStep`	`number`	`10`	Increment used by PageUp/PageDown and Shift+Arrow keys.
`locale`	`string \| string[]`	`"en-US"`	Locale used for deterministic numeric parsing and formatting.
`format`	`Intl.NumberFormatOptions`	`{}`	Formats the committed display value with `Intl.NumberFormat`.
`label`	`string`	`"Number" outside Field`	Visible scrub label and accessible name; an enclosing Field label is used when omitted.
`size`	`NumberFieldSize`	`"default"`	Size variant for the component.
`id`	`string`	-	ID forwarded to the form control.
`name`	`string`	-	Serializes the invariant numeric value through a hidden form control.
`form`	`string`	-	Associates the control with a form elsewhere in the document.
`required`	`boolean`	`false`	Marks the field or label as required.
`disabled`	`boolean`	`false`	Disables interaction with the control.
`readonly`	`boolean`	`false`	Keeps the input focusable while preventing value changes.
`invalid`	`boolean`	`false`	Marks the component invalid independently of parse validity.
`allowWheelScrub`	`boolean`	`false`	Allows focused wheel gestures to change the number.
`onValueChange`	`((value: number \| null, details: NumberFieldChangeDetails) => void)`	-	Runs after each accepted numeric value change with its reason, previous value, and source event.
`onValueCommit`	`((value: number \| null, details: NumberFieldChangeDetails) => void)`	-	Runs once when a semantic input, keyboard, pointer, wheel, scrub, or reset transaction commits.

children : Snippet<[]>bind:ref : HTMLDivElement | null

Inherits from Svelte <div> attributes.

NumberFieldDecrement

Decreases the shared value, including press-and-hold repetition and bound handling.

Prop	Type	Default	Description
`bind:ref`	`HTMLButtonElement \| null`	`null`	Bindable reference to the decrement button.

children : Snippet<[]>bind:ref : HTMLButtonElement | null

Inherits from Svelte <button> attributes.

NumberFieldGroup

Groups the input and step controls into one focus-ring and validation surface.

Prop	Type	Default	Description
`bind:ref`	`HTMLDivElement \| null`	`null`	Bindable reference to the presentational group div.

children : Snippet<[]>bind:ref : HTMLDivElement | null

Inherits from Svelte <div> attributes.

NumberFieldIncrement

Increases the shared value, including press-and-hold repetition and bound handling.

Prop	Type	Default	Description
`bind:ref`	`HTMLButtonElement \| null`	`null`	Bindable reference to the increment button.

children : Snippet<[]>bind:ref : HTMLButtonElement | null

Inherits from Svelte <button> attributes.

NumberFieldInput

Renders the locale-aware text input with accessible spinbutton semantics.

Prop	Type	Default	Description
`bind:ref`	`HTMLInputElement \| null`	`null`	Bindable reference to the visible spinbutton input.

bind:ref : HTMLInputElement | null

Inherits from Svelte <input> attributes.

NumberFieldScrubArea

Labels the input and supports horizontal pointer scrubbing on fine pointers.

Prop	Type	Default	Description
`label`	`string`	-	Required non-empty accessible label; custom children replace only its visual contents.
`bind:ref`	`HTMLDivElement \| null`	`null`	Bindable reference to the scrub-area wrapper.

children : Snippet<[]>bind:ref : HTMLDivElement | null

Inherits from Svelte <div> attributes.

Implementation Details

Status: Stable
Foundation: custom
Category: Selection & Input
Particles: 11