NumberField

Numeric input with increment/decrement controls and FormField chrome.

Introduction

Use NumberField when you need increment/decrement steppers, numeric onChange callbacks, and enforced min, max, and step behavior.

Use TextField with type="number" only for a plain numeric input without stepper UI—browser spinners and validation behavior vary by platform, and onChange returns a string rather than a number.

Import

import { NumberField } from "@bridge-ui/vue/Components/NumberField";

import { NumberField } from "@bridge-ui/react/Components/NumberField";

Basic usage

Use the stepper buttons or type a value directly. In React, bind with value and onChange (which receives the numeric value). In Vue, use v-model. For uncontrolled usage with an initial value, use defaultValue in React or default-value in Vue.

<script setup lang="ts">
import { ref } from "vue";

import { NumberField } from "@bridge-ui/vue/Components/NumberField";

const quantity = ref(1);
</script>

<template>
  <div class="flex w-full max-w-sm flex-col gap-4">
    <NumberField
      :min="0"
      :max="20"
      :step="1"
      placeholder="0"
      label="Quantity"
    />

    <NumberField
      label="Units"
      v-model="quantity"
      description="Use the stepper or type a value."
    />
  </div>
</template>

import { useState } from "react";

import { NumberField } from "@bridge-ui/react/Components/NumberField";

export default function NumberFieldBasic() {
  const [quantity, setQuantity] = useState(1);

  return (
    <div className="flex w-full max-w-sm flex-col gap-4">
      <NumberField min={0} max={20} step={1} placeholder="0" label="Quantity" />

      <NumberField
        label="Units"
        value={quantity}
        onChange={setQuantity}
        description="Use the stepper or type a value."
      />
    </div>
  );
}

Min, max, and step

Constrain the allowed range with min and max, and set the increment with step (default 1).

<script setup lang="ts">
import { NumberField } from "@bridge-ui/vue/Components/NumberField";
</script>

<template>
  <div class="flex w-full max-w-sm flex-col gap-4">
    <NumberField :min="1" :max="99" :step="5" label="Items" placeholder="0" />
  </div>
</template>

import { NumberField } from "@bridge-ui/react/Components/NumberField";

export default function NumberFieldMinMaxStep() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-4">
      <NumberField min={1} max={99} step={5} label="Items" placeholder="0" />
    </div>
  );
}

Validation

Set error and errorMessage to show invalid styling and an error message below the field.

<script setup lang="ts">
import { NumberField } from "@bridge-ui/vue/Components/NumberField";
</script>

<template>
  <div class="flex w-full max-w-sm flex-col gap-4">
    <NumberField
      error
      label="Amount"
      placeholder="0"
      error-message="Value must be between 0 and 100."
    />
  </div>
</template>

import { NumberField } from "@bridge-ui/react/Components/NumberField";

export default function NumberFieldValidation() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-4">
      <NumberField
        error
        label="Amount"
        placeholder="0"
        errorMessage="Value must be between 0 and 100."
      />
    </div>
  );
}

TextField, Slider

Accessibility

NumberField follows the FormField accessibility pattern. Stepper buttons include accessible labels for increment and decrement actions.

Label, helper text, and error message are linked via controlId and aria-describedby.
When error is true, the input receives aria-invalid="true".

Anatomy

NumberField composes FormField around a numeric input and stepper controls:

FormField (root)
├── Header — label, optional corner text, required indicator
├── Container — variant shell
│   ├── Decrement button
│   ├── Input — numeric text input
│   └── Increment button
└── Footer — description or error message

API

Prop	Type	Default	Description
v-model	number	—	Two-way binding for the numeric value.
default-value	number	—	Initial value for uncontrolled usage (without v-model).

Prop	Type	Default	Description
value	number	—	Numeric value. Use with onChange for controlled state.
defaultValue	number	—	Initial value for uncontrolled usage.
onChange	(value: number) => void	—	Called with the parsed numeric value.

NumberField-specific

Prop	Type	Default	Description
min	number	—	Minimum value.
max	number	—	Maximum value.
step	number	1	Step increment value.
classes	NumberFieldClasses	—	Classes for the number field.

Inherited from FormField

Prop	Type	Default	Description
label	string	—	Primary label text above the control.
description	string	—	Helper text below the control (hidden when invalid).
corner	string	—	Secondary label text at the inline end of the header row.
required	boolean	false	Shows a red asterisk on the label.
disabled	boolean	false	Whether the control is disabled.
readonly	boolean	false	Whether the control is read-only.
error	boolean	false	Applies invalid styling and hides description.
errorMessage	string	—	Error message below the control.
showErrorIcon	boolean	true	Shows an error icon when invalid.
hideErrorMessage	boolean	false	Does not reserve space for error messages.
variant	FormFieldVariant	"outline"	Visual variant of the field shell.
color	FormFieldColor	"primary"	Color applied to the field control.
size	FormFieldSize	"md"	Typography and control sizing.
rounded	FormFieldRounded	"md"	Border radius of the field control.
start	string	—	Inline-start text inside the field (prefix).
end	string	—	Inline-end text inside the field (suffix).
startIcon	IconSource	—	Icon at the inline start.
endIcon	IconSource	—	Icon at the inline end.
errorIcon	IconSource	"alert"	Icon shown when invalid and showErrorIcon is enabled.
controlId	string	—	Associates labels and helper text with the control. Auto-generated when omitted.
classes	FormFieldClasses	—	Class overrides per part.
customProps	FormFieldCustomProps	—	Props for each part. label accepts Label props (without children); error label colors come from Label.
slots	FormFieldSlots	—	React slots. Vue: #label, #corner, default, #description, #errorMessage, #start, #end.