Datepicker — Ariane

Sur cette page

Accessibilité

Lien direct vers cette section

Le calendrier suit le pattern APG Date Picker Dialog.

Pris en charge automatiquement

Lien direct vers cette section

Navigation clavier complète dans la grille de jours (WCAG 2.1.1 (ouvre dans un nouvel onglet)Keyboard : toutes les fonctionnalités sont accessibles au clavier.)
Focus piégé dans le dialog calendrier lors de son ouverture, restitué à l’input à la fermeture (WCAG 2.1.2 (ouvre dans un nouvel onglet)No Keyboard Trap : le focus peut être déplacé hors du composant.)
Le slot error est relié à l’input par aria-describedby : le message est lu quand le champ reçoit le focus (WCAG 1.3.1 (ouvre dans un nouvel onglet)Info and Relationships : les informations et relations présentées visuellement sont aussi disponibles par programme.)
aria-invalid="true" sur l’input quand le slot error est rempli ou quand le champ est invalide après une interaction, comme un champ natif
aria-disabled="true" sur les jours hors plage et les jours désactivés (WCAG 4.1.2 (ouvre dans un nouvel onglet)Name, Role, Value : les états des éléments interactifs sont communiqués aux AT.)
Le hint par défaut donne un exemple de date formatée et, avec min ou max, la plage sélectionnable (WCAG 3.3.2 (ouvre dans un nouvel onglet)Labels or Instructions : des instructions sont fournies lorsque le contenu nécessite une saisie de l'utilisateur.)

Raccourcis clavier du calendrier

Lien direct vers cette section

Touche	Action
`↑↓←→`	Naviguer de jour en jour / semaine
`Home` / `End`	Premier / dernier jour de la semaine
`Page Up` / `Page Down`	Mois précédent / suivant
`Shift` + `Page Up` / `Page Down`	Année précédente / suivante
`Entrée` / `Espace`	Sélectionner le jour focalisé
`Escape`	Fermer sans sélectionner

À votre charge

Lien direct vers cette section

Label : toujours fournir un label via la prop label ou le slot label.
Hint : pour un autre contenu que le hint par défaut, utiliser le slot hint (jamais placeholder, qui disparaît à la saisie). Il remplace le hint par défaut, exemple de date et plage min/max compris : à répéter si nécessaire.
Annonce des erreurs : le composant n’annonce pas un message d’erreur à son apparition. À la soumission d’un formulaire, affichez un récapitulatif des erreurs et placez le focus dessus ou sur le premier champ en erreur (voir Formulaires).
Focus des jours : l’indicateur de focus visible (WCAG 2.4.7 (ouvre dans un nouvel onglet)Focus Visible : le composant recevant le focus clavier doit être visuellement identifiable.) est porté par --ar-datepicker-day-focus-ring-color/-width/-offset. --ar-datepicker-day-focus-border-color est cosmétique : le redéfinir n’affecte pas la garantie WCAG 2.4.7.

Utilisation

Lien direct vers cette section

Largeur du champ de saisie

Lien direct vers cette section

--ar-datepicker-input-max-width est calculé par défaut d’après la longueur de format, indépendamment de la largeur du hint. Si vous le surchargez, restez proche du contenu attendu dans le champ.

Formulaires

Lien direct vers cette section

ar-datepicker se comporte comme un champ de formulaire natif : soumission, validation, états et réinitialisation sont décrits dans la page Formulaires. Propre au datepicker, form.reset() ramène aussi le texte de saisie à son état initial, et un panneau ouvert se ferme avec ses événements habituels (ar-datepicker-hide, ar-datepicker-hidden).

Intégration masque de saisie

Lien direct vers cette section

Le getter inputElement expose l’<input> interne pour y brancher une bibliothèque de masque comme IMask :

import IMask from 'imask';
const picker = document.querySelector('ar-datepicker');
IMask(picker.inputElement, { mask: Date });

Libellés des boutons « Aujourd’hui » et « Fermer »

Lien direct vers cette section

Ces textes suivent l’attribut lang (cf. Traductions). Les slots today-label / close-label les remplacent par un contenu plus riche ; le texte traduit reste la source de l’aria-label du <button>, même si le slot ne contient qu’une icône :

<ar-datepicker lang="en">
    <span slot="close-label" aria-hidden="true">✕</span>
</ar-datepicker>

Exemples

Lien direct vers cette section

Les exemples de cette page sont affichés avec le thème neutre du starter-kit.

Par défaut

Lien direct vers cette section

Date unique avec format français. Le hint par défaut affiche un exemple de date.

Voir le code

<ar-datepicker
  label="Date de naissance"
  format="dd/MM/yyyy"
  lang="fr-FR"
></ar-datepicker>

Avec erreur

Lien direct vers cette section

Lorsque le slot "error" est rempli, le composant expose `:state(has-error)`.

Date invalide ou hors plage autorisée

Voir le code

<ar-datepicker label="Date de naissance">
  <span slot="error">Date invalide ou hors plage autorisée</span>
</ar-datepicker>

Readonly

Lien direct vers cette section

Valeur affichée non modifiable, soumise au formulaire.

Voir le code

<ar-datepicker value="2026-06-12" readonly label="Date"></ar-datepicker>

Disabled

Lien direct vers cette section

Composant désactivé, valeur exclue du formulaire.

Voir le code

<ar-datepicker value="2026-06-12" disabled label="Date"></ar-datepicker>

Plage de dates

Lien direct vers cette section

`min` et `max` restreignent les jours sélectionnables. Le hint par défaut annonce la plage.

Voir le code

<ar-datepicker
  label="Date de rendez-vous"
  min="2026-01-01"
  max="2026-12-31"
  lang="fr-FR"
></ar-datepicker>

Dates désactivées

Lien direct vers cette section

`isDateDisabled` désactive des jours selon une règle libre, ici les week-ends, et rend le champ invalide si l'un d'eux est saisi à la main. Le hint par défaut ne les décrit pas.

Voir le code

<ar-datepicker id="demo-disabled-dates" label="Date de rendez-vous" lang="fr-FR"></ar-datepicker>
<script>
    document.getElementById('demo-disabled-dates').isDateDisabled = function (date) {
        return date.getDay() === 0 || date.getDay() === 6;
    };
</script>

Langue et format

Lien direct vers cette section

L'attribut `lang` pilote les textes et les formats, sauf le label de l'input.

Voir le code

<ar-datepicker
  label="Date of birth"
  format="MM/dd/yyyy"
  lang="en-US"
></ar-datepicker>

Démo interactive

Lien direct vers cette section

Manipulez les attributs pour voir le code et la preview se mettre à jour.

<ar-datepicker
  label="Date de naissance"
  format="dd/MM/yyyy"
  lang="fr-FR"
></ar-datepicker>

Référence API

Lien direct vers cette section

Import

Lien direct vers cette section

Si vous utilisez l'autoloader, les composants détectés dans la pages sont chargés automatiquement, donc pas besoin de les importer individuellement.
Pour un import manuel, voici comment vous y prendre.

CDN

npm

Importez ce composant depuis le CDN.

<script type="module" src="https://unpkg.com/@ariane-ui/core/dist/components/datepicker/index.js"></script>

Après avoir installé le paquet via npm, vous pouvez importer le composant ainsi :

import '@ariane-ui/core/dist/components/datepicker/index.js';

Configuration

Lien direct vers cette section

Attributs et propriétés 14

Slots 6

Événements 9

Méthodes 3

valuereflète

Valeur ISO `yyyy-MM-dd` de la date sélectionnée.

Type stringDéfaut ''

formatreflète

Format de saisie/affichage (tokens `dd`, `MM`, `yyyy`). Défaut : `dd/MM/yyyy`.

Type stringDéfaut 'dd/MM/yyyy'

minreflète

Date minimale sélectionnable (ISO `yyyy-MM-dd`).

Type stringDéfaut ''

maxreflète

Date maximale sélectionnable (ISO `yyyy-MM-dd`).

Type stringDéfaut ''

placeholderreflète

Texte placeholder de l'input.

Type stringDéfaut ''

autocompletereflète

Valeur `autocomplete` de l'input natif.

Type stringDéfaut ''

labelreflète

Label du champ (alternative au slot `label`).

Type stringDéfaut ''

readOnlyreflètereadonly

Bloque la saisie tout en soumettant la valeur au formulaire.

Type booleanDéfaut false

openreflète

Ouvre ou ferme le popover calendrier.

Type booleanDéfaut false

pendingreflète

Attente d'une réponse, pilotée par l'application (par exemple les jours désactivés du mois affiché, à charger après `ar-datepicker-view-change`). Le composant ne le pose ni ne le retire jamais. Non bloquant : le calendrier reste utilisable. Pose `aria-busy="true"` sur le panneau, l'état `:state(pending)` et annonce l'attente au passage `false → true`.

Type booleanDéfaut false

namereflète

Identifie le champ dans `FormData`.

Type stringDéfaut ''

disabledreflète

Désactive le champ et exclut sa valeur du formulaire.

Type booleanDéfaut false

requiredreflète

Active la contrainte de validation native `required`.

Type booleanDéfaut false

isDateDisabled

Prédicat fourni par l'application : retourne `true` quand un jour doit être désactivé. S'ajoute aux règles `min` et `max`. Une date refusée par le prédicat, même saisie à la main, rend le champ invalide (`stepMismatch`). Propriété JavaScript uniquement, à poser comme propriété et non comme attribut ; réassignez-la pour que le calendrier en tienne compte.

Type ((date: Date) => boolean) | undefined

label

Contenu riche du label (remplace le prop `label`).

after-label

Éléments après le label (bouton d'aide, tooltip…).

hint

Texte d'aide persistant (format attendu, plage min/max si définie). Lié via aria-describedby. Un contenu personnalisé remplace entièrement le texte par défaut, y compris la mention de la plage — à répéter manuellement si nécessaire.

error

Message d'erreur de l'application. Déclenche l'état has-error, et est lié à l'input par aria-describedby.

today-label

Contenu riche du bouton « Aujourd'hui » (icône + texte, remplace le texte traduit par défaut).

close-label

Contenu riche du bouton « Fermer » (icône + texte, remplace le texte traduit par défaut).

input

Natif, sur l'hôte, une fois `value` mise à jour par l'utilisateur (sélection calendrier ou validation de la saisie).

change

Natif, juste après `input`.

ar-datepicker-input-changedetail : { id: string | undefined, value: string | null, valueAsDate: Date | null, valid: boolean }

Valeur commitée (blur ou sélection calendrier).

ar-datepicker-input-completedetail : { id: string | undefined, value: string | null, valueAsDate: Date | null, valid: boolean }

Saisie complète au format attendu. `detail.valid` indique s'il s'agit d'une date plausible (pas le 32/01/2026).

ar-datepicker-showannulabledetail : { id: string | undefined }

Avant ouverture du popover.

ar-datepicker-showndetail : { id: string | undefined }

Après ouverture.

ar-datepicker-hideannulabledetail : { id: string | undefined }

Avant fermeture.

ar-datepicker-hiddendetail : { id: string | undefined }

Après fermeture.

ar-datepicker-view-changedetail : { id: string | undefined, year: number, month: number }

Le mois affiché change (navigation) ou le calendrier s'ouvre ; `month` va de 1 à 12.

checkValidity()retour : boolean

Renvoie `true` si le champ est valide ; émet `invalid` sinon.

reportValidity()retour : boolean

Comme `checkValidity()`, et affiche le message de validation du navigateur.

setCustomValidity()message: stringretour : void

Pose une erreur de validation personnalisée (par exemple une erreur de serveur). Elle persiste, comme sur un `<input>` natif, jusqu'à `setCustomValidity('')`, y compris après `form.reset()` et après une nouvelle saisie.

Personnalisation

Lien direct vers cette section

CSS Parts 23

CSS Custom States 9

CSS Custom Properties 33

Utilisez ::part(name) pour styler ces éléments depuis l'extérieur.
Certaines parts indiquent un rôle transverse, partagé avec d'autres composants — voir Personnalisation avancée.

datepicker

Racine du composant.

input

Le champ texte.

field

Porté par `input` : élément qui reçoit une saisie. Sous-rôle standard de `field` (avec `select`, cf. ar-pagination), réutilisable par tout futur composant avec un champ texte.

trigger

Le bouton d'ouverture du calendrier.

panel

Le popover flottant.

header

En-tête du calendrier (navigation).

nav-button

Tous les boutons de navigation (ciblage groupé).

prev-year

Bouton année précédente.

prev-month

Bouton mois précédent.

next-month

Bouton mois suivant.

next-year

Bouton année suivante.

grid

La grille calendrier.

weekday

Les cellules d'en-tête de colonne (abréviations de jours).

label

L'élément label.

hint

Le texte d'aide sous l'input.

error

Le message d'erreur sous l'input.

day

Les boutons jours.

control

Porté par `day` : élément interactif générique.

footer

Pied du calendrier.

footer-button

Tous les boutons du footer (ciblage groupé).

today-button

Bouton « Aujourd'hui ».

close-button

Bouton « Fermer ».

action-button

Porté par les 4 boutons de navigation (`nav-button`) et les 2 boutons du footer (`footer-button`) : bouton qui déclenche une action ponctuelle.

Utilisez le sélecteur :state(name) sur le tag pour styler ce composant en fonction de son état.
Composable avec ::part() pour cibler un élément interne (ar-datepicker:state(name)::part(x)).
Sous Chrome et Edge 125, l'état est exposé avec le préfixe -- (:--name) : voir Compatibilité.

:state(open)

Le calendrier est ouvert.

:state(disabled)

Le composant est désactivé.

:state(readonly)

Le composant est en lecture seule.

:state(has-error)

Le slot `error` est rempli : l'application affiche une erreur. Indépendant de la validité du champ (voir `user-invalid`).

:state(pending)

L'application a posé l'attribut `pending` : une réponse est attendue.

:state(required)

Le champ est obligatoire (`required`).

:state(optional)

Le champ n'est pas obligatoire.

:state(user-invalid)

Le champ est invalide après une saisie validée par l'utilisateur (sélection dans le calendrier, saisie puis perte de focus), une tentative de soumission ou `reportValidity()`. Jamais posé par une valeur venant de l'application ; retiré par `form.reset()`.

:state(user-valid)

Le champ est valide après la même interaction.

Ce composant utilise un panel flottant, partagé avec d'autres composants, qui expose des custom properties.
Les thèmes peuvent redéfinir ces tokens globalement via :root, ou par composant comme dans cet exemple :

ar-datepicker {
    --ar-panel-radius: 1rem;
}

--ar-panel-bg

Fond du panel partagé. Repli système `Canvas` si aucun thème n'est chargé.

--ar-panel-text

Couleur du texte du panel partagé. Repli système `CanvasText` si aucun thème n'est chargé.

--ar-panel-border-color

Couleur de bordure du panel partagé. Repli système `ButtonBorder` si aucun thème n'est chargé.

--ar-panel-radius

Rayon de bordure du panel partagé.

--ar-panel-shadow

Ombre portée du panel partagé.

--ar-panel-padding

Espacement interne du panel partagé.

--ar-panel-min-width

Largeur minimale du panel partagé.

--ar-panel-max-width

Largeur maximale du panel partagé.

--ar-panel-show-duration

Durée de l'animation d'ouverture du panel partagé (respecte `prefers-reduced-motion`).

Il expose également des custom properties propres, personnalisables directement via :root.

--ar-datepicker-input-max-width

Largeur maximale du champ de saisie. Par défaut, une valeur calculée à partir de la longueur de `format`.

--ar-datepicker-panel-max-width

Largeur maximale du popover (valeur propre, non cascadée depuis --ar-panel-max-width ; repli `25rem` si aucun thème n'est chargé, évite que la grille de ~35 jours s'étale sur toute la largeur de la page).

--ar-datepicker-distance

Espacement entre le trigger et le panel.

--ar-datepicker-offset

Décalage latéral du panel.

--ar-datepicker-nav-button-border-color

Couleur de bordure des boutons nav.

--ar-datepicker-footer-button-border-color

Couleur de bordure des boutons footer.

--ar-datepicker-day-size

Taille des cellules jour (repli `2.5rem` si aucun thème n'est chargé — cible tactile WCAG 2.5.8 Target Size Minimum, la grille utilisant border-collapse: collapse qui supprime l'espacement natif du <table>).

--ar-datepicker-day-border-color

Couleur de bordure par défaut des cellules jour. Repli `transparent` si aucun thème n'est chargé (aucune bordure par défaut).

--ar-datepicker-day-color

Couleur du texte des cellules jour (cascade vers --ar-color-text).

--ar-datepicker-day-bg

Fond des cellules jour.

--ar-datepicker-day-other-month-color

Couleur des jours hors du mois affiché. Repli `GrayText` si aucun thème n'est chargé.

--ar-datepicker-day-today-bg

Fond du jour actuel.

--ar-datepicker-day-today-color

Couleur texte du jour actuel.

--ar-datepicker-day-today-border

Couleur de bordure du jour actuel. Repli `GrayText` si aucun thème n'est chargé (garde une distinction visible du reste de la grille).

--ar-datepicker-day-hover-bg

Fond au survol d'un jour. Repli `ButtonFace` si aucun thème n'est chargé.

--ar-datepicker-day-hover-color

Couleur texte au survol d'un jour. Repli `ButtonText` si aucun thème n'est chargé.

--ar-datepicker-day-focus-ring-color

Couleur du focus ring des jours. Repli `ButtonText` si aucun thème n'est chargé (WCAG 2.4.7).

--ar-datepicker-day-focus-ring-width

Épaisseur du focus ring des jours.

--ar-datepicker-day-focus-ring-offset

Décalage du focus ring des jours.

--ar-datepicker-day-focus-border-color

Couleur de bordure de la cellule jour en focus (roving tabindex). Purement cosmétique : l'indicateur de focus WCAG 2.4.7 est garanti indépendamment par --ar-datepicker-day-focus-ring-color/-width/-offset. Repli transparent si aucun thème n'est chargé.

--ar-datepicker-day-selected-bg

Fond du jour sélectionné. Repli `Highlight` si aucun thème n'est chargé (sinon indiscernable des jours non sélectionnés).

--ar-datepicker-day-selected-color

Couleur texte du jour sélectionné. Repli `HighlightText` si aucun thème n'est chargé.

--ar-datepicker-nav-button-focus-ring-color

Couleur de l'anneau de focus des boutons de navigation (cascade vers --ar-focus-ring-color). Repli `ButtonText` si aucun thème n'est chargé (WCAG 2.4.7).

--ar-datepicker-footer-button-focus-ring-color

Couleur de l'anneau de focus des boutons du footer (cascade vers --ar-focus-ring-color). Repli `ButtonText` si aucun thème n'est chargé (WCAG 2.4.7).

Traduction

Lien direct vers cette section

La langue de ce composant suit l'attribut lang de la page (<html lang>).
Vous pouvez appliquer une langue différente à une instance donnée en posant l'attribut lang directement dessus.
Voir la page Traductions pour le détail du mécanisme et la liste des traductions disponibles.

lang étant un attribut HTML natif, il n'apparaît pas dans le tableau « Attributs & Propriétés ».