Number Input

Provides controls for editing, incrementing or decrementing numeric values using the keyboard or the pointer.

# Features

Clamp value between a configurable minimum and maximum, and snap to step values.
Round values to a specific number of fraction digits & handle rounding errors.
Press and hold the stepper buttons to continuously increment or decrement.
Use the keyboard to increment and decrement the value according to the step value.
Use the scroll wheel to increment and decrement the value.

# Anatomy

Typically, a number input consists of:

Root: The element that listens to all events.
- Input: The element that shows current value and allows user to type a new value.
- Label: The accessible label for the input.
- Increment: The optional spin button to increment the value.
- Decrement: The optional spin button to decrement the value.

<script>
	import { createNumberInput } from '@grail-ui/svelte';

	const { useNumberInput, labelAttrs, inputAttrs, incrementAttrs, decrementAttrs, } = createNumberInput();
</script>

<div use:useNumberInput>
	<label {...$labelAttrs}>Enter number:</label>
	<button {...$decrementAttrs}>-</button>
	<input type="text" {...$inputAttrs} bind:value />
	<button {...$incrementAttrs}>+</button>
</div>

# Examples

# Minimum and maximum

The min and max can be used to limit the entered value to a specific range. The value will be clamped when the user blurs the input field. In addition, the increment and decrement buttons will be disabled when the value is within one step value from the bounds.

createNumberInput({
	min: 0,
	max: 100,
})

# Accessibility

# Keyboard Interactions

Key	description
`▲` `PageUp`	Increment value to the next step.
`▼` `PageDown`	Decrement value to the previous next step.
`Shift+ArrowUp` `Shift+PageUp`	Increment value with the step multiplied by ten.
`Shift+ArrowDown` `Shift+PageDown`	Decrement value with the step multiplied by ten.
`Home`	Set input to minimum value.
`End`	Set input to maximum allowed value.

# API

# NumberInputConfig

Property	Description	Default
pattern?	`string` The pattern used to check the <input> element's value against.	`[0-9]*(.[0-9]+)?`
min?	`number` The minimum value of the number input.	—
max?	`number` The maximum value of the number input.	—
step?	`number \| any` The amount to increment or decrement the value by.	`1`
allowMouseWheel?	`boolean` Whether to allow mouse wheel to change the value.	`true`
clampValueOnBlur?	`boolean` Whether to clamp the value when the input loses focus (blur).	`true`
inputMode?	`text \| numeric \| decimal` Hints at the type of data that might be entered by the user. It also determines the type of keyboard shown to the user on mobile devices.	`decimal`
spinOnPress?	`boolean` Whether to spin the value when the increment/decrement button is pressed.	`true`
incrementAriaLabel?	`string` A custom aria-label for the increment button.	'Increment'
decrementAriaLabel?	`string` A custom aria-label for the decrement button.	'Decrement'

# NumberInputReturn

Property	Description
useNumberInput	`Action<HTMLElement, void>` Action for the number input root element.
labelAttrs	`Readable<Record<string, string>>` HTML attributes for the label element.
inputAttrs	`Readable<Record<string, string \| null>>` HTML attributes for the input element.
incrementAttrs	`Readable<Record<string, string \| boolean>>` HTML attributes for the increment button.
decrementAttrs	`Readable<Record<string, string \| boolean>>` HTML attributes for the decrement button.
min	`Writable<number \| null \| undefined>` The controlled minimum value of the number input.
max	`Writable<number \| null \| undefined>` The controlled maximum value of the number input.
invalid	`Readable<boolean>` Whether the number input value is invalid.
step	`Writable<number \| any>` The controlled amount to increment or decrement the value by.
valueAsNumber	`Readable<number \| undefined>` Current input value as number.

Overview

Components

Utilities