Forms

NumberField

A number typed in the reader's own format, stepped with the keyboard or two buttons, and bound and submitted as a plain number.

Usage

Bind the value: a number, or null when the field is empty. The user types the number as their locale writes it, such as 1,234.5 or 1.234,5; when they leave the field it is written with the locale's grouping and the digits of format.

Quantity

From 1 to 99

Amount

USD

Try 1234.5, then leave the field

Bound values: quantity = 1, amount = null

Order.svelte

<script>
  import { NumberField } from 'sveltier';
  let quantity = $state(1);
  let amount = $state(null);
</script>

<NumberField label="Quantity" name="quantity" min={1} max={99} step={1} bind:value={quantity} />

<!-- Digits only in format: the currency goes in prepend, so the text stays editable. -->
<NumberField
  label="Amount"
  name="amount"
  min={0}
  format={{ minimumFractionDigits: 2, maximumFractionDigits: 2 }}
  required
  bind:value={amount}
>
  {#snippet prepend()}USD{/snippet}
</NumberField>

Range and steps

min and max stop the keys and the buttons. A typed value outside them is not changed for the user: the field says what to enter instead. With step, the keys and buttons move along the steps counted from min, and a typed value between two steps is an error; without it they move by 1 and any number is accepted.

Format and currency

format takes Intl.NumberFormat options for the digits only: grouping and fraction digits. A currency or percent sign in the text would make it unreadable as a number once the user edits it, so put the currency or unit in prepend or append; in development, a currency or percent style warns.

In a form

With name, a hidden input submits the plain number, such as 1234.5, while the field shows 1,234.50. Validation works as on a TextField: required, rules (they receive the number), error and validateOn.

Accessibility

The input is a spinbutton with its value, range and the formatted text as aria-valuetext.
↑ and ↓ move one step, Page Up and Page Down ten, Home and End go to min and max.
The decrease and increase buttons are named, stay out of the tab order (the keys do the same), keep focus in the field, and are at least 24 px square.
Phones show a number keypad: a numeric one for whole numbers of zero or more, a decimal one otherwise.

API

Name	Type	Default	Description
`variant`	`'outlined' \| 'tonal' \| 'elevated' \| 'text' \| 'plain'`	`'outlined'`	How the box is drawn.
`color`	`Color`	`'primary'`	The accent of the focused field. An invalid field uses `error`.
`size`	`'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`	`'md'`	Height and text size, matching a Button of the same size.
`density`	`'compact' \| 'default' \| 'comfortable'`	`'default'`	Multiplies the height and padding, never the text.
`rounded`	`boolean \| 'none' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'`	`true`	Corner rounding. `true` keeps the theme's radius.
`disabled`	`boolean`	`false`	Mutes the field and disables its control.
`label`	`string`	`–`	The visible label, linked to the control. Without it, name the control with `aria-label`.
`hint`	`string`	`–`	Help under the field. An error replaces it.
`error`	`FieldError`	`–`	An error from outside the field, such as the server's answer: a message, a list of which the first is shown, or `true` for an invalid state described elsewhere.
`prepend`	`Snippet`	`–`	Content at the start of the box, usually an icon.
`append`	`Snippet`	`–`	Content at the end of the box: an icon, a unit or a button.
`value`	`number \| null`	`–`	The number, or `null` when the field is empty. Bindable.
`min`	`number`	`–`	The smallest value. The keys and buttons stop here; a smaller typed value is an error.
`max`	`number`	`–`	The largest value. The keys and buttons stop here; a larger typed value is an error.
`step`	`number`	`–`	How far the arrow keys and the buttons move; Page Up and Page Down move ten steps. When set, a typed value off the steps, counted from `min`, is an error. When not set, they move by 1 and any number is accepted, decimals included.
`format`	`Intl.NumberFormatOptions`	`{ maximumFractionDigits: 20 }`	How the number is written once the user leaves the field, as `Intl.NumberFormat` options in the app's locale: digits only, such as `{ minimumFractionDigits: 2 }`, so the user can edit what they see. Put a currency or a unit in `prepend` or `append`.
`controls`	`boolean`	`true`	Shows decrease and increase buttons at the end of the field.
`rules`	`readonly Rule<number>[]`	`–`	Checks run in order after the HTML constraints, with the number. The first message is shown.
`validateOn`	`'blur' \| 'input' \| 'submit'`	`–`	When the message shows. Defaults to the form's setting, else `'blur'`.
`required`	`boolean`	`false`	The field must not be empty. Adds an asterisk to the label.
`readonly`	`boolean`	`false`	The number can be read and copied but not changed.
`name`	`string`	`–`	Submits the plain number, such as `1234.5`, under this name in a form.
`style`	`string \| null`	`–`	Inline style of the field's root element.
`class`	`ClassValue \| null`	`–`	Classes added after the component's own: a string, an array or an object.
`ref`	`HTMLInputElement \| null`	`–`	The root element, bindable with `bind:ref`.