Headless Number Field

New version v0.0.9 🚀

An unstyled, fully accessible spinbutton for Phoenix LiveView, stepper buttons, drag-to-scrub, locale-aware formatting, and full keyboard support built in. You bring the styling.

Installation:

mix mishka.ui.gen.headless number_field

Source: View Source

Package: Mishka Chelekom

Tags:

Headless Base UI Accessible JS

Overview of the Phoenix and LiveView Headless Number Field Component

The Mishka Chelekom Headless Number Field ships zero opinionated styling - only the semantic markup, full WAI-ARIA spinbutton wiring, press-and-hold stepper buttons, optional drag-to-scrub, and locale-aware formatting via Intl.NumberFormat. Every part - scrub-area, decrement, input, increment and hidden-input - is addressable through a *_class attribute, so you style it entirely with your own Tailwind classes while the accessibility and behavior keep working underneath.

**Headless = bring your own design.** The example below is a faithful port of Base UI's own Number Field demo. Copy it, then swap the classes for your design system - the behavior never changes.

Base UI Number Field example (Phoenix headless)

Amount

<.number_field
  id="baseui-number_field-hero"
  value={100}
  scrub_cursor
  class="flex flex-col items-start gap-1"
  scrub_area_class="cursor-ew-resize font-bold select-none"
  scrub_area_label_class="cursor-ew-resize text-sm font-bold text-neutral-950 dark:text-white"
  scrub_cursor_class="drop-shadow-[0_1px_1px_#0008] filter"
  group_class="flex h-8"
  decrement_class="flex h-full w-8 items-center justify-center border border-r-0 border-neutral-950 bg-white bg-clip-padding text-neutral-950 outline-0 select-none dark:border-white dark:bg-neutral-950 dark:text-white hover:not-data-[disabled]:bg-neutral-100 dark:hover:not-data-[disabled]:bg-neutral-800 active:not-data-[disabled]:bg-neutral-200 dark:active:not-data-[disabled]:bg-neutral-700 data-[disabled]:border-neutral-500 data-[disabled]:text-neutral-500 dark:data-[disabled]:border-neutral-400 dark:data-[disabled]:text-neutral-400"
  increment_class="flex h-full w-8 items-center justify-center border border-l-0 border-neutral-950 bg-white bg-clip-padding text-neutral-950 outline-0 select-none dark:border-white dark:bg-neutral-950 dark:text-white hover:not-data-[disabled]:bg-neutral-100 dark:hover:not-data-[disabled]:bg-neutral-800 active:not-data-[disabled]:bg-neutral-200 dark:active:not-data-[disabled]:bg-neutral-700 data-[disabled]:border-neutral-500 data-[disabled]:text-neutral-500 dark:data-[disabled]:border-neutral-400 dark:data-[disabled]:text-neutral-400"
  input_class="h-full w-[7ch] border border-neutral-950 bg-white px-2 text-left text-sm font-normal text-neutral-950 tabular-nums any-pointer-coarse:text-base dark:border-white dark:bg-neutral-950 dark:text-white focus:z-1 focus:outline-2 focus:-outline-offset-1 focus:outline-neutral-950 dark:focus:outline-white"
>
  <:scrub_area>Amount</:scrub_area>
  <:scrub_cursor_icon>
    <svg width="26" height="14" viewBox="0 0 24 14" fill="black" stroke="white" style="display: block;">
      <path d="M19.5 5.5L6.49737 5.51844V2L1 6.9999L6.5 12L6.49737 8.5L19.5 8.5V12L25 6.9999L19.5 2V5.5Z" />
    </svg>
  </:scrub_cursor_icon>
  <:decrement_icon>
    <svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-linecap="square" stroke-linejoin="round" style="display: block;">
      <path d="M1.5 8h13" />
    </svg>
  </:decrement_icon>
  <:increment_icon>
    <svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-linecap="square" stroke-linejoin="round" style="display: block;">
      <path d="M1.5 8h13M8 14.5v-13" />
    </svg>
  </:increment_icon>
</.number_field>

Parts & data attributes

Each part carries a stable data-part and a structural chelekom-number_field__* class you can target, plus root-level state attributes reflecting disabled/readonly/ required/scrubbing.

Part	data-part	State / ARIA	Purpose
Root	root	data-disabled, data-readonly, data-required, data-scrubbing	Carries the NumberField hook; reads min/max/step/format/locale from data attributes.
Scrub area / cursor	scrub-area / scrub-area-cursor	data-direction, data-pixel-sensitivity	Optional drag region (e.g. a label) that scrubs the value; optional custom cursor shown while scrubbing.
Decrement / Increment	decrement / increment	aria-label, aria-controls, tabindex="-1"	Stepper buttons; press-and-hold to auto-repeat.
Input	input	aria-roledescription	The visible, locale-formatted text input.
Hidden input	hidden-input	aria-hidden="true", tabindex="-1"	Visually hidden type=number input carrying the raw value for form submission.

Accessibility

Follows the WAI-ARIA Spinbutton pattern : Arrow Up/Down step the value by step (Shift for large_step, Alt for small_step), PageUp/PageDown step by the large step, Home/End jump to min/max, and the mouse wheel can scrub the value when focused (allow_wheel_scrub). The input exposes aria-roledescription and the stepper buttons carry aria-label and aria-controls.

Headless Number Field component props

Name	Type	Required	Description
id	string	Yes	Unique id (required by the hook).
name	string	No	Name for the hidden form input.
value	any	No	Current/initial numeric value.
min / max	any	No	Minimum / maximum value.
step	any	No	Step for buttons/arrows/scrub (number or "any"). Defaults to 1.
small_step	any	No	Step while holding Alt. Defaults to 0.1.
large_step	any	No	Step while holding Shift (and PageUp/PageDown). Defaults to 10.
snap_on_step	boolean	No	Snap to the nearest step on increment/decrement.
allow_out_of_range	boolean	No	Let typed values exceed min/max (steps still clamp).
allow_wheel_scrub	boolean	No	Scrub with the mouse wheel while focused.
format	map	No	Intl.NumberFormat options map (currency/percent/unit/…).
locale	string	No	BCP-47 locale for formatting/parsing.
disabled	boolean	No	Disable interaction (data-disabled).
readonly	boolean	No	Block changes but stay focusable (data-readonly).
required	boolean	No	Mark required for form validation (data-required).
placeholder	string	No	Input placeholder.
on_change	string	No	LiveView event pushed on change (payload carries the value).
on_commit	string	No	LiveView event pushed on commit - blur/release (payload carries the value).
form	string	No	Form id owning the hidden input (when rendered outside the form).
aria_roledescription	string	No	Role description for the input. Defaults to "Number field".
buttons	boolean	No	Render the increment/decrement buttons. Defaults to true.
scrub_direction	string	No	Scrub axis: horizontal \| vertical. Defaults to horizontal.
scrub_sensitivity	any	No	Pixels of movement per step while scrubbing. Defaults to 2.
scrub_teleport	any	No	Cursor wrap distance (px) from the scrub-area center.
scrub_cursor	boolean	No	Render a custom cursor element for the scrub area.
*_class	any	No	Per-part classes: class, scrub_area_class, scrub_area_label_class, scrub_cursor_class, group_class, decrement_class, increment_class, input_class.
scrub_area / scrub_cursor_icon	slot	No	Optional drag region (e.g. a label) that scrubs the value / custom icon rendered inside the scrub-area-cursor part.
decrement_icon / increment_icon	slot	No	Custom icon rendered inside the decrement/increment button (replaces the default minus/plus).

NumberField CLI Arguments

Name	Type	Options	Recommended?
`--type`	string	number_field	Yes
`--only`	string	number_field	Yes
`--module`	string	Something	NO