Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Forms

NumberInput

A native number field with step buttons and optional units.

Last changed in version 0.14.2: Improve keyboard navigation, action feedback, and selected colors across Vue components.

Interactive showcase

Install

Run in your project
bunx --bun @getweini/cli@latest add number-input

Start with this example

Import the files copied by the install command, then place the component in your Vue template. The text and values in the example belong to your app; change them to fit your task.

kg
Vue
<script setup lang="ts">
import { ref } from 'vue'
import NumberInput from './components/ui/number-input/NumberInput.vue'

const weight = ref<number | undefined>(2.5)
const messages = { decrement: 'Decrease', increment: 'Increase' }
</script>

<template>
  <NumberInput v-model="weight" :min="0" :step="0.25" :messages="messages" wheel>
    <template #suffix>kg</template>
  </NumberInput>
</template>

Arrow keys and buttons step the value. The corresponding −/+ glyph briefly pulses on each successful step, including repeated clicks and exposed increment/decrement calls. Reduced motion keeps the directional highlight without animation. Opt in with wheel to let a focused input step on vertical scrolling; unfocused fields keep page scrolling.

When to use it

Bounded quantities

Let shoppers type a quantity or use step buttons within inventory limits.

Measurements

Display a unit beside a fractional numeric value without storing the unit in the model.

More examples

Ticket count

A whole-number quantity with explicit bounds.

Ticket count
<script setup lang="ts">
import { ref } from 'vue'
import NumberInput from './components/ui/number-input/NumberInput.vue'

const tickets = ref<number | undefined>(1)
const messages = { decrement: 'Fewer tickets', increment: 'More tickets' }
</script>
<template>
  <label for="tickets">Tickets</label>
  <NumberInput
    id="tickets"
    v-model="tickets"
    name="tickets"
    :min="1"
    :max="8"
    :step="1"
    :messages="messages"
  />
</template>

Weight in kilograms

An explicit minimum anchors the quarter-step grid.

Weight in kilograms
<script setup lang="ts">
import { ref } from 'vue'
import NumberInput from './components/ui/number-input/NumberInput.vue'

const weight = ref<number | undefined>(0.5)
const messages = { decrement: 'Decrease weight', increment: 'Increase weight' }
</script>
<template>
  <label for="weight">Weight in kilograms</label>
  <NumberInput id="weight" v-model="weight" :min="0" :max="20" :step="0.25" :messages="messages">
    <template #suffix>kg</template>
  </NumberInput>
</template>

Complete API

Every public prop, model, event, slot, and exposed member of the installed Vue parts is listed below. “Not set” means you can leave that value out; “Required” means you must provide it. Native HTML attributes also work where the component uses a native element.

NumberInput

Complete API for NumberInput
NameType or signatureDefaultWhat it does
rootClasspropClassValueNot setClasses applied to the outer component wrapper.
rootStylepropStyleValueNot setStyles applied to the outer component wrapper.
sizepropControlSize | undefined"md"Choose the visual size. Medium is the usual default where available.
invalidpropboolean | undefinedNot setShow the invalid state; also provide a visible error message.
disabledpropboolean | undefinedNot setPrevent interaction and show the disabled state.
readonlypropboolean | undefinedNot setShow the value while preventing edits.
minpropnumber | undefinedNot setSmallest allowed value.
maxpropnumber | undefinedNot setLargest allowed value.
steppropnumber | undefined1Amount added or removed for each adjustment.
wheelpropboolean | undefinedfalseWith wheel enabled, vertical wheel events change a step only while the input has keyboard focus.
messagespropNumberInputMessagesRequiredSupply the text this component displays for its built-in actions and states.
modelValuemodelnumber | undefinedNot setCurrent value. Use v-model to keep it in sync with your page.
update:modelValueevent[value: number | undefined]—Requests a new model value from the parent.
prefixslot(() => unknown) | undefinedOptionalContent shown before the main label or value.
suffixslot(() => unknown) | undefinedOptionalContent shown after the main label or value.
errorslot((props: { message: string; messages: string[]; }) => unknown) | undefinedOptionalContent for the error area of NumberInput.
elementexposedHTMLInputElement | null—Reference to the underlying HTML element.
focusexposed() => void | undefined—Move keyboard focus to this control.
incrementexposed() => boolean—Access increment from a component template ref.
decrementexposed() => boolean—Access decrement from a component template ref.
Public type definitions
Public types
// packages/frameworks/vue/components/number-input/types.ts
// ------- IMPORTS -------

import type { ControlSize } from '@getweini/vue/types'
import type { HTMLAttributes } from 'vue'

// ------- TYPES -------

export interface NumberInputMessages {
  increment: string
  decrement: string
}

export interface NumberInputProps {
  rootClass?: HTMLAttributes['class']
  rootStyle?: HTMLAttributes['style']
  size?: ControlSize
  invalid?: boolean
  disabled?: boolean
  readonly?: boolean
  min?: number
  max?: number
  step?: number
  wheel?: boolean
  messages: NumberInputMessages
}


// packages/frameworks/vue/dist/types/index.d.ts
export type { ButtonOptions, ButtonProps } from './button';
export type ControlSize = 'sm' | 'md' | 'lg';
export interface SelectOption<T = unknown> {
    label: string;
    value: T;
    disabled?: boolean;
}
/** Application-owned copy. Bind translated strings reactively when the locale changes. */
export interface ListboxMessages {
    /** Popup name when no aria-label or aria-labelledby is supplied. */
    listboxLabel: string;
    empty: string;
    clearSelection: string;
}
export interface ListboxProps<T> {
    options: readonly SelectOption<T>[];
    messages: ListboxMessages;
    id?: string;
    disabled?: boolean;
    required?: boolean;
    invalid?: boolean;
    name?: string;
    form?: string;
    placeholder?: string;
    size?: ControlSize;
    clearable?: boolean;
    gap?: number;
    /** Supply stable equality for object values. Values must be unique. */
    by?: (a: T, b: T) => boolean;
    /** Required for meaningful form submission of object values. */
    serialize?: (value: T) => string;
}


// packages/frameworks/vue/dist/types/button.d.ts
import type { Component } from 'vue';
/** Options shared by button implementations across frameworks. */
export interface ButtonOptions<Variant extends string = string, Size extends string = string> {
    variant?: Variant;
    size?: Size;
    disabled?: boolean;
    loading?: boolean;
    type?: 'button' | 'submit' | 'reset';
}
/** Vue-specific target options extend the reusable button contract. */
export interface ButtonProps<Variant extends string = 'default' | 'secondary' | 'outline' | 'ghost' | 'destructive', Size extends string = 'sm' | 'md' | 'lg'> extends ButtonOptions<Variant, Size> {
    as?: 'button' | 'a' | Component;
    asChild?: boolean;
}

Implementation notes

  • rootClass and rootStyle style the visible wrapper; native attributes belong to the input.
  • Clearing the field emits undefined; handle that state before calculating totals.
  • Typed invalid values remain editable. Check native validity on submit rather than assuming the step buttons enforce typed input.

Accessibility and localization

  • Pass localized increment and decrement labels through messages. Mention units in the label or description, not only in the suffix.

Source contract and editing guidance