Saltar al contenido

DatePicker

beta

Selección de una fecha: un disparador tipo input abre un calendario navegable por teclado (patrón APG). Trabaja con Date nativo y cero dependencias; los nombres de mes y día salen de Intl. El panel vive en el top-layer nativo (Popover API). Con data-ts-range elige un tramo (inicio y fin) en el mismo calendario, con data-ts-date-preset suma atajos (hoy, últimos 7 días, este mes) en una columna junto a la grilla, y con data-ts-date-text se puede escribir la fecha en un campo de texto.

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.

Calendario suelto

html

Fecha de despliegue con mínimo y máximo

html

Obligatoria, con ayuda

html

Con mensaje de error

html

Limpiable

html

Sin fines de semana ni feriados

html

Con marcas por día

html

Densidad compacta

html

Cargando

html

Rango de fechas

html

Con atajos de fecha

html

Rango con atajos

html

Fecha escrita a mano

Formato: dd/mm/aaaa
html

Varios meses

html

Selector de mes y año

html

Número de semana

html

Fecha y hora

html

Cuándo usarlo

  • Capturar una fecha donde ver el calendario ayuda a elegir (reservas, vencimientos).
  • Hace falta un tramo con inicio y fin (una ventana de despliegue, un periodo de facturación): data-ts-range.
  • El contexto del mes o la semana importa para decidir.
  • La gente conoce la fecha de memoria o la pega de otro lado (un vencimiento, un ticket): data-ts-date-text suma un campo donde se escribe.
  • Hay elecciones que se repiten (hoy, los últimos 7 días, este mes): se suman como atajos con data-ts-date-preset.
  • Hace falta restringir a un rango (data-ts-min/data-ts-max) o respetar un locale (data-ts-locale).
  • Se busca el campo completo, con label, ayuda y error.
  • Hay días que no se pueden elegir (fines de semana, feriados, una regla propia) o que conviene señalar con una marca (reuniones, despliegues).

Cuándo no

  • La fecha es conocida y tipear es más rápido (una fecha de nacimiento) → un input con formato.
  • Es sólo una hora, sin fecha, o un valor que no es una fecha → el control que corresponda.

Cómo usarlo

  • Se restringe a las fechas válidas con data-ts-min/data-ts-max, y los días sueltos que no se pueden elegir se marcan con data-ts-disabled-weekdays, data-ts-disabled-dates o setDatePickerDisabledDate.
  • data-ts-day-marks señala eventos con un punto y un texto corto: el texto llega al lector de pantalla y al title.
  • Mientras se traen marcas o días no disponibles del servidor, se llama a setDatePickerLoading(root, true): no bloquea el campo.
  • Se arma con el HTML de field para formularios, o con su label, ayuda y error pegados al campo si va suelto; el formato esperado debe quedar claro.
  • En el campo tipeable (data-ts-date-text), readonly muestra una fecha que no se edita, en vez de disabled: sigue enfocable y se lee mejor.
  • Para los atajos relativos se usan las claves (today, last-7-days, last-30-days, this-week, this-month, last-month): se resuelven al hacer clic, no al armar la página.
  • Con data-ts-range, si va en un formulario, se pone name en los dos <input type="hidden"> (data-ts-date-input="start" y "end"): viajan dos fechas yyyy-mm-dd, inicio y fin.

Cómo no usarlo

  • No se obliga a navegar meses para una fecha lejana ya conocida.
  • No se activa data-ts-date-text si sólo se elige entre pocas fechas del calendario: un campo editable invita a errores de tipeo que el calendario evita.
  • No se espera ts:change en el primer clic de un rango: sale recién cuando el rango está completo o se limpia.
  • No se pasa una clave de rango en un calendario simple (ni today como rango de varios días): no se dibuja y en desarrollo avisa.
  • No se asume un formato: se respeta el locale del usuario.
  • El color de la marca no es la única señal: siempre se escribe su label.

Relacionados

FieldInput

TaishoDS Core

Necesita el JS del Core: maneja foco, teclado y estado.

Es un calendario propio con navegación por teclado; el <input> nativo sólo aporta el campo de texto.

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

  • data-ts-clear
  • data-ts-count-suffix
  • data-ts-date-caption
  • data-ts-date-grid
  • data-ts-date-input
  • data-ts-date-months
  • data-ts-date-next
  • data-ts-date-picker
  • data-ts-date-preset
  • data-ts-date-prev
  • data-ts-date-spinner
  • data-ts-date-status
  • data-ts-date-text
  • data-ts-date-time
  • data-ts-date-title
  • data-ts-date-weekdays
  • data-ts-day-marks
  • data-ts-disabled-dates
  • data-ts-disabled-weekdays
  • data-ts-end-text
  • data-ts-granularity
  • data-ts-hour-cycle
  • data-ts-listbox
  • data-ts-listbox-label
  • data-ts-listbox-loading
  • data-ts-listbox-native
  • data-ts-listbox-panel
  • data-ts-listbox-spinner
  • data-ts-listbox-trigger
  • data-ts-locale
  • data-ts-month
  • data-ts-number
  • data-ts-number-field
  • data-ts-number-format
  • data-ts-number-raw
  • data-ts-number-spinner
  • data-ts-number-step
  • data-ts-placeholder
  • data-ts-range
  • data-ts-required-proxy
  • data-ts-value
  • data-ts-visible-months
  • data-ts-week-column
  • data-ts-week-numbers
  • data-ts-week-short

Qué hace: Dibuja la grilla del calendario, navega por teclado y formatea la fecha. Con disparador funciona completo, con el calendario en un panel que abre, cierra y devuelve el foco. Cada día lleva su nombre accesible con la fecha completa. Si los atributos de abajo cambian por JavaScript, el calendario se redibuja.

Atributo Qué hace
popovertarget (en el disparador)El botón abre el calendario con la Popover API nativa y mantiene aria-expanded e is-open. Al abrir, el calendario vuelve al mes del valor con el foco en su día. Elegir un día (clic, Enter o Espacio) cierra el panel, escribe la fecha formateada en el disparador y el valor yyyy-mm-dd en el <input type="hidden" name>, y el foco vuelve al botón. Escape y clic afuera cierran. Mayús + RePág/AvPág navegan por año.
data-ts-min, data-ts-maxLos días fuera de rango quedan aria-disabled: enfocables, no elegibles.
data-ts-week-start="0"Primer día de la semana.
data-ts-localeIdioma de los nombres de mes y día, y del formato de la fecha.
placeholder, disabled, size, densityLos de siempre: atributos nativos y clases del componente. También anda en RTL.
data-ts-disabled-datesDías no disponibles, separados por espacio: "2026-12-25 2027-01-01".
data-ts-disabled-weekdaysDías de la semana no disponibles: "0 6".
setDatePickerDisabledDate(root, fn)Una función decide qué días no están disponibles; null la quita.
data-ts-day-marksMarcas por día, con JSON: [{"date":"2026-12-25","label":"Despliegue","variant":"success"}].
data-ts-visible-monthsCuántos meses se ven a la vez. El Core dibuja una grilla por mes dentro de div.ts.calendar-months[data-ts-date-months], que reemplaza a la grilla única; la raíz lleva is-multi.
data-ts-caption-layout="dropdown"Selector de mes y año. En la cabecera van dos Select con data-ts-date-caption="month" y "year" en su disparador, cada uno con su opción vigente: el Core la toma de molde y completa las demás según data-ts-min y data-ts-max.
data-ts-week-numbersColumna con la semana ISO. Su valor es el nombre accesible de cada número, con {n} en el lugar del número ("Semana {n}"); data-ts-week-short es el texto del encabezado y data-ts-week-column, su nombre accesible. La raíz lleva has-week-numbers.
data-ts-granularity="minute", data-ts-hour-cycleFecha con hora, sólo en modo simple. data-ts-value, data-ts-min, data-ts-max y el hidden van como yyyy-mm-ddThh:mm en hora local. Bajo la grilla, en div.ts.calendar-time, van dos NumberInput con data-ts-date-time="hour" y "minute" en su input y, con data-ts-hour-cycle="12", un Select con "period" en su disparador. Elegir un día no cierra el panel.
data-ts-date-presetAtajos: botones dentro de div.ts.datepicker-presets[role=group] en el panel, con una clave (today, last-7-days…), un día yyyy-mm-dd o un intervalo inicio/fin. Confirman y cierran como elegir un día, y quedan aria-disabled si caen fuera de min/max o no están disponibles.
ts datepicker-prefix-blockPrefijo: un span primero en el disparador, o un div primero en div.ts.datepicker-field. Es marcado y CSS.
data-ts-date-textCampo tipeable: div.ts.datepicker-field con input.ts.datepicker-input[data-ts-date-text] ("start" y "end" con range, dentro de role=group) y el botón .ts.datepicker-toggle con popovertarget. El Core confirma al salir del campo o con Enter (sin consumir la tecla, así un <form> sigue su envío), escribe el hidden y reformatea. Un valor inválido, fuera de rango o no disponible vuelve al último válido, y vacío quita la fecha (ts:change con valor vacío). required, readonly y disabled son los nativos del input.
data-ts-rangeRango, en la raíz del calendario; data-ts-value es el intervalo ISO (2026-07-01/2026-07-31). El primer clic fija el inicio, la vista previa sigue al puntero y al foco, una región viva anuncia el inicio (plantilla data-ts-end-text) y hay dos hidden, data-ts-date-input="start" y "end". ts:change lleva value, start y end, y sólo sale al completar o limpiar.
setDatePickerLoading(root, true | false)Pone is-loading, aria-busy y el Spinner de data-ts-date-spinner; no bloquea.
ts:changeElegir un día lo emite, cancelable. form.reset() vuelve a la fecha inicial sin emitirlo.

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

  • taisho.button.css
  • taisho.checkbox.css
  • taisho.icon.css
  • taisho.input.css
  • taisho.kbd.css
  • taisho.number-input.css
  • taisho.popover.css
  • taisho.select.css
  • taisho.spinner.css

Para el funcionamiento general del Core, ver Comportamiento.

Accesibilidad

Implementa el patrón Date Picker Dialog de la WAI-ARIA APG.

  • El trigger es un <button> con aria-haspopup="dialog" y aria-expanded que refleja si el calendario está abierto (también en el Core, que lo sincroniza al abrir y cerrar el popover); el panel es un role="dialog" con nombre accesible.
  • La grilla usa role="grid" con roving tabindex: flechas mueven día/semana, Home/End inicio/fin de semana, RePág/AvPág cambian de mes (con Mayús, de año), Enter/Espacio eligen. El grupo y la grilla se nombran con el mes visible («Julio de 2026»).
  • Cada día es un gridcell con la fecha completa como nombre accesible; aria-selected indica el elegido y los días fuera de rango llevan aria-disabled (siguen enfocables, no se eligen). El nombre es la fecha completa, no sólo el número del día.
  • form.reset() devuelve la fecha inicial (texto del disparador, hidden y calendario) sin disparar ts:change.
  • El disparador se nombra por aria-labelledby (label + fecha elegida) y aria-describedby apunta a la ayuda o al error; un campo inválido lleva aria-invalid="true" y el mensaje se anuncia con aria-live="polite". El asterisco de obligatorio es decorativo (aria-hidden): un <button> no admite required ni aria-required, así que el bloqueo del envío lo lleva un <input data-ts-required-proxy> sin name, invisible, aria-hidden y fuera del orden de Tab: enviar vacío muestra el mensaje nativo del navegador y el foco cae en el disparador. No valida con disabled ni readonly.
  • Los días no disponibles (data-ts-disabled-dates, data-ts-disabled-weekdays o una función con setDatePickerDisabledDate(root, fn)) llevan aria-disabled="true": siguen enfocables con las flechas (APG) pero Enter, Espacio y clic no los eligen. El calendario se redibuja si cambian por JS.
  • Las marcas de día (data-ts-day-marks) agregan al nombre accesible de la celda el texto de la marca («jueves, 25 de diciembre de 2026, Navidad»; con varias, unidas con coma) y lo repiten en el title. El punto de color es decorativo (aria-hidden): el color nunca es la única señal.
  • Para el estado de carga, se llama a setDatePickerLoading(root, true|false): pone is-loading y aria-busy="true" en el disparador y la grilla, y muestra un Spinner (un role="status" que anuncia el estado). Si se pone sólo la clase, no se anuncia. No bloquea: el calendario abre y se puede elegir.
  • Los atajos (data-ts-date-preset) son botones dentro de un role="group" con nombre. Uno que cae fuera del rango permitido, o cuyo extremo es un día no disponible, lleva aria-disabled="true": sigue enfocable y no se elige, como los días. Cada atajo trae una clave (today, last-7-days, this-week…), un día yyyy-mm-dd o un intervalo inicio/fin; las claves se resuelven contra hoy al clic y el Core recalcula aria-disabled cada vez que abre el panel.
  • Con data-ts-range la grilla lleva aria-multiselectable="true" y aria-selected="true" en todo el tramo (extremos e interior; la vista previa también). Tras el primer clic una región viva (role="status", data-ts-date-status) anuncia «Inicio: martes, 14 de julio de 2026. Elegir la fecha de fin.» y se vacía al completar o descartar. El disparador muestra el rango con Intl.DateTimeFormat.formatRange. Los extremos tienen que estar disponibles; el tramo puede cruzar días con aria-disabled. El valor se declara con data-ts-value="inicio/fin" y ts:change trae start y end.
  • Con el campo tipeable (data-ts-date-input, patrón APG Date Picker Dialog) el disparador es un <input type="text"> nombrado por su label (o por aria-label si no hay), con aria-describedby que suma un texto oculto con el formato esperado («Formato: dd/mm/aaaa») y el mismo patrón como placeholder. El botón de calendario aparte lleva aria-label, aria-haspopup="dialog" y aria-expanded. required, readonly y disabled son los nativos del input (el mensaje de validación es el del navegador; no hace falta el input de validación). Con readonly no hay botón. En rango los dos campos viven en un role="group" nombrado por el label y cada uno lleva su aria-label («Fecha de inicio» / «Fecha de fin»). aria-invalid y aria-busy van en los inputs.
  • readonly deja el disparador enfocable y sin disabled, pero sin aria-haspopup, aria-expanded ni calendario: Enter, Espacio y clic no hacen nada y el valor viaja en el form. Es un <button>, así que no lleva aria-readonly (no es válido en su rol).
  • El botón de limpiar (data-ts-clear) es un <button> hermano del disparador, con nombre «Limpiar campo»; Tab llega a él después del disparador. Al activarlo cierra el calendario, devuelve el foco al disparador y avisa con ts:change.
  • Hoy se marca con un punto bajo el número (color del texto, así contrasta también sobre el día seleccionado) además del peso; con forced-colors no cuenta el punto sino el subrayado. El foco de día es un anillo interno de 2px con la tinta de foco de la familia, sin bordes.
  • En RTL los chevrones de mes se reflejan (el anterior apunta a la derecha) y, con forced-colors: active, el día seleccionado usa Highlight/HighlightText, hoy va subrayado (o con punto de sistema si además está seleccionado) y el foco lleva outline de sistema.
  • Los textos (mes anterior/siguiente, «elegir una fecha») vienen escritos en el HTML; los nombres de mes y de día, de Intl según el locale (data-ts-locale).
  • Con data-ts-visible-months cada mes es su propia role="grid", nombrada con su mes; hay un solo día tabulable en todo el calendario y las flechas cruzan de una grilla a la otra. La vista sólo se mueve cuando el día enfocado sale de lo visible, y el rótulo con el tramo de meses se anuncia con aria-live. Los días de relleno quedan como celdas vacías, para que ninguna fecha se lea dos veces.
  • Con data-ts-caption-layout="dropdown" la cabecera suma dos Select nombrados «Mes» y «Año» (traducibles), en el orden de tabulación entre las flechas. El rótulo del mes sigue en el DOM para el lector y se anuncia con aria-live al cambiar. Escape con un selector abierto cierra sólo ese selector. Después de saltar de mes, la grilla conserva su día tabulable.
  • Con data-ts-week-numbers cada fila empieza con un role="rowheader" nombrado «Semana 29» (traducible) y la columna tiene su columnheader. El número no es enfocable ni elegible: las flechas siguen yendo de día a día.
  • Con data-ts-granularity="minute" las horas y los minutos son role="spinbutton" (flechas, RePág y AvPág) dentro de un role="group" llamado «Hora», con nombres traducibles; con reloj de 12 horas suma un Select de período. Elegir un día no cierra el panel y el foco sigue en la grilla, así que Tab llega a la hora. Sin fecha elegida los campos quedan deshabilitados. Escape cierra el panel y el valor ya elegido se conserva.

Teclado

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

Tecla Qué hace
←→↑↓Mueve el día enfocado (día y semana). En RTL la grilla se espeja: ← avanza un día y → retrocede.
Home/EndPrimer y último día de la semana.
RePág/AvPágMes anterior y siguiente; si el día no existe en ese mes, cae en el último.
Mayús+RePág/AvPágAño anterior y siguiente.
Enter/EspacioSelecciona el día enfocado, cierra el calendario y devuelve el foco al disparador.
Enter/Espacio(con`data-ts-range`)La primera vez fija el inicio y el calendario sigue abierto; las flechas mueven la vista previa del tramo; la segunda vez fija el fin, cierra y devuelve el foco al disparador. Escape a mitad de camino descarta el inicio.
Tab(atajos)Con atajos (data-ts-date-preset), Tab recorre primero los atajos (columna al inicio del panel) y después el calendario; al abrir, el foco sigue en el día. Enter, Espacio o clic en un atajo confirma el valor, cierra el panel y devuelve el foco al disparador.
Escribir/Enter/Tab(`data-ts-date-input`)Con el campo tipeable, clic o Tab entran sin abrir el calendario (el botón de calendario es otro tabulable, después del campo). Enter o salir del campo confirma lo escrito; si es ilegible, inexistente, fuera del rango permitido o un día no disponible, el texto vuelve al último valor válido, y vacío quita la fecha. Dentro de un <form>, Enter deja seguir el envío. En rango, Tab pasa del campo de inicio al de fin sin confirmar; el par se confirma al salir del grupo.
Enter/Espacio/clic(disparador)Abre el calendario con el foco en el día enfocable (el seleccionado o, sin valor, hoy). Escape lo cierra y devuelve el foco al disparador.

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.