Number Input

Demo & usage

More examples

<sv-number-input label="Price" variant="currency" [decimals]="2" [step]="0.5" [min]="0" [(value)]="price" />

<sv-number-input
  formControlName="quantity"
  label="Quantity"
  [min]="1" [max]="99"
  [required]="true"
  [errorMessage]="form.controls.quantity.invalid ? 'Enter 1–99' : ''" />

<sv-number-input preset="quantity" [min]="1" [max]="10" ariaLabel="Quantity" [(value)]="qty" />

<p id="stock-note">Only 3 left — your cart has 5</p>

<sv-number-input
  ariaLabel="Quantity, Aurora Runner"
  ariaDescribedby="stock-note"
  [invalid]="true"
  [max]="3"
  [(value)]="qty" />

When to use

• Entering a precise number with optional min/max bounds and stepping.
• Quantities, prices, durations — anything where the exact value matters.
• For approximate values across a range, a Slider is friendlier.

Async states

None — this component has nothing to load, so it has no loading, empty or error state to drive.

Outputs

Customization & theming

• Add `prefix`/`suffix` adornments, or use a `variant` preset (currency → $, percentage → %); set `size`.
• Clamp with `min` / `max`, control decimal places with `decimals`, and the increment with `step`.
• Add `label`, `hint`, `errorMessage`, `required`, `placeholder`, `name`; two-way bind `[(value)]` or use a reactive control; listen to `(changed)`.
• Use `preset="quantity"` for a compact stepper with large +/– buttons, ideal for product pages and cart rows.

Best practices

• Do: Set `min`/`max` so out-of-range values are clamped on input and via the +/– buttons.
• Do: Use `prefix`/`suffix` (or the `variant` preset) for units (e.g. $, %) rather than the label alone.
• Do: Set `currency` (an ISO 4217 code) rather than relying on `variant="currency"`, which renders `$` for compatibility. With `locale` set, the symbol AND the side it goes on come from the platform's own CLDR data — `de-DE` writes `1.234,50 €` and `de-CH` writes `CHF 1'234.50`, so a `prefix` input can only ever produce the American shape.
• Tip: An empty `locale` means "do not localise", not "use the browser's". Defaulting to the browser would change what every existing caller renders the day it runs on a German laptop, so opting in is the only version of this that is not a silent behaviour change.
• Don't: Don't expect `locale` to change the input box. This is an `<input type="number">` and its value is canonical by specification — `.` for the decimal, no grouping — so `1.234,50` cannot go in the field. The browser already owns that job and does it: a German user on a German browser types `12,5` and the element reports `12.5`. What `locale` changes is the string screen readers announce, which the component builds itself.
• Tip: Set `ariaLabel` when there is no visible `label` (e.g. a compact inline stepper). The +/– buttons take their names from it too, so a list of steppers is not five pairs of "Increase value".
• Do: When the message explaining the limit is rendered by the parent, pass its id as `ariaDescribedby` and set `[invalid]` — don't re-send the text as `errorMessage`, which would render it twice.

Accessibility

• Built on the native `<input type="number">` — implicit spinbutton role with full keyboard support (Arrow Up/Down and direct typing); the +/– buttons have descriptive `aria-label`s.
• A unique id is generated automatically so the `<label for>` association works without `inputId`; use `ariaLabel` when there is no visible label.
• `prefix`/`suffix` are announced via `aria-valuetext` (e.g. "$12.00"); `hint` and `errorMessage` are linked with `aria-describedby`, and `errorMessage` sets `aria-invalid`.
• The +/– buttons are named after the field (`label`, else `ariaLabel`), so several steppers on one page are told apart.
• `ariaDescribedby` appends ids owned by a parent to the field's own description, and `invalid` marks the value wrong when the parent renders the reason. The border follows `aria-invalid` either way, so the visual and the announced state never disagree.
• Implements ControlValueAccessor — works with `[(ngModel)]` and reactive forms; `formControl.disable()` disables the input and buttons.