Number field
BetaUn número con botones para sumar y restar, para cantidades acotadas.
registry/ds/number-field.tsxEntre 1 y 12.
import { NumberField } from "@/registry/ds/number-field";
export default function NumberFieldBasic() {
return (
<div className="flex w-full max-w-md flex-col gap-5">
<NumberField label="Cantidad de cuotas" defaultValue={6} min={1} max={12} hint="Entre 1 y 12." className="max-w-48" />
<NumberField label="Monto a pagar" defaultValue={99000} min={0} step={1000} largeStep={10000} format={{ style: "currency", currency: "ARS", maximumFractionDigits: 0 }} className="max-w-64" />
<NumberField size="sm" label="Asientos" defaultValue={2} min={0} max={8} disabled className="max-w-40" />
</div>
);
}Cuándo usarlo
| Usá Number field para… | Usá otra cosa para… |
|---|---|
| Cantidades chicas y acotadas: cuotas, asientos, unidades. | Números largos o identificadores (DNI, teléfono) → Input con inputMode="numeric". |
| Valores con paso fijo (de a 1.000). | Un valor dentro de una escala, sin precisión → Slider. |
| Montos con formato (moneda, decimales). | Fechas → Date picker. |
Formatos
El valor siempre es un número; format recibe las opciones de
Intl.NumberFormat y decide cómo se escribe: porcentaje, unidades, moneda o
decimales fijos.
El valor interno es 0,5.
Shift + flecha salta de a 10.
De 1 a 10, con medios puntos.
import { NumberField } from "@/registry/ds/number-field";
/** El valor es un número; cómo se escribe lo decide `format` (Intl.NumberFormat): moneda, porcentaje, unidades o decimales */
export default function NumberFieldFormats() {
return (
<div className="grid w-full max-w-lg gap-5 sm:grid-cols-2">
<NumberField label="Beca" defaultValue={0.5} min={0} max={1} step={0.05} format={{ style: "percent" }} hint="El valor interno es 0,5." />
<NumberField label="Distancia a la sede" defaultValue={12} min={0} step={1} largeStep={10} format={{ style: "unit", unit: "kilometer" }} hint="Shift + flecha salta de a 10." />
<NumberField label="Arancel" defaultValue={20500} min={0} step={500} format={{ style: "currency", currency: "ARS", maximumFractionDigits: 0 }} />
<NumberField label="Nota" defaultValue={7.5} min={1} max={10} step={0.5} format={{ minimumFractionDigits: 1, maximumFractionDigits: 1 }} hint="De 1 a 10, con medios puntos." />
</div>
);
}Reglas
- Siempre con
minymaxrazonables: los botones se deshabilitan en los límites. - El
stepes la unidad real (1.000 para montos, 1 para unidades).largeStepcon Shift para saltos grandes. - Mostrá el formato en el campo (
format): "$ 99.000" se lee mejor que "99000". - La ayuda dice el rango: "Entre 1 y 12".
Medidas
El campo mide igual que Input. Los botones ocupan todo el alto, con ancho 32 / 40 / 48, separados por una línea.
| Parte | Propiedad | Token |
|---|---|---|
| Campo | Todos los estados | — |
| Botón − / + | Icono → hover | icon/muted |
| Botón · hover | Fondo | bg/subtle |
| Divisor | Borde | border/default |
| Botón · límite | Icono | text/disabled |
| Foco en botón | Anillo interior 2 px | focus/ring |
Instalación
npx shadcn@latest add https://polen.cdc.cool/r/number-field.jsonPlayground
Configurá el componente y copiá el snippet: se genera del mismo estado que renderiza el preview.
size
Formato
<NumberField label="Cantidad de cuotas" defaultValue={6} min={1} max={12} />Props
Sobre Base UI Number Field.
| Prop | Tipo | Default | Descripción |
|---|---|---|---|
value / defaultValue | number | null | — | Controlado o inicial. |
onValueChange | (value: number | null) => void | — | Al cambiar. |
min · max · step | number | — | Límites y paso. |
largeStep | number | — | Paso con Shift. |
format | Intl.NumberFormatOptions | — | Moneda, decimales, unidades. |
locale | string | "es-AR" | Locale del formato (1.250,50). |
size · label · hint · error · required · disabled | — | — | Como en Input. |
| Tecla | Qué hace |
|---|---|
| ↑↓ | Suma o resta un paso. |
| Shift↑ | Suma el paso grande. |
| HomeEnd | Va al mínimo / máximo. |
role="spinbutton"conaria-valuenow,-valuemin,-valuemaxy el valor formateado comoaria-valuetext.- Los botones − / + tienen nombre ("Restar", "Sumar") y se deshabilitan en los límites.
- Teclado numérico en mobile.