# nord-number-field
> Number Field is a control for entering a numeric value, with decrement and
> increment stepper buttons, optional drag-to-scrub, and locale-aware
> formatting. It ports the behaviour of Base UI's Number Field: arrow/Page
> stepping, Home/End to the bounds, press-and-hold auto-repeat, optional
> wheel/scrub, clamping, and Intl.NumberFormat formatting.
>
> Number Field is a control only — it has no built-in label, hint or error.
> Compose it inside a Field with a
> Field Label to give it a label, hint and error,
> the same way you would a native input.
>
> FORM PARTICIPATION: the value is submitted as the raw numeric string under the
> host name via FormDataController (the inner input has no name, avoiding a
> double submit). Unlike Base UI there is no hidden native number input, and —
> like the other new Nord controls — Number Field does NOT use
> ElementInternals, so it performs no native constraint validation: required,
> min, max and step are NOT enforced as form-blocking validity. min/max
> govern interactive stepping and (unless allow-out-of-range is set) clamp the
> value; required only surfaces as required/aria-required on the inner input
> for assistive technology. Authors must validate constraints themselves and
> reflect failures via invalid and a nord-field-error.
>
> ACCESSIBILITY NOTE: the inner control is a text input (with inputmode) and
> aria-roledescription="Number field", NOT role="spinbutton" and NOT a
> native type="number". A text input lets us show locale-formatted text
> (currency, percent, grouping) while keeping full text editing — assistive tech
> reads the formatted value from the input's text. We do NOT add
> aria-valuenow/valuemin/valuemax/valuetext: those are only valid on a
> range role (e.g. spinbutton/slider) and would fail aria-allowed-attr
> validation on a text input. This mirrors what Base UI's NumberFieldInput
> actually ships (only aria-roledescription).
## Usage
Number Field is a **control only** — it has no built-in label, hint or error. Pair it with a [Field](/components/field/) to give it a label, helper text and an error message, exactly like a native input. Connect the [Field Label](/components/field-label/) to the number field with the `for` attribute so it gets an accessible name and click-to-focus.
Import the number field and the Field parts you need — each import registers its custom element:
```js
import '@nordhealth/components/lib/NumberField'
import '@nordhealth/components/lib/Field'
import '@nordhealth/components/lib/FieldLabel'
import '@nordhealth/components/lib/FieldDescription'
import '@nordhealth/components/lib/FieldError'
```
Then compose the Field around the number field:
```html
Amount
Enter an amount between 1 and 100.
```
Read and write the value with the `value` property — it is a `number` (or `null` when empty), not a string:
```js
const field = document.querySelector('nord-number-field')
field.value = 42
field.addEventListener('input', () => console.log(field.value))
```
Constrain and format the field with the `min`, `max`, `step` and `format` options. `format` takes [`Intl.NumberFormat` options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat){rel="[\"nofollow\"]"} and is set as a property:
```js
field.min = 0
field.max = 1000
field.format = { style: 'currency', currency: 'EUR' }
```
Number Field renders in the light DOM, so you can style it directly with your own CSS or Tailwind utilities, and size it by setting a width on the field (or on its Field).
### Keyboard, buttons and scrubbing
- **Arrow keys** step by `step`; **Shift+Arrow** and **PageUp/PageDown** step by `large-step`; **Alt+Arrow** steps by `small-step`. **Home** and **End** jump to `min` and `max` when those are set.
- The **stepper buttons** support press-and-hold to auto-repeat. They are `tabindex="-1"`, so keyboard users step via the input while touch and assistive-technology users can still tap the buttons.
- Enable `scrub` to add a drag handle, or `allow-wheel-scrub` to change the value with the mouse wheel while the input is focused.
### Accessibility
The inner control is a text input with `inputmode`, carrying `aria-roledescription="Number field"` — **not** `role="spinbutton"` and **not** a native `type="number"`. This lets it display locale-formatted text (currency, percent, grouping) while keeping full text editing; assistive technology reads the formatted value straight from the input's text. The form value is submitted as the raw numeric string under the host `name`; the inner input has no `name`, so there is no double submit.
> **Do:** - Use for entering a single numeric value, such as a quantity, price, percentage or duration.
- Pair it with a [Field](/components/field/) and a [Field Label](/components/field-label/) connected with `for`, so it has an accessible name, helper text and an error message.
- Set `min`, `max` and `step` to constrain the value, and `format` to display it in the user's locale (currency, percent, grouping).
- Use `scrub` or `allow-wheel-scrub` when fine-grained, fast adjustment is helpful, such as in design tools.
> **Don't:** - Don’t use for non-numeric input, see [Input](/components/input/) instead.
- Don’t use for choosing from a fixed list of values, see [Select](/components/select/) or [Combobox](/components/combobox/) instead.
- Don’t add a Field Label without a `for` pointing at the number field’s `id`, or the control will have no accessible name.
- Don’t rely on the number field for validation messaging — mark the surrounding [Field](/components/field/) invalid and show a [Field Error](/components/field-error/).
## Examples
### Overview
```html
Amount
```
### Min Max
```html
Quantity
Between 0 and 10
```
### Currency
```html
```
### Percent
```html
```
### Locale
```html
```
### Wheel Scrub
```html
Zoom
Focus the field, then scroll to change the value
```
### Hide Controls
```html
Age
```
### Disabled
```html
Amount
```
### Readonly
```html
Amount
```
### Invalid
```html
Amount
Enter a valid amount
```
### Input Group
```html
Quantity
Add to cart
```
### R T L
```html
الكمية
```
### Standalone
```html
```
### Field
```html
Quantity
How many would you like?
```
### Custom Format
```html
Amount
Always shown with grouped thousands and two decimals.
```
### Custom Mask
```html
Amount
Thousands are grouped as you type; fractions cap at two digits.
```
### Start And End Slots
```html
Weight
#
kg
Slot content before (start) and after (end) the number, inside the control border.
```
### Currency Auto Placement
```html
Price (USD, en-US)
en-US is symbol-first, so $ is placed at the start automatically.
Preis (EUR, de-DE)
de-DE is symbol-last, so € is placed at the end — same prop, derived from the locale.
```
### Currency Placement Override
```html
Pris
SEK trails by default in sv-SE; currency-placement="start" forces it to the leading edge.
```
### Currency With Mask
```html
Amount
Grouped as you type; the currency symbol stays put in its slot.
```
### Unit And Percent
```html
Weight
kg
A unit label is just slotted content — no dedicated prop needed.
Completion
%
Percent is the same — slot a "%" after the number.
```
## API Reference
### Properties
- **value** (`number | null`, default: `null`) — The raw numeric value of the field, or null when empty.
The value attribute may be set as a numeric string in HTML; it is coerced
with a custom converter (Number(v), NaN -> null).
- **min** (`number | undefined`) — The minimum allowed value. Step interactions and blur-clamping clamp to it,
and the decrement button disables at/below it. Home jumps to it only when it
is finite.
- **max** (`number | undefined`) — The maximum allowed value. Step interactions and blur-clamping clamp to it,
and the increment button disables at/above it. End jumps to it only when it
is finite.
- **step** (`number | 'any'`, default: `1`) — Amount each arrow press / button click / wheel notch changes the value.
'any' disables step semantics (treated as 1 internally for stepping).
- **large-step** (`number`, default: `10`) — Step used for PageUp/PageDown and Shift+Arrow.
- **small-step** (`number`, default: `0.1`) — Step used when Alt/Option is held with Arrow keys.
- **snap-on-step** (`boolean`, default: `false`) — When true, stepping snaps the value to the nearest multiple of the step.
- **allow-out-of-range** (`boolean`, default: `false`) — When true, direct text entry may go outside min/max without clamping
(so range validation can flag it); step interactions still clamp.
- **integer** (`boolean`, default: `false`) — Restricts the field to whole numbers. The decimal separator can no longer be
typed, pasted or programmatic fractional values are rounded to the nearest
integer, and the built-in mask caps the fraction to zero. The soft keyboard
shows the plain numeric keypad.
- **allow-wheel-scrub** (`boolean`, default: `false`) — When true, scrolling the mouse wheel while focused changes the value.
- **scrub** (`boolean`, default: `false`) — When true, renders a drag handle so the user can click-drag to change the value.
- **locale** (`string | string[] | undefined`) — BCP-47 locale(s) for Intl formatting/parsing. Defaults to the runtime locale.
- **placeholder** (`string | undefined`) — Placeholder text shown when the field is empty.
- **name** (`string | undefined`) — Form field name. The value is submitted under this name via FormDataController.
- **disabled** (`boolean`, default: `false`) — Disables the control.
- **readonly** (`boolean`, default: `false`) — Read-only: the user cannot change the value, but the value is still submitted.
- **invalid** (`boolean`, default: `false`) — Applies error styling and sets aria-invalid="true" on the inner input.
- **hide-controls** (`boolean`, default: `false`) — Hides the increment/decrement stepper buttons (still steppable via keyboard).
- **currency** (`string | undefined`) — ISO 4217 currency code (e.g. USD, EUR, SEK). Setting it enables the
currency convenience: a decorative, locale-aware symbol is rendered into the
start/end slot resolved from currencyPlacement, and the currency is
folded into the input's accessible description so assistive tech announces it.
This is layered on top of the generic start/end slots — for a fully
custom symbol, omit currency and slot your own content instead. It is
independent of format: the symbol lives beside the number rather than in
the formatted text, so it composes cleanly with mask.
- **currency-placement** (`'start' | 'end' | 'auto'`, default: `'auto'`) — Which side the currency symbol is placed on. 'auto' (the default)
derives the side from the locale/currency pair via Intl (symbol-first
locales like en-US → start, symbol-last locales like de-DE → end);
'start'/'end' force the side. Has no effect unless currency is set.
- **form** (`HTMLFormElement | null`)
- **size** (`'s' | 'm' | 'l'`, default: `'m'`) — The size of the component.
- **label** (`string`, default: `''`) — Label for the control. Ignored when the control is wrapped in a
<nord-field>, which provides the label via <nord-field-label>.
- **hint** (`string | undefined`) — Optional hint text shown with the control. Ignored inside a <nord-field>,
which provides it via <nord-field-description>.
- **hint-below** (`boolean`, default: `false`) — Renders the hint below the control and any error instead of below the label.
- **hide-label** (`boolean`, default: `false`) — Visually hide the label, but still expose it to assistive technologies.
- **error** (`string | undefined`) — Optional error shown with the control. Ignored inside a <nord-field>,
which provides it via <nord-field-error>.
- **required** (`boolean`, default: `false`) — Determines whether the control is required or not.
A required control is announced as such to assistive technology and, inside
a <nord-field>, drives the required indicator on the <nord-field-label>.
When using this property you need to also set “novalidate” attribute on a form element to prevent browser from displaying its own validation errors.
- **hide-required** (`boolean`, default: `false`) — Visually hide the required indicator, but still expose the required state
to assistive technologies.
### Events
- **input** (`NordEvent`) — Dispatched as the value changes during interaction (typing a parseable value, clearing, each step, each button tick, each wheel notch, each scrub increment).
- **change** (`NumberFieldChangeEvent`) — Dispatched when the value is committed (on blur, keyboard step, or pointer-up after a button hold or scrub). Carries the numeric value and a reason.
### Slots
- **start** — Leading content inside the control, before the input (e.g. a unit or currency symbol). Sits after the decrement stepper button.
- **end** — Trailing content inside the control, after the input (e.g. a unit label or %). Sits before the increment stepper button.
### Methods
- **focus** — `focus(options?: FocusOptions) => void` — Focus the inner input (mirrors combobox focus).
### CSS Custom Properties
- `--n-number-field-control-min-inline-size` (default: `8ch`) — Minimum inline size (width) of the numeric input portion of the control.
- `--n-number-field-step-inline-size` (default: `var(--n-space-xl)`) — Inline size (width) of each increment/decrement stepper button.
- `--n-number-field-background` (default: `var(--n-input-background, var(--n-color-surface))`) — Background of the control.
- `--n-number-field-border-color` (default: `var(--n-input-border-color, var(--n-color-border-strong))`) — Border color of the control.
- `--n-number-field-border-radius` (default: `var(--n-input-border-radius, var(--n-border-radius-s))`) — Corner radius of the control.
### Dependencies
- `icon`