Forms

NumberInput

Numeric input with locale-aware formatting, min and max bounds, and step increments emitting a number or null.

import { NumberInput } from '@lostgradient/cinder/number-input';
formnumeric
01

Overview

Numeric text input with increment and decrement stepper controls.

Usage

svelte 
<script lang="ts">
  import NumberInput from '@lostgradient/cinder/number-input';
</script>

<NumberInput />
Live preview
02

When to use

Use when
  • Collecting a bounded numeric value such as a quantity, price, or age.
  • Needing locale-aware display formatting on top of a native number input.
Avoid when
  • Selecting a value within a continuous range visually — use slider instead.
  • Collecting free-form text or non-numeric content — use input instead.
03

Examples

Basic number input

Numeric field with label, bounds, and a committed-value display.

04

Props

Props for number-input
Name Type Default Required Bindable Description
id text req HTML id for the underlying input, used to associate the <label> and ARIA attributes. Required.
value number | null null bind Bindable current numeric value, or null when the field is empty.
min number | undefined Minimum permitted value; the stepper decrement button disables when this bound is reached.
max number | undefined Maximum permitted value; the stepper increment button disables when this bound is reached.
step number | undefined Amount added or subtracted per stepper click or arrow-key press. Default 1.
format Intl.NumberFormatOptions Locale-aware formatting options passed to Intl.NumberFormat. Supports all Intl.NumberFormatOptions properties such as style ('decimal', 'currency', 'percent', 'unit'), currency, minimumFractionDigits, maximumFractionDigits, and notation. Defaults to locale-standard decimal formatting when omitted.
locale text BCP 47 locale tag used for number formatting and parsing. Defaults to the nearest LocaleProvider locale, then navigator.language after mount and en-US during server rendering.
disabled boolean When true, disables the input and stepper buttons, matching the native disabled attribute.
required boolean Marks the input as required for form validation, matching the native required attribute.
name text Name used to identify this field's value in form data.
label text Visible label text rendered above the input and linked via for/id.
description text Helper text rendered below the input and associated via aria-describedby.
error text Error message rendered below the input; also sets aria-invalid on the input.
inputAttachment Attachment<HTMLInputElement> Attachment for native input access and lifecycle-scoped listeners.
onchange (value: number | null) => void
onblur unknown req