BetaFeito sobre o UI SDK 0.1.0-beta.2 da Vercel. A API pode mudar.

Number input

Um campo numérico no UI SDK da Vercel com botões que repetem ao segurar, formatos de moeda, porcentagem e unidade em qualquer idioma, e uma alça para arrastar.

Componentes de formulário
8 partes
13 exemplos
Atualizado em 14 de nov. de 2026

Depende de

@tabler/icons-react
@ui-sdk/core
@ui-sdk/react
class-variance-authority

Quantity

import { Label } from "@/components/ui/label"
import {
  NumberInput,
  NumberInputControl,
  NumberInputDecrement,
  NumberInputGroup,
  NumberInputIncrement,
  NumberInputScrubArea,
  NumberInputScrubAreaCursor,
} from "@/components/ui/ui-sdk-number-input"

function UiSdkNumberInputDemo() {
  return (
    <NumberInput defaultValue={1} min={1} max={99} className="max-w-36">
      <NumberInputScrubArea pixelsPerStep={6}>
        <Label htmlFor="demo-quantity">Quantity</Label>
        <NumberInputScrubAreaCursor />
      </NumberInputScrubArea>
      <NumberInputGroup>
        <NumberInputDecrement />
        <NumberInputControl id="demo-quantity" />
        <NumberInputIncrement />
      </NumberInputGroup>
    </NumberInput>
  )
}

export { UiSdkNumberInputDemo }

Instalação

pnpm dlx shadcn@latest add https://hextaui.com/r/ui-sdk-number-input.json

Adiciona o componente, os tokens de tema do HextaUI e quaisquer componentes do HextaUI dos quais ele depende.

Adicione os tokens de tema ao seu CSS global, se ainda não o fez.

Instale as dependências.

pnpm add @ui-sdk/react@0.1.0-beta.2 @ui-sdk/core@0.1.0-beta.2 @tabler/icons-react class-variance-authority cn

3
Copie e cole o código a seguir no seu projeto.
components/ui/ui-sdk-number-input.tsx
"use client" import * as React from "react" import { IconChevronDown, IconChevronUp, IconMinus, IconPlus,
Atualize os caminhos de importação para corresponder à configuração do seu projeto.

O UI SDK adiciona um pouco de CSS próprio em uma camada de cascata chamada ui-sdk. Declare essa camada no topo da sua folha de estilos global, acima do import do Tailwind, para que suas classes vençam.

@layer ui-sdk;

@import "tailwindcss";

import {
  NumberInput,
  NumberInputControl,
  NumberInputDecrement,
  NumberInputGroup,
  NumberInputIncrement,
} from "@/components/ui/ui-sdk-number-input"

<NumberInput defaultValue={1} min={0}>
  <NumberInputGroup>
    <NumberInputDecrement />
    <NumberInputControl aria-label="Quantity" />
    <NumberInputIncrement />
  </NumberInputGroup>
</NumberInput>

O valor é um número, ou null quando o campo está vazio, e o campo o mostra formatado. Digitar atualiza o valor assim que o texto é um número válido. Enter ou sair do campo o confirma: o texto é lido, mantido entre min e max, ajustado ao passo e formatado de novo.

Composição

NumberInput
├── NumberInputScrubArea
│   └── NumberInputScrubAreaCursor
└── NumberInputGroup
    ├── NumberInputDecrement
    ├── NumberInputControl
    ├── NumberInputIncrement
    └── NumberInputStepper
        ├── NumberInputIncrement
        └── NumberInputDecrement

Exemplos

Mínimo e máximo

Abrir exemplo

Um botão se desativa no seu limite. Um valor digitado fora dos limites é trazido de volta ao confirmar.

import { Label } from "@/components/ui/label"
import {
  NumberInput,
  NumberInputControl,
  NumberInputDecrement,
  NumberInputGroup,
  NumberInputIncrement,
} from "@/components/ui/ui-sdk-number-input"

function UiSdkNumberInputMinMax() {
  return (
    <div className="flex w-full max-w-40 flex-col gap-2">
      <Label htmlFor="guests">Guests</Label>
      <NumberInput defaultValue={2} min={1} max={8}>
        <NumberInputGroup>
          <NumberInputDecrement />
          <NumberInputControl id="guests" />
          <NumberInputIncrement />
        </NumberInputGroup>
      </NumberInput>
      <p className="m-0 text-xs text-muted-foreground">
        Tables seat 1 to 8 guests.
      </p>
    </div>
  )
}

export { UiSdkNumberInputMinMax }

Etapa

Abrir exemplo

step é o incremento comum. Shift, Page Up e Page Down mudam em largeStep, e Alt ou Option com uma seta em smallStep. Segure um botão para repetir.

import { Label } from "@/components/ui/label"
import {
  NumberInput,
  NumberInputControl,
  NumberInputDecrement,
  NumberInputGroup,
  NumberInputIncrement,
} from "@/components/ui/ui-sdk-number-input"

function UiSdkNumberInputStep() {
  return (
    <div className="grid w-full max-w-sm grid-cols-2 gap-4">
      <div className="flex flex-col gap-2">
        <Label htmlFor="temperature">Temperature</Label>
        <NumberInput
          defaultValue={0.7}
          min={0}
          max={2}
          step={0.1}
          largeStep={0.5}
          smallStep={0.01}
        >
          <NumberInputGroup>
            <NumberInputDecrement />
            <NumberInputControl id="temperature" />
            <NumberInputIncrement />
          </NumberInputGroup>
        </NumberInput>
      </div>
      <div className="flex flex-col gap-2">
        <Label htmlFor="max-tokens">Max tokens</Label>
        <NumberInput
          defaultValue={4096}
          min={256}
          max={32768}
          step={256}
          largeStep={4096}
        >
          <NumberInputGroup>
            <NumberInputDecrement />
            <NumberInputControl id="max-tokens" />
            <NumberInputIncrement />
          </NumberInputGroup>
        </NumberInput>
      </div>
    </div>
  )
}

export { UiSdkNumberInputStep }

Moeda, porcentagem e unidades

Abrir exemplo

format recebe opções de Intl.NumberFormat. Dá para digitar no mesmo formato, e uma porcentagem é uma fração, então 15% é 0.15. O grupo variant="stacked" coloca setas pequenas no fim.

import { Label } from "@/components/ui/label"
import {
  NumberInput,
  NumberInputControl,
  NumberInputDecrement,
  NumberInputGroup,
  NumberInputIncrement,
  NumberInputStepper,
} from "@/components/ui/ui-sdk-number-input"

const fields = [
  {
    id: "price",
    label: "Price",
    defaultValue: 19.99,
    step: 0.01,
    format: { style: "currency", currency: "USD" },
  },
  {
    id: "discount",
    label: "Discount",
    defaultValue: 0.15,
    step: 0.01,
    format: { style: "percent" },
  },
  {
    id: "weight",
    label: "Weight",
    defaultValue: 2.5,
    step: 0.1,
    format: { style: "unit", unit: "kilogram" },
  },
] satisfies {
  id: string
  label: string
  defaultValue: number
  step: number
  format: Intl.NumberFormatOptions
}[]

function UiSdkNumberInputFormat() {
  return (
    <div className="flex w-full max-w-44 flex-col gap-4">
      {fields.map(({ id, label, ...options }) => (
        <div key={id} className="flex flex-col gap-2">
          <Label htmlFor={id}>{label}</Label>
          <NumberInput {...options} min={0} locale="en-US">
            <NumberInputGroup variant="stacked">
              <NumberInputControl id={id} />
              <NumberInputStepper>
                <NumberInputIncrement />
                <NumberInputDecrement />
              </NumberInputStepper>
            </NumberInputGroup>
          </NumberInput>
        </div>
      ))}
    </div>
  )
}

export { UiSdkNumberInputFormat }

Idioma

Abrir exemplo

locale escolhe separadores, símbolos e agrupamento de dígitos, para exibir e para digitar. Sem ele, o campo segue o idioma da página quando fica interativo, e o servidor renderiza em inglês.

import { Label } from "@/components/ui/label"
import {
  NumberInput,
  NumberInputControl,
  NumberInputDecrement,
  NumberInputGroup,
  NumberInputIncrement,
} from "@/components/ui/ui-sdk-number-input"

const fields = [
  {
    id: "preis",
    label: "Preis",
    locale: "de-DE",
    defaultValue: 1234.5,
    step: 0.01,
    format: { style: "currency", currency: "EUR" },
  },
  {
    id: "budget",
    label: "Budget",
    locale: "en-IN",
    defaultValue: 1234567,
    step: 1000,
    format: { style: "currency", currency: "INR", maximumFractionDigits: 0 },
  },
  {
    id: "kakaku",
    label: "価格",
    locale: "ja-JP",
    defaultValue: 2980,
    step: 10,
    format: { style: "currency", currency: "JPY" },
  },
] satisfies {
  id: string
  label: string
  locale: string
  defaultValue: number
  step: number
  format: Intl.NumberFormatOptions
}[]

function UiSdkNumberInputLocale() {
  return (
    <div className="flex w-full max-w-52 flex-col gap-4">
      {fields.map(({ id, label, ...options }) => (
        <div key={id} className="flex flex-col gap-2">
          <Label htmlFor={id}>{label}</Label>
          <NumberInput {...options} min={0}>
            <NumberInputGroup>
              <NumberInputDecrement />
              <NumberInputControl id={id} />
              <NumberInputIncrement />
            </NumberInputGroup>
          </NumberInput>
        </div>
      ))}
    </div>
  )
}

export { UiSdkNumberInputLocale }

Arrastar

Abrir exemplo

Arraste um NumberInputScrubArea para os lados para mudar o valor, como numa ferramenta de design. Onde o navegador permite travar o ponteiro, o arraste pode passar da borda da tela, e NumberInputScrubAreaCursor desenha o cursor.

import {
  NumberInput,
  NumberInputControl,
  NumberInputGroup,
  NumberInputScrubArea,
  NumberInputScrubAreaCursor,
} from "@/components/ui/ui-sdk-number-input"

const fields = [
  { label: "X position", handle: "X", defaultValue: 120 },
  { label: "Y position", handle: "Y", defaultValue: 48 },
  { label: "Width", handle: "W", defaultValue: 320, min: 0 },
  { label: "Height", handle: "H", defaultValue: 240, min: 0 },
]

function UiSdkNumberInputScrub() {
  return (
    <div
      role="group"
      aria-labelledby="scrub-frame"
      className="flex w-full max-w-64 flex-col gap-2"
    >
      <p id="scrub-frame" className="m-0 text-xs font-medium">
        Frame
      </p>
      <div className="grid grid-cols-2 gap-2">
        {fields.map(({ label, handle, ...options }) => (
          <NumberInput key={label} {...options}>
            <NumberInputGroup variant="plain">
              <NumberInputScrubArea pixelsPerStep={1}>
                <span aria-hidden="true">{handle}</span>
                <NumberInputScrubAreaCursor />
              </NumberInputScrubArea>
              <NumberInputControl aria-label={label} />
            </NumberInputGroup>
          </NumberInput>
        ))}
      </div>
    </div>
  )
}

export { UiSdkNumberInputScrub }

Roda do mouse

Abrir exemplo

Com wheel, rolar sobre o campo focado muda o valor. Fica desligado por padrão, então uma página que rola por cima do campo nunca o altera.

import { Label } from "@/components/ui/label"
import {
  NumberInput,
  NumberInputControl,
  NumberInputDecrement,
  NumberInputGroup,
  NumberInputIncrement,
} from "@/components/ui/ui-sdk-number-input"

function UiSdkNumberInputWheel() {
  return (
    <div className="flex w-full max-w-40 flex-col gap-2">
      <Label htmlFor="hover-delay">Hover delay</Label>
      <NumberInput
        defaultValue={300}
        min={0}
        max={2000}
        step={50}
        wheel
        format={{ style: "unit", unit: "millisecond" }}
        locale="en-US"
      >
        <NumberInputGroup>
          <NumberInputDecrement />
          <NumberInputControl id="hover-delay" />
          <NumberInputIncrement />
        </NumberInputGroup>
      </NumberInput>
      <p className="m-0 text-xs text-muted-foreground">
        Focus it, then scroll over it.
      </p>
    </div>
  )
}

export { UiSdkNumberInputWheel }

Controlado

Abrir exemplo

onValueChange roda a cada mudança válida, e onValueCommit quando uma interação termina, que é onde salvar. Um controlador muda ou define o valor a partir de qualquer botão.

"use client"

import * as React from "react"

import { Button } from "@/components/ui/button"
import { Label } from "@/components/ui/label"
import {
  NumberInput,
  NumberInputControl,
  NumberInputDecrement,
  NumberInputGroup,
  NumberInputIncrement,
  createNumberInputController,
} from "@/components/ui/ui-sdk-number-input"

function UiSdkNumberInputControlled() {
  const [seats, setSeats] = React.useState<number | null>(5)
  const [saved, setSaved] = React.useState<number | null>(5)
  const [controller] = React.useState(createNumberInputController)

  return (
    <div className="flex w-full max-w-56 flex-col gap-2">
      <Label htmlFor="seats">Seats</Label>
      <NumberInput
        controller={controller}
        value={seats}
        min={1}
        max={50}
        onValueChange={(value) => setSeats(value)}
        onValueCommit={(value) => setSaved(value)}
      >
        <NumberInputGroup>
          <NumberInputDecrement />
          <NumberInputControl id="seats" />
          <NumberInputIncrement />
        </NumberInputGroup>
      </NumberInput>
      <div className="flex items-center gap-2 pt-1">
        <Button
          size="sm"
          variant="outline"
          onClick={() => controller.increment({ large: true })}
        >
          Add 10
        </Button>
        <Button
          size="sm"
          variant="ghost"
          onClick={() => controller.setValue(1)}
        >
          Reset to 1
        </Button>
      </div>
      <p className="m-0 text-xs text-muted-foreground tabular-nums">
        {`Showing ${seats ?? "nothing"}, saved ${saved ?? "nothing"}.`}
      </p>
    </div>
  )
}

export { UiSdkNumberInputControlled }

Form

Abrir exemplo

Com um name, o número é enviado como está, como 1250, nunca formatado. required bloqueia um campo vazio, e redefinir o formulário volta ao padrão.

"use client"

import * as React from "react"

import { Button } from "@/components/ui/button"
import { Label } from "@/components/ui/label"
import {
  NumberInput,
  NumberInputControl,
  NumberInputDecrement,
  NumberInputGroup,
  NumberInputIncrement,
} from "@/components/ui/ui-sdk-number-input"

function UiSdkNumberInputForm() {
  const [submitted, setSubmitted] = React.useState<string | null>(null)

  return (
    <form
      className="flex w-full max-w-48 flex-col gap-2"
      onSubmit={(event) => {
        event.preventDefault()
        setSubmitted(String(new FormData(event.currentTarget).get("amount")))
      }}
      onReset={() => setSubmitted(null)}
    >
      <Label htmlFor="amount">Amount</Label>
      <NumberInput
        name="amount"
        required
        min={1}
        step={0.01}
        defaultValue={1250}
        locale="en-US"
        format={{ style: "currency", currency: "USD" }}
      >
        <NumberInputGroup>
          <NumberInputDecrement />
          <NumberInputControl id="amount" />
          <NumberInputIncrement />
        </NumberInputGroup>
      </NumberInput>
      <div className="flex items-center gap-3 pt-1">
        <Button type="submit" size="sm">
          Submit
        </Button>
        <Button type="reset" size="sm" variant="ghost">
          Reset
        </Button>
      </div>
      <p className="m-0 text-xs text-muted-foreground tabular-nums">
        {submitted === null
          ? "Nothing submitted yet."
          : `Submitted amount=${submitted}`}
      </p>
    </form>
  )
}

export { UiSdkNumberInputForm }

Inválido

Abrir exemplo

invalid marca o campo e define aria-invalid no input, para verificações próprias como estoque.

"use client"

import * as React from "react"

import { Label } from "@/components/ui/label"
import {
  NumberInput,
  NumberInputControl,
  NumberInputDecrement,
  NumberInputGroup,
  NumberInputIncrement,
} from "@/components/ui/ui-sdk-number-input"

const stock = 12

function UiSdkNumberInputInvalid() {
  const [quantity, setQuantity] = React.useState<number | null>(14)
  const invalid = quantity !== null && quantity > stock

  return (
    <div className="flex w-full max-w-40 flex-col gap-2">
      <Label htmlFor="order-quantity">Quantity</Label>
      <NumberInput
        defaultValue={14}
        min={1}
        invalid={invalid}
        onValueChange={(value) => setQuantity(value)}
      >
        <NumberInputGroup>
          <NumberInputDecrement />
          <NumberInputControl
            id="order-quantity"
            aria-describedby="order-quantity-message"
          />
          <NumberInputIncrement />
        </NumberInputGroup>
      </NumberInput>
      <p
        id="order-quantity-message"
        className={
          invalid
            ? "m-0 text-xs text-destructive"
            : "m-0 text-xs text-muted-foreground"
        }
      >
        {invalid ? `Only ${stock} left in stock.` : `${stock} in stock.`}
      </p>
    </div>
  )
}

export { UiSdkNumberInputInvalid }

Desabilitado

Abrir exemplo

Um campo desativado não pode ser focado nem alterado, e não é enviado.

import { Label } from "@/components/ui/label"
import {
  NumberInput,
  NumberInputControl,
  NumberInputDecrement,
  NumberInputGroup,
  NumberInputIncrement,
} from "@/components/ui/ui-sdk-number-input"

function UiSdkNumberInputDisabled() {
  return (
    <div className="flex w-full max-w-40 flex-col gap-2">
      <Label htmlFor="sold-out">Quantity</Label>
      <NumberInput defaultValue={3} disabled>
        <NumberInputGroup>
          <NumberInputDecrement />
          <NumberInputControl id="sold-out" />
          <NumberInputIncrement />
        </NumberInputGroup>
      </NumberInput>
      <p className="m-0 text-xs text-muted-foreground">Sold out.</p>
    </div>
  )
}

export { UiSdkNumberInputDisabled }

Somente leitura

Abrir exemplo

Um campo somente leitura pode ser focado e é enviado, mas botões, arraste e digitação não o alteram.

import { Label } from "@/components/ui/label"
import {
  NumberInput,
  NumberInputControl,
  NumberInputDecrement,
  NumberInputGroup,
  NumberInputIncrement,
} from "@/components/ui/ui-sdk-number-input"

function UiSdkNumberInputReadOnly() {
  return (
    <div className="flex w-full max-w-40 flex-col gap-2">
      <Label htmlFor="included-seats">Seats included</Label>
      <NumberInput defaultValue={5} readOnly>
        <NumberInputGroup>
          <NumberInputDecrement />
          <NumberInputControl id="included-seats" />
          <NumberInputIncrement />
        </NumberInputGroup>
      </NumberInput>
      <p className="m-0 text-xs text-muted-foreground">Set by your plan.</p>
    </div>
  )
}

export { UiSdkNumberInputReadOnly }

Da direita para a esquerda

Abrir exemplo

Os botões trocam de lado, e o idioma define os dígitos e a moeda.

import { Label } from "@/components/ui/label"
import {
  NumberInput,
  NumberInputControl,
  NumberInputDecrement,
  NumberInputGroup,
  NumberInputIncrement,
} from "@/components/ui/ui-sdk-number-input"

function UiSdkNumberInputRtl() {
  return (
    <div dir="rtl" className="flex w-full max-w-44 flex-col gap-2">
      <Label htmlFor="rtl-amount">المبلغ</Label>
      <NumberInput
        defaultValue={250}
        min={0}
        step={5}
        locale="ar-EG"
        format={{ style: "currency", currency: "EGP" }}
      >
        <NumberInputGroup>
          <NumberInputDecrement aria-label="إنقاص" />
          <NumberInputControl id="rtl-amount" />
          <NumberInputIncrement aria-label="زيادة" />
        </NumberInputGroup>
      </NumberInput>
    </div>
  )
}

export { UiSdkNumberInputRtl }

Teclado

Tecla	Ação
`↑↓`	Muda o valor em step.
`ShiftPageUpPageDown`	Muda em largeStep, dez passos por padrão. Shift funciona com as setas, os botões, a roda e o arraste.
`Alt`	Com uma seta, muda em smallStep, um décimo de passo por padrão.
`HomeEnd`	Vai ao mínimo ou ao máximo, quando definidos.
`Enter`	Confirma e formata o que foi digitado.

Acessibilidade

O campo segue o teclado do padrão spinbutton da WAI-ARIA em um input de texto nativo, então a edição de texto comum continua funcionando. Nomeie o input com um rótulo ou aria-label. Os botões se chamam “Increase” e “Decrease” por padrão, apontam para o input e ficam fora da ordem de tabulação porque as setas fazem o mesmo.

Um campo com decimais pede um teclado decimal nos celulares, e os botões crescem em telas de toque. Eles só encolhem ao toque quando o movimento é permitido.

Referência da API

Cada parte envolve a parte do UI SDK de mesmo nome e aceita todas as suas props, incluindo render e um className que pode ser uma função do estado da parte.

NumberInput

Prop	Tipo	Padrão
`value`	`number \| null`	`–`
`defaultValue`	`number \| null`	`–`
`onValueChange`	`(value: number \| null, details) => void`	`–`
`onValueCommit`Executa quando uma interação termina. Para salvar.	`(value: number \| null, details) => void`	`–`
`min`	`number`	`–`
`max`	`number`	`–`
`step`	`number`	`1`
`largeStep`	`number`	`step × 10`
`smallStep`	`number`	`step ÷ 10`
`format`	`Intl.NumberFormatOptions`	`–`
`locale`Por padrão, o idioma da página.	`string`	`–`
`wheel`	`boolean`	`false`
`invalid`	`boolean`	`false`
`disabled`	`boolean`	`false`
`readOnly`	`boolean`	`false`
`required`	`boolean`	`false`
`name`	`string`	`–`
`form`	`string`	`–`
`controller`De createNumberInputController().	`NumberInputController`	`–`

Atributo	Descrição
`data-slot="number-input"`	Para mirar o campo numérico no CSS.
`data-scrubbing`	Presente enquanto um arraste muda o valor.
`data-invalid`	Presente quando inválido.
`data-disabled`	Presente quando desabilitado.
`data-readonly`	Presente quando somente leitura.
`data-required`	Presente quando obrigatório.

NumberInputGroup

Prop	Tipo	Padrão
`variant`Botões dos dois lados, setas empilhadas no fim ou nenhum botão, para uma alça de arraste.	`"split" \| "stacked" \| "plain"`	`"split"`
`render`	`ReactElement \| (props, state) => ReactElement`	`–`

Atributo	Descrição
`data-slot="number-input-group"`	Para mirar a caixa do campo no CSS.
`data-variant`	A variante: split, stacked ou plain.

NumberInputControl

Prop	Tipo	Padrão
`id`	`string`	`–`
`placeholder`	`string`	`–`
`render`	`ReactElement \| (props, state) => ReactElement`	`–`

NumberInputIncrement

Prop	Tipo	Padrão
`aria-label`	`string`	`"Increase"`
`disabled`Desativa só este botão.	`boolean`	`–`
`children`Por padrão, um sinal de mais, ou uma seta na variante stacked.	`ReactNode \| (state) => ReactNode`	`–`
`render`	`ReactElement \| (props, state) => ReactElement`	`–`

Atributo	Descrição
`data-slot="number-input-increment"`	Seleciona o botão no CSS.
`data-at-bound`	Presente quando o valor está em max.
`data-disabled`	Presente quando o botão não pode mudar o valor.

NumberInputDecrement

Prop	Tipo	Padrão
`aria-label`	`string`	`"Decrease"`
`disabled`Desativa só este botão.	`boolean`	`–`
`render`	`ReactElement \| (props, state) => ReactElement`	`–`

Atributo	Descrição
`data-slot="number-input-decrement"`	Seleciona o botão no CSS.
`data-at-bound`	Presente quando o valor está em min.

NumberInputStepper

Empilha o botão de aumentar sobre o de diminuir no fim de um grupo stacked.

NumberInputScrubArea

Prop	Tipo	Padrão
`orientation`Direita e para cima aumentam o valor.	`"horizontal" \| "vertical"`	`"horizontal"`
`pixelsPerStep`Quanto o ponteiro se move para um passo.	`number`	`–`
`controller`Conecta uma área de arraste fora do campo numérico, como um ícone numa barra de ferramentas.	`NumberInputController`	`–`

Atributo	Descrição
`data-slot="number-input-scrub-area"`	Para mirar a área de arraste no CSS.
`data-orientation`	horizontal ou vertical.
`data-scrubbing`	Presente enquanto um arraste muda o valor.

NumberInputScrubAreaCursor

Prop	Tipo	Padrão
`children`Por padrão, uma seta horizontal centrada no ponteiro.	`ReactNode`	`–`