cv-number

Numeric input field with ARIA spinbutton semantics, optional stepper controls, clearable behavior, and prefix/suffix slots.

Headless: createNumber

Usage

View source

html

<div class="number-demo-shell" data-demo="number" data-live-demo-height="900">
  <section class="number-demo-hero" aria-labelledby="number-demo-title">
    <div class="number-demo-copy">
      <span class="number-demo-kicker">Numeric spinbutton primitive</span>
      <h3 id="number-demo-title">
        Clamp, step, clear, and serialize numeric state through one field surface.
      </h3>
      <p>
        The headless number model owns draft text, bounds, step math, clear defaults, focus state, and ARIA
        spinbutton attributes. UIKit renders the editable surface, slots, stepper controls, sizes, and form
        integration.
      </p>
    </div>

    <dl class="number-demo-metrics" aria-label="Number contract summary">
      <div>
        <dt>Range</dt>
        <dd>min / max / step / large-step</dd>
      </div>
      <div>
        <dt>Actions</dt>
        <dd>arrows / page keys / stepper / clear</dd>
      </div>
      <div>
        <dt>State</dt>
        <dd>draft / focused / filled / invalid</dd>
      </div>
    </dl>
  </section>

  <section class="number-demo-board" aria-label="Number examples in a vault policy form">
    <form class="number-demo-form" data-number-form>
      <div class="number-demo-form-head">
        <div>
          <span>Visible policy limits</span>
          <strong>decoy-profile.local</strong>
        </div>
        <cv-badge variant="primary" pill>bounded input</cv-badge>
      </div>

      <div class="number-demo-field-grid">
        <cv-field required>
          <span slot="label">Decoy quota</span>
          <cv-number
            data-number-primary
            name="quota"
            value="30"
            default-value="30"
            min="0"
            max="100"
            step="5"
            large-step="25"
            clearable
            stepper
          >
            <span slot="suffix">GB</span>
          </cv-number>
          <span slot="description">Arrow keys step by 5. Page keys step by 25. Clear returns to 30.</span>
        </cv-field>

        <cv-field>
          <span slot="label">HOTP counter</span>
          <cv-number name="counter" value="12" min="0" max="999999" step="1" stepper clearable>
            <span slot="prefix">#</span>
          </cv-number>
          <span slot="description"
            >Stepper controls expose the same committed change event as keyboard steps.</span
          >
        </cv-field>

        <cv-field>
          <span slot="label">Retry window</span>
          <cv-number name="retry" variant="filled" value="3" min="1" max="10" step="1" clearable>
            <span slot="suffix">tries</span>
          </cv-number>
          <span slot="description">Filled variant keeps the same headless range and form contract.</span>
        </cv-field>

        <cv-field>
          <span slot="label">Timeout</span>
          <cv-number name="timeout" value="45" min="5" max="120" step="5" large-step="30">
            <span slot="suffix">sec</span>
          </cv-number>
          <span slot="description">Draft edits commit on Enter or blur, then snap through the model.</span>
        </cv-field>
      </div>

      <div class="number-demo-actions" aria-label="Programmatic number actions">
        <cv-button type="button" size="small" data-number-action="step-up">Step up</cv-button>
        <cv-button type="button" size="small" data-number-action="page-up">Page up</cv-button>
        <cv-button type="button" size="small" variant="secondary" data-number-action="reset">Reset</cv-button>
        <cv-button type="button" size="small" variant="secondary" data-number-action="validate"
          >Validate</cv-button
        >
      </div>
    </form>

    <aside class="number-demo-side" aria-label="Number event output">
      <div class="number-demo-side-head">
        <span class="number-demo-kicker">Event stream</span>
        <h4>Committed numeric changes report a stable number value, not draft text.</h4>
      </div>

      <p class="number-demo-log" role="status" aria-live="polite" data-number-output>
        Waiting for a committed number event.
      </p>

      <dl class="number-demo-live" aria-label="Live number state">
        <div>
          <dt>Primary value</dt>
          <dd data-number-mirror>30 GB</dd>
        </div>
        <div>
          <dt>Last event</dt>
          <dd data-number-active>none</dd>
        </div>
        <div>
          <dt>Range</dt>
          <dd>0 to 100</dd>
        </div>
      </dl>
    </aside>
  </section>

  <section class="number-demo-section" aria-labelledby="number-demo-matrix-title">
    <div class="number-demo-section-header">
      <span class="number-demo-kicker">Variants, bounds, and field states</span>
      <h4 id="number-demo-matrix-title">
        Use one number contract, then tune density, affordance, or validation through attributes.
      </h4>
    </div>

    <div class="number-demo-matrix" aria-label="Number state matrix">
      <div>
        <span>Range edges</span>
        <cv-number value="0" min="0" max="10" step="1" stepper></cv-number>
        <cv-number value="10" min="0" max="10" step="1" stepper></cv-number>
      </div>

      <div>
        <span>Size</span>
        <cv-number size="small" value="8" min="0" max="16"></cv-number>
        <cv-number value="16" min="0" max="32"></cv-number>
        <cv-number size="large" value="32" min="0" max="64"></cv-number>
      </div>

      <div>
        <span>Affixes</span>
        <cv-number value="19" clearable>
          <span slot="prefix">$</span>
          <span slot="suffix">.00</span>
        </cv-number>
        <cv-number value="128" variant="filled" min="16" max="512">
          <span slot="suffix">MB</span>
        </cv-number>
      </div>

      <div>
        <span>Validation</span>
        <cv-field required invalid>
          <span slot="label">Age gate</span>
          <cv-number required invalid min="18" max="120" value="16"></cv-number>
          <span slot="error">Value must be at least 18.</span>
        </cv-field>
      </div>

      <div>
        <span>Clear defaults</span>
        <cv-number value="42" default-value="10" min="0" max="100" clearable stepper></cv-number>
        <cv-number value="10" default-value="10" min="0" max="100" clearable></cv-number>
      </div>

      <div>
        <span>Read state</span>
        <cv-number read-only value="100"></cv-number>
        <cv-field disabled>
          <span slot="label">Disabled by field</span>
          <cv-number value="50" stepper></cv-number>
        </cv-field>
      </div>
    </div>
  </section>
</div>

<script type="module">
  document.querySelectorAll('.number-demo-shell[data-demo="number"]:not([data-ready])').forEach((shell) => {
    shell.dataset.ready = 'true'

    const form = shell.querySelector('[data-number-form]')
    const output = shell.querySelector('[data-number-output]')
    const mirror = shell.querySelector('[data-number-mirror]')
    const active = shell.querySelector('[data-number-active]')
    const primary = shell.querySelector('[data-number-primary]')
    const eventLabels = {
      'cv-change': 'change',
      'cv-clear': 'clear',
      'cv-focus': 'focus',
      'cv-blur': 'blur',
    }

    const readNumber = (number) => {
      if (!number) return 0
      if (typeof number.getValue === 'function') return number.getValue()
      return Number(number.value || number.getAttribute('value') || 0)
    }

    const syncMirror = () => {
      if (!mirror) return
      mirror.textContent = `${readNumber(primary)} GB`
    }

    const setOutput = (message) => {
      if (output) output.textContent = message
    }

    const getFieldName = (number) => {
      const label = number.closest('cv-field')?.querySelector('[slot="label"]')?.textContent?.trim()
      return label || number.getAttribute('name') || 'number'
    }

    const report = (event) => {
      const number = event.target instanceof HTMLElement ? event.target : null
      if (!number?.matches('cv-number')) return

      const name = getFieldName(number)
      const label = eventLabels[event.type] ?? event.type
      const value =
        event instanceof CustomEvent && event.detail && 'value' in event.detail
          ? event.detail.value
          : readNumber(number)

      if (active) active.textContent = `${label}: ${name}`
      setOutput(`${label}: ${name} -> ${value}`)
      syncMirror()
    }

    shell.querySelectorAll('[data-number-action]').forEach((button) => {
      button.addEventListener('click', () => {
        const action = button.getAttribute('data-number-action')
        if (!primary) return

        if (action === 'step-up') {
          primary.stepUp()
          setOutput(`action: Step up -> ${readNumber(primary)}`)
        } else if (action === 'page-up') {
          primary.pageUp()
          setOutput(`action: Page up -> ${readNumber(primary)}`)
        } else if (action === 'reset') {
          primary.setValue(30)
          setOutput('action: Reset -> 30')
        } else if (action === 'validate') {
          const valid = primary.reportValidity()
          setOutput(`validation: ${valid ? 'valid' : 'invalid'} at ${readNumber(primary)}`)
        }

        if (active) active.textContent = `action: ${action}`
        syncMirror()
      })
    })

    form?.addEventListener('submit', (event) => {
      event.preventDefault()
      setOutput(`submit: quota=${readNumber(primary)}`)
    })

    Object.keys(eventLabels).forEach((eventName) => {
      shell.addEventListener(eventName, report)
    })

    syncMirror()
  })
</script>

Anatomy

<cv-number> (host)
└── <div part="base">
    ├── <span part="prefix">
    │   └── <slot name="prefix">
    ├── <input part="input" role="spinbutton" inputmode="decimal">
    ├── <span part="clear-button" role="button">       ← conditional on showClearButton
    │   └── <slot name="clear-icon">×</slot>
    ├── <span part="stepper">                           ← conditional on stepper, horizontal controls
    │   ├── <button part="increment" type="button">
    │   └── <button part="decrement" type="button">
    └── <span part="suffix">
        └── <slot name="suffix">

Attributes

Attribute	Type	Default	Reflects	Description
`value`	Number	`0`	no	Current numeric value
`default-value`	Number	`min ?? 0`	no	Value to reset to on clear; form reset restores the initial connected `value` snapshot
`min`	Number	—	no	Optional minimum boundary
`max`	Number	—	no	Optional maximum boundary
`step`	Number	`1`	no	Small increment/decrement step
`large-step`	Number	`10`	no	Large increment/decrement step (`PageUp`/`PageDown`)
`name`	String	`""`	no	Form field name for submit serialization
`disabled`	Boolean	`false`	yes	Prevents interaction and dims the component
`read-only`	Boolean	`false`	yes	Keeps focusable/announced but blocks user mutation
`required`	Boolean	`false`	yes	Marks the field as required for form validation
`clearable`	Boolean	`false`	yes	Shows a clear button when the value differs from default
`stepper`	Boolean	`false`	yes	Shows increment/decrement stepper buttons
`placeholder`	String	`""`	no	Placeholder text displayed when the input is empty
`size`	String	`"medium"`	yes	Component size: `small` \| `medium` \| `large`
`variant`	String	`"outlined"`	yes	Visual variant: `outlined` \| `filled`
`aria-label`	String	`""`	no	Accessible label
`aria-labelledby`	String	`""`	no	ID reference to visible label
`aria-describedby`	String	`""`	no	ID reference to description

Variants

Variant	Description
`outlined`	Default style with visible border and transparent background
`filled`	Subtle background fill with no visible border

Sizes

Size	`--cv-number-height`	`--cv-number-padding-inline`	`--cv-number-font-size`
`small`	`30px`	`var(--cv-space-2, 8px)`	`var(--cv-font-size-sm, 13px)`
`medium`	`36px`	`var(--cv-space-3, 12px)`	`var(--cv-font-size-base, 14px)`
`large`	`42px`	`var(--cv-space-4, 16px)`	`var(--cv-font-size-md, 16px)`

Slots

Slot	Description
`prefix`	Content rendered before the input (e.g., currency symbol icon)
`suffix`	Content rendered after the stepper controls (e.g., unit label)
`clear-icon`	Custom icon for the clear button (default: `×`)

Note: The native <input> element is not slottable. There is no default slot.

CSS Parts

Part	Element	Description
`base`	`<div>`	Outermost wrapper element containing input and controls
`input`	`<input>`	The native input element with `role="spinbutton"`
`prefix`	`<span>`	Wrapper around the `prefix` slot
`suffix`	`<span>`	Wrapper around the `suffix` slot
`clear-button`	`<span>`	The clear button wrapper (conditionally visible)
`stepper`	`<span>`	Wrapper around increment/decrement buttons (conditionally visible)
`increment`	`<button>`	Increment stepper button
`decrement`	`<button>`	Decrement stepper button

CSS Custom Properties

Property	Default	Description
`--cv-number-height`	`36px`	Component block size
`--cv-number-padding-inline`	`var(--cv-space-3, 12px)`	Horizontal padding inside the input container
`--cv-number-font-size`	`var(--cv-font-size-base, 14px)`	Font size of the input text
`--cv-number-border-radius`	`var(--cv-radius-sm, 6px)`	Border radius of the input container
`--cv-number-border-color`	`var(--cv-color-border, #2a3245)`	Border color in default state
`--cv-number-background`	`transparent`	Background color of the input container
`--cv-number-color`	`var(--cv-color-text, #e8ecf6)`	Text color of the input value
`--cv-number-placeholder-color`	`var(--cv-color-text-muted, #6b7a99)`	Placeholder text color
`--cv-number-focus-ring`	`0 0 0 2px var(--cv-color-primary, #65d7ff)`	Box-shadow applied on focus
`--cv-number-icon-size`	`1em`	Size of prefix/suffix/clear icons
`--cv-number-gap`	`var(--cv-space-2, 8px)`	Spacing between inner elements (prefix, input, buttons, suffix)
`--cv-number-transition-duration`	`var(--cv-duration-fast, 120ms)`	Transition duration for state changes
`--cv-number-stepper-width`	`28px`	Legacy fallback for horizontal stepper button inline size
`--cv-number-stepper-button-inline-size`	`var(--cv-number-stepper-width, 28px)`	Inline size of each horizontal stepper button
`--cv-number-stepper-button-gap`	`2px`	Gap between horizontal stepper buttons

Additionally, component styles depend on theme tokens through fallback values:

Theme Property	Default	Description
`--cv-color-border`	`#2a3245`	Base border color
`--cv-color-surface`	`#141923`	Surface background color (used by `filled` variant)
`--cv-color-surface-elevated`	`#1d2432`	Stepper button background
`--cv-color-text`	`#e8ecf6`	Default text color
`--cv-color-text-muted`	`#6b7a99`	Muted text color for placeholder
`--cv-color-primary`	`#65d7ff`	Primary accent color for focus ring
`--cv-duration-fast`	`120ms`	Transition duration
`--cv-easing-standard`	`ease`	Transition timing function
`--cv-radius-sm`	`6px`	Base border radius fallback
`--cv-font-size-sm`	`13px`	Small font size
`--cv-font-size-base`	`14px`	Base font size
`--cv-font-size-md`	`16px`	Medium font size
`--cv-space-2`	`8px`	Spacing scale: small
`--cv-space-3`	`12px`	Spacing scale: medium
`--cv-space-4`	`16px`	Spacing scale: large

Visual States

Host selector	Description
`:host([disabled])`	Reduced opacity (`0.55`), `cursor: not-allowed`, no interaction
`:host([read-only])`	Normal opacity, `cursor: default`, input text not editable
`:host([required])`	No visual change by default (can be styled via part selectors)
`:host([focused])`	Focus ring applied via `--cv-number-focus-ring`
`:host([filled])`	Indicates value differs from default (e.g., for floating label transitions)
`:host([clearable])`	Clear button space reserved in layout
`:host([stepper])`	Stepper buttons rendered and visible
`:host([stepper-active="increment"])`	Transient pressed/step feedback for the increment button
`:host([stepper-active="decrement"])`	Transient pressed/step feedback for the decrement button
`:host([size="small"])`	Small size overrides
`:host([size="large"])`	Large size overrides
`:host([variant="outlined"])`	Visible border, transparent background
`:host([variant="filled"])`	Subtle background (`--cv-color-surface`), no visible border

Reactive State Mapping

cv-number is a visual adapter over headless createNumber.

UIKit properties to headless actions

UIKit Property	Direction	Headless Binding
`value`	attr/prop -> action	`actions.setValue(value)`
`disabled`	attr -> action	`actions.setDisabled(value)`
`read-only`	attr -> action	`actions.setReadOnly(value)`
`required`	attr -> action	`actions.setRequired(value)`
`placeholder`	attr -> action	`actions.setPlaceholder(value)`
`clearable`	attr -> action	`actions.setClearable(value)`
`stepper`	attr -> action	`actions.setStepper(value)`
`min`	attr -> option	passed to `createNumber(options)`
`max`	attr -> option	passed to `createNumber(options)`
`step`	attr -> option	passed to `createNumber(options)`
`large-step`	attr -> option	passed to `createNumber(options)`
`default-value`	attr -> option	passed as `defaultValue` to `createNumber(options)`
`aria-label`	attr -> option	passed as `ariaLabel` to `createNumber(options)`
`aria-labelledby`	attr -> option	passed as `ariaLabelledBy` to `createNumber(options)`
`aria-describedby`	attr -> option	passed as `ariaDescribedBy` to `createNumber(options)`

Headless state to DOM reflection

Headless State	Direction	DOM Reflection
`state.isDisabled()`	state -> attr	`[disabled]` host attribute
`state.isReadOnly()`	state -> attr	`[read-only]` host attribute
`state.required()`	state -> attr	`[required]` host attribute
`state.focused()`	state -> attr	`[focused]` host attribute
`state.filled()`	state -> attr	`[filled]` host attribute
`state.showClearButton()`	state -> DOM	shows/hides the clear button element
`state.stepper()`	state -> DOM	shows/hides the stepper buttons
`state.draftText()`	state -> DOM	when non-null, displayed in the input; when null, displays formatted `String(value)`
`state.value()`	state -> DOM	displayed in the input when `draftText` is null
`state.placeholder()`	state -> DOM	applied as placeholder on the native input
`state.hasMin()` / `state.hasMax()`	state -> DOM	for conditional styling or rendering hints

Contract props spreading

contracts.getInputProps() is spread onto the [part="input"] native <input> element to apply id, role, tabindex, inputmode, aria-valuenow, aria-valuemin, aria-valuemax, aria-valuetext, aria-disabled, aria-readonly, aria-required, aria-label, aria-labelledby, aria-describedby, placeholder, and autocomplete.
contracts.getIncrementButtonProps() is spread onto the [part="increment"] button to apply id, tabindex, aria-label, aria-disabled, hidden, aria-hidden, and onClick.
contracts.getDecrementButtonProps() is spread onto the [part="decrement"] button to apply id, tabindex, aria-label, aria-disabled, hidden, aria-hidden, and onClick.
contracts.getClearButtonProps() is spread onto the [part="clear-button"] element to apply role, aria-label, tabindex, hidden, aria-hidden, and onClick.

Event wiring

Native <input> input event -> actions.handleInput(e.target.value) (updates draft text)
Native <input> keydown event -> actions.handleKeyDown(e) (handles ArrowUp/Down, PageUp/Down, Home/End, Enter, Escape)
Native <input> focus event -> actions.setFocused(true) -> dispatches cv-focus CustomEvent
Native <input> blur event -> actions.setFocused(false) (triggers draft commit) -> dispatches cv-blur CustomEvent; if value changed since focus, dispatches cv-change CustomEvent
Clear button click -> actions.clear() -> dispatches cv-clear CustomEvent
Increment/decrement button click -> unified user step path -> actions.increment() / actions.decrement() -> dispatches cv-change CustomEvent only when the committed value changes
Focused stepper + fine-pointer desktop wheel up/down -> normalized threshold accumulator -> unified user step path; modifiers, horizontal-dominant wheel movement, unfocused controls, disabled/read-only controls, and hidden steppers are ignored
stepper + horizontal touch swipe right/left -> thresholded scrub steps through the unified user step path; vertical-dominant touch movement cancels the gesture so page scroll remains available
Stepper button press-and-hold -> delayed repeated steps through the unified user step path, with accelerating repeat interval and click suppression after repeat starts
Successful touch-origin swipe and long-press steps may call navigator.vibrate(6) as best-effort feedback when available; vibration is throttled and disabled under prefers-reduced-motion: reduce

Input display logic (UIKit responsibility)

UIKit reads state.draftText() and state.value() to determine what to display in the native <input>:

When draftText !== null: display draftText (user is actively editing)
When draftText === null: display formatted String(value) (committed state)

UIKit does not own value management, clamping, snapping, draft commit logic, or ARIA computation; headless state is the source of truth.

Events

Event	Detail	Description
`cv-change`	`{ value: number }`	Fires on committed value change from user interaction (stepper click, focused wheel step, touch swipe step, long-press step, keyboard step, draft commit on blur/Enter). Does not fire from programmatic `setValue`.
`cv-clear`	`{ }`	Fires when the value is cleared via the clear button or `Escape` key
`cv-focus`	`{ }`	Fires when the input receives focus
`cv-blur`	`{ }`	Fires when the input loses focus

Imperative API

Method / Property	Description
`stepUp(times = 1)`	Increments by `step` `times` times
`stepDown(times = 1)`	Decrements by `step` `times` times
`pageUp(times = 1)`	Increments by `largeStep` `times` times
`pageDown(times = 1)`	Decrements by `largeStep` `times` times
`setValue(value)`	Sets numeric value through headless normalization
`getValue()`	Returns current committed numeric value
`setRange(min, max)`	Updates range boundaries; `null`/`undefined` removes a bound
`focus(options?)`	Focuses inner input control
`select()`	Selects text in inner input control
`checkValidity()`	Runs current validation checks
`reportValidity()`	Reports validation state to UA when supported
`setCustomValidity(message)`	Sets/clears custom validity message
`form`	Form owner when form-associated internals are supported
`validity`	Current validity state when supported
`validationMessage`	Current validation message
`willValidate`	Whether control participates in validation

Form Association

Component is form-associated via ElementInternals when available.
Submit value is serialized as the committed numeric value string.
disabled state removes form value from submission.
Reset restores the initial value snapshot captured on first connection.
Clear button and Escape reset to default-value (min ?? 0 when omitted), which is separate from form reset.
Browser form-state restoration accepts numeric string state and ignores non-numeric state.

cv-number ​

Usage ​

Anatomy ​

Attributes ​

Variants ​

Sizes ​

Slots ​

CSS Parts ​

CSS Custom Properties ​

Visual States ​

Reactive State Mapping ​

UIKit properties to headless actions ​

Headless state to DOM reflection ​

Contract props spreading ​

Event wiring ​

Input display logic (UIKit responsibility) ​

Events ​

Imperative API ​

Form Association ​