# Number Field

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

## Installation

Start from a Svelte 5 application, then install the component package, shared theme, and Bits UI peer:

```bash
pnpm add coss-svelte @coss-svelte/theme bits-ui
```

Import `@coss-svelte/theme/style-coss.css` after Tailwind from the application's global stylesheet.

## Usage

```svelte
<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>

```

## 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. |

**Composition and refs**

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

Inherits from [Svelte <div> attributes](https://svelte.dev/docs/svelte/basic-markup#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. |

**Composition and refs**

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

Inherits from [Svelte <button> attributes](https://svelte.dev/docs/svelte/basic-markup#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. |

**Composition and refs**

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

Inherits from [Svelte <div> attributes](https://svelte.dev/docs/svelte/basic-markup#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. |

**Composition and refs**

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

Inherits from [Svelte <button> attributes](https://svelte.dev/docs/svelte/basic-markup#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. |

**Composition and refs**

- `bind:ref: HTMLInputElement \| null`

Inherits from [Svelte <input> attributes](https://svelte.dev/docs/svelte/basic-markup#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. |

**Composition and refs**

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

Inherits from [Svelte <div> attributes](https://svelte.dev/docs/svelte/basic-markup#Attributes).

## Implementation Details

| Field | Value |
| --- | --- |
| Status | Stable |
| Foundation | custom |
| Category | Selection & Input |
| Particles | 11 |

## Status

Stable for the current coss-svelte surface.

## Agent Notes

- Import Svelte exports directly from `coss-svelte`.
- This is Svelte 5 code: use `class`, lowercase event properties, runes, snippets, and documented `bind:*` contracts. Do not emit JSX, React hooks, `className`, `asChild`, or Base UI imports.
- Prefer this route's example and generated API table over React COSS snippets; COSS React particles are design references only.
- The copy-and-own registry is a preview. Inspect `/r/number-field.json` for the complete local file and dependency closure.
- Number Field is stable in the current source catalog.