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
Con error y rueda del mouse
Con prefijo de moneda
Con sufijo de unidad
Con paso grande
Solo lectura
Cargando
Formato de moneda con ayuda
Formato de porcentaje
Con valores negativos
Deshabilitado
Limpiable
Sin botones de paso
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/stepacordes 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
fieldpara 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.
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-wheeldata-ts-cleardata-ts-large-stepdata-ts-localedata-ts-numberdata-ts-number-fielddata-ts-number-formatdata-ts-number-rawdata-ts-number-spinnerdata-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-step | Cuánto saltan PageUp y PageDown, en lugar de step × 10. |
data-ts-allow-wheel | La rueda del mouse no cambia el valor salvo con este atributo; sin él reenvía el scroll a la página. |
readonly | En 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-suffix | Prefijo y sufijo: marcado y CSS. |
setNumberInputLoading(root, true | false) | Pone is-loading, aria-busy y el Spinner. |
data-ts-number-format, data-ts-locale | data-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.csstaisho.icon.csstaisho.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-labelpropio y se deshabilitan al alcanzarmin/max. - El
labelse asocia víafor/id. - El texto de ayuda y el mensaje de error se enlazan al campo por
aria-describedby; un campo inválido llevaaria-invalid="true". - La rueda del mouse no cambia el valor salvo que se habilite (y sólo con el campo enfocado):
data-ts-allow-wheelen 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, respetandodeltaXydeltaMode. - 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_INTEGERse clampea a ese límite (un entero mayor perdería dígitos en silencio). readonlypone 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 esdisabled: éste además saca el campo del foco.- Para el estado de carga, se llama a
setNumberInputLoading(root, true|false): poneis-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) ydata-ts-localeen la raíz, el campo pasa atype="text"coninputmode="decimal"yrole="spinbutton", conaria-valuenow(el número crudo),aria-valuemin/aria-valuemaxyaria-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 >= 0el signo menos no se acepta al tipearlo (no se escribe y luego se corrige al salir). Conminnegativo o sinminentra. - El prefijo y el sufijo (
ts number-input-prefixyts 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 ellabel(por ejemplo «Precio en USD»). - El botón de limpiar (
data-ts-clear) lleva suaria-labelescrito en el HTML, aparece sólo con valor y no con el campodisabledoreadonly. 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. |
| HomeEnd | Llevan a min / max. Sin ese límite conservan su función nativa (mover el cursor del texto). |
| PageUpPageDown | Saltan 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.