Saltar al contenido

NumberInput

Campo numérico con botones de incremento/decremento. Respeta min, max y step, responde a las flechas del teclado y, con data-ts-number-format, muestra moneda, miles o porcentaje sin perder el número crudo.

Formularios · TaishoDS Core, en HTML plano.

Ejemplos

Un ejemplo por caso, funcionando. Cada ejemplo es el HTML de su vista previa: se copia tal cual y, con el CSS y el JS del Core cargados, se ve y funciona igual.

Cantidad con mínimo y máximo

html

Con error y rueda del mouse

html

Con prefijo de moneda

USD
html

Con sufijo de unidad

GB
html

Con paso grande

html

Solo lectura

html

Cargando

html

Formato de moneda con ayuda

html

Formato de porcentaje

html

Con valores negativos

html

Deshabilitado

html

Limpiable

html

Sin botones de paso

USD
html

Cuándo usarlo

  • Capturar una cantidad exacta: cantidad, edad, precio, con un paso definido.
  • Conviene ajustar de a pasos con los botones o las flechas.
  • Lo que importa es el valor preciso, no una aproximación.

Cuándo no

  • El valor es aproximado dentro de un rango y ayuda el feedback visual → slider.
  • No es un número sino texto → input.

Cómo usarlo

  • Se fijan min/max/step acordes al dato real.
  • Para precios y porcentajes se usa data-ts-number-format: se ve "12.500,50 US$" y el form recibe 12500.5.
  • Se arma con el HTML de field para el label y los errores.

Cómo no usarlo

  • No se usa para rangos enormes donde escribir es más rápido que tabular pasos.
  • No se omiten los límites: dejar pasar cualquier número traslada el error aguas abajo.

Relacionados

SliderInputField

TaishoDS Core

Necesita el JS del Core: lo engancha por atributos data-ts-*.

Se monta sobre un <input> nativo, pero los botones +/− y el paso con flechas son propios.

El Core lo engancha por estos atributos. Van en el marcado; no hace falta inicializar nada.

  • data-ts-allow-wheel
  • data-ts-clear
  • data-ts-large-step
  • data-ts-locale
  • data-ts-number
  • data-ts-number-field
  • data-ts-number-format
  • data-ts-number-raw
  • data-ts-number-spinner
  • data-ts-number-step

Qué hace: Incrementa y decrementa respetando min, max y step, y restaura el último valor válido al perder el foco. Home y End van a min y max (sólo si existen); PageUp y PageDown saltan step × 10. El texto no se reescribe mientras se tipea, y un número fuera de ±Number.MAX_SAFE_INTEGER se acota al perder el foco. Con min mayor o igual a 0 el signo - no se acepta.

Atributo Qué hace
data-ts-large-stepCuánto saltan PageUp y PageDown, en lugar de step × 10.
data-ts-allow-wheelLa rueda del mouse no cambia el valor salvo con este atributo; sin él reenvía el scroll a la página.
readonlyEn el input: los botones quedan deshabilitados y no cambian el valor ni las flechas, ni las teclas, ni la rueda.
ts number-input-prefix, ts number-input-suffixPrefijo y sufijo: marcado y CSS.
setNumberInputLoading(root, true | false)Pone is-loading, aria-busy y el Spinner.
data-ts-number-format, data-ts-localedata-ts-number-format es un JSON de Intl.NumberFormatOptions. El campo pasa a ser de texto y muestra el valor formateado salvo con foco, donde edita el número crudo. El crudo viaja en el hidden data-ts-number-raw.

Sin build, desde el CDN: taisho.number-input.css, además de taisho.base.css. También se carga:

  • taisho.button.css
  • taisho.icon.css
  • taisho.spinner.css

Para el funcionamiento general del Core, ver Comportamiento.

Accesibilidad

Implementa el patrón Spinbutton de la WAI-ARIA APG.

  • Las flechas ↑/↓ del teclado incrementan y decrementan por step; Home/End y PageUp/PageDown siguen el patrón spinbutton de la APG (React Aria las trae igual).
  • Los botones de + / − tienen aria-label propio y se deshabilitan al alcanzar min/max.
  • El label se asocia vía for/id.
  • El texto de ayuda y el mensaje de error se enlazan al campo por aria-describedby; un campo inválido lleva aria-invalid="true".
  • La rueda del mouse no cambia el valor salvo que se habilite (y sólo con el campo enfocado): data-ts-allow-wheel en la raíz. Sin eso el campo conserva el foco —no se lo suelta— y el scroll se reenvía al ancestro scrollable más cercano o a la página, respetando deltaX y deltaMode.
  • Al perder el foco con el campo vacío o inválido se restaura el último valor válido: lo que ve el usuario y lo que viaja en el formulario coinciden.
  • El texto del campo no se reescribe mientras se tipea: sólo se normaliza al perder el foco. Un número que excede ±Number.MAX_SAFE_INTEGER se clampea a ese límite (un entero mayor perdería dígitos en silencio).
  • readonly pone el atributo nativo en el <input>: sigue enfocable y copiable, los botones +/− quedan deshabilitados y ni las flechas, ni las teclas de navegación, ni la rueda cambian el valor. No es disabled: éste además saca el campo del foco.
  • Para el estado de carga, se llama a setNumberInputLoading(root, true|false): pone is-loading, aria-busy="true" en el <input> y el Spinner al final del campo. Si se pone sólo la clase, no se anuncia. No bloquea la edición.
  • Con data-ts-number-format (moneda, miles, porcentaje) y data-ts-locale en la raíz, el campo pasa a type="text" con inputmode="decimal" y role="spinbutton", con aria-valuenow (el número crudo), aria-valuemin/aria-valuemax y aria-valuetext (el valor formateado, para que el lector diga «12.500,50 US$» y no «12500.5»). Sin foco se ve el valor formateado; con foco, el número crudo para editarlo. Sólo admite dígitos, separador decimal y -.
  • Con min >= 0 el signo menos no se acepta al tipearlo (no se escribe y luego se corrige al salir). Con min negativo o sin min entra.
  • El prefijo y el sufijo (ts number-input-prefix y ts number-input-suffix, para unidad o moneda) son texto decorativo junto al campo: si la unidad es clave para entender el dato, se repite en el label (por ejemplo «Precio en USD»).
  • El botón de limpiar (data-ts-clear) lleva su aria-label escrito en el HTML, aparece sólo con valor y no con el campo disabled o readonly. Con él, un campo vacío es un estado válido: no se restaura al salir y el foco vuelve al campo. Si no se ponen los botones −/+, las flechas ↑/↓ y las teclas de salto siguen actuando.

Teclado

Además de lo que ya hace el navegador (Tab mueve el foco, Enter activa un botón).

Tecla Qué hace
↑↓Suman o restan step al valor (0,5 + 1 = 1,5), igual que los botones.
HomeEndLlevan a min / max. Sin ese límite conservan su función nativa (mover el cursor del texto).
PageUpPageDownSaltan el paso grande (data-ts-large-step en la raíz; por defecto, diez veces el paso).

Verificación

Qué se probó de verdad. Lo que no se probó lo dice: preferimos un «sin verificar» a una afirmación de más.

  • axe WCAG 2.2 A + AA en navegador real, en tema claro y oscuro, antes de cada versión.
  • teclado Mapa de teclas documentado arriba, contrastado contra el componente.
  • lector de pantalla Sin verificar con lector de pantalla. Conviene probarlo en la combinación de componentes propia, no sólo aquí, donde cada uno aparece solo y en su estado feliz.