Affiche un panneau contextuel déclenché par un bouton, positionné automatiquement autour de lui. À utiliser pour des menus d'actions, des filtres, ou tout contenu additionnel qui ne justifie pas un dialog.
aria-haspopup="true" et aria-expanded synchronisé à l’état ouvert/fermé —
WCAG 4.1.2 (ouvre dans un nouvel onglet)ar-dropdown-item), le panel reçoit role="menu" et chaque enfant focusable reçoit role="menuitem".↑ ↓ Home End pour déplacer le focus, Escape et Tab pour fermer —
WCAG 2.1.1 (ouvre dans un nouvel onglet)popover="auto") : un clic hors du panel ferme automatiquement.prefers-reduced-motion: reduce est actif.aria-label si le trigger ne contient que de l’iconographie.ar-dropdown-item. Les éléments sans ar-dropdown-item dans un panel menu ne reçoivent pas role="menuitem" et sortent de la navigation clavier.ar-dropdown[disabled] et aria-disabled="true" sur le trigger. L’attribut disabled du composant bloque la logique JS ; aria-disabled="true" (à la place du disabled natif) maintient le bouton dans l’ordre de tabulation pour que les technologies d’assistance puissent annoncer l’état et lire une éventuelle raison via aria-describedby.En mode menu, activer un item (clic, Entrée ou Espace) émet ar-dropdown-select, puis ferme le menu. detail.item est l’ar-dropdown-item activé. Annulez l’événement pour garder le menu ouvert :
dropdown.addEventListener('ar-dropdown-select', (e) => {
if (e.detail.item.hasAttribute('data-keep-open')) e.preventDefault();
});
Les exemples de cette page sont affichés avec le thème neutre du starter-kit.
Avec des ar-dropdown-item, le panel reçoit automatiquement role="menu" et la navigation clavier est activée (↑↓ Home End Escape Tab).
<ar-dropdown>
<button class="ar-btn ar-btn-secondary" slot="trigger">Actions ▾</button>
<ar-dropdown-item><button>Modifier</button></ar-dropdown-item>
<ar-dropdown-item><button>Dupliquer</button></ar-dropdown-item>
<ar-dropdown-item><button>Supprimer</button></ar-dropdown-item>
</ar-dropdown>Un `<hr>` placé entre des `ar-dropdown-item` reçoit automatiquement `role="separator"`. Stylez-le avec votre propre CSS — ici via une variable CSS du token de bordure.
<ar-dropdown>
<button class="ar-btn ar-btn-secondary" slot="trigger">Actions ▾</button>
<ar-dropdown-item><button>Modifier</button></ar-dropdown-item>
<ar-dropdown-item><button>Dupliquer</button></ar-dropdown-item>
<hr style="border:none;border-top:1px solid var(--ar-color-border,#e5e7eb);margin:.25rem 0;">
<ar-dropdown-item><button>Supprimer</button></ar-dropdown-item>
</ar-dropdown>Sans ar-dropdown-item, le panel est un conteneur libre — aucun role ni navigation clavier n'est ajouté.
Contenu libre — formulaire, liste, texte…
<ar-dropdown>
<button class="ar-btn ar-btn-secondary" slot="trigger">Options ▾</button>
<p style="padding: .5rem .75rem; margin: 0; color: var(--ar-color-text, inherit);">Contenu libre — formulaire, liste, texte…</p>
</ar-dropdown>Le panel s'ouvre au-dessus du trigger, aligné à droite.
<ar-dropdown placement="top-end">
<button class="ar-btn ar-btn-secondary" slot="trigger">Placement ▾</button>
<ar-dropdown-item><button>Item 1</button></ar-dropdown-item>
<ar-dropdown-item><button>Item 2</button></ar-dropdown-item>
</ar-dropdown>Espacement en pixels entre le trigger et le panel (axe principal), piloté par la custom property CSS `--ar-dropdown-distance` (défaut : `var(--ar-anchor-distance)`, 4px).
<ar-dropdown style="--ar-dropdown-distance: 16px">
<button class="ar-btn ar-btn-secondary" slot="trigger">Distance 16px ▾</button>
<ar-dropdown-item><button>Item 1</button></ar-dropdown-item>
<ar-dropdown-item><button>Item 2</button></ar-dropdown-item>
<ar-dropdown-item><button>Item 3</button></ar-dropdown-item>
</ar-dropdown>Décalage latéral en pixels du panel par rapport au trigger (axe transversal), piloté par la custom property CSS `--ar-dropdown-offset` (défaut : `var(--ar-anchor-offset)`, 0).
<ar-dropdown style="--ar-dropdown-offset: 32px">
<button class="ar-btn ar-btn-secondary" slot="trigger">Offset 32px ▾</button>
<ar-dropdown-item><button>Item 1</button></ar-dropdown-item>
<ar-dropdown-item><button>Item 2</button></ar-dropdown-item>
<ar-dropdown-item><button>Item 3</button></ar-dropdown-item>
</ar-dropdown>L'attribut `trigger-id` accepte l'ID d'un élément déclencheur situé en dehors du composant. Utile pour les boutons dans une barre d'outils ou une autre zone de la page.
<button class="ar-btn ar-btn-secondary" id="ar-doc-ext-trigger">Trigger externe ▾</button>
<ar-dropdown trigger-id="ar-doc-ext-trigger">
<ar-dropdown-item><button>Modifier</button></ar-dropdown-item>
<ar-dropdown-item><button>Dupliquer</button></ar-dropdown-item>
<ar-dropdown-item><button>Supprimer</button></ar-dropdown-item>
</ar-dropdown>Combine `disabled` sur `ar-dropdown` et `aria-disabled="true"` sur le trigger — voir la section Accessibilité pour le détail. WCAG exempte les composants désactivés des exigences de contraste : `opacity: .5` est donc conforme.
Droits insuffisants pour effectuer cette action.
<ar-dropdown disabled>
<button
class="ar-btn ar-btn-secondary"
slot="trigger"
aria-disabled="true"
aria-describedby="disabled-reason"
style="opacity:.5;cursor:not-allowed;"
>Actions ▾</button>
<ar-dropdown-item><button>Item 1</button></ar-dropdown-item>
</ar-dropdown>
<p id="disabled-reason" style="margin-top:.5rem;font-size:.875rem;color:var(--ar-color-text-muted,#6b7280);">
Droits insuffisants pour effectuer cette action.
</p>Manipulez les attributs pour voir le code et la preview se mettre à jour.
<ar-dropdown>
<button class="ar-btn ar-btn-secondary" slot="trigger">Actions ▾</button>
<ar-dropdown-item><button>Modifier</button></ar-dropdown-item>
<ar-dropdown-item><button>Dupliquer</button></ar-dropdown-item>
<ar-dropdown-item><button>Supprimer</button></ar-dropdown-item>
</ar-dropdown>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.
Importez ce composant depuis le CDN.
<script type="module" src="https://unpkg.com/@ariane-ui/core/dist/components/dropdown/index.js"></script>Après avoir installé le paquet via npm, vous pouvez importer le composant ainsi :
import '@ariane-ui/core/dist/components/dropdown/index.js';Ouvre ou ferme le panel.
Placement du panel par rapport au trigger (Floating UI).
Désactive le composant — le trigger ne répond plus aux clics.
Désactive le verrouillage du scroll des conteneurs ancêtres à l'ouverture. Par défaut, le scroll est bloqué comme le fait le `<select>` natif. À activer uniquement si le jitter de positionnement est acceptable.
ID d'un élément déclencheur externe (light DOM). Quand défini, le slot `trigger` est ignoré.
Le bouton déclencheur (ignoré si `trigger-id` est défini).
Contenu du panel (libre ou ar-dropdown-item pour le mode menu).
detail : { id: string | undefined }Émis avant l'ouverture.
detail : { id: string | undefined }Émis si ar-dropdown-show est annulé.
detail : { id: string | undefined }Émis après l'ouverture.
detail : { id: string | undefined }Émis avant la fermeture.
detail : { id: string | undefined }Émis si ar-dropdown-hide est annulé.
detail : { id: string | undefined }Émis après la fermeture.
detail : { id: string | undefined, item: ArDropdownItem }En mode menu, à l'activation d'un item (clic, Entrée, Espace) ; `item` est l'`ar-dropdown-item` activé. Sans annulation, le menu se ferme.
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.
Le panel flottant.
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-dropdown:state(name)::part(x)).
Sous Chrome et Edge 125, l'état est exposé avec le préfixe -- (:--name) : voir Compatibilité.
Le panel est ouvert.
Le composant est désactivé.
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-dropdown {
--ar-panel-radius: 1rem;
}Fond du panel partagé. Repli système `Canvas` si aucun thème n'est chargé.
Couleur du texte du panel partagé. Repli système `CanvasText` si aucun thème n'est chargé.
Couleur de bordure du panel partagé. Repli système `ButtonBorder` si aucun thème n'est chargé.
Rayon de bordure du panel partagé.
Ombre portée du panel partagé.
Espacement interne du panel partagé.
Largeur minimale du panel partagé.
Largeur maximale du panel partagé.
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.
Espacement entre le trigger et le panel (axe principal).
Décalage latéral du panel (axe transversal).