Source

Listes déroulantes

Basculez les superpositions contextuelles pour afficher des listes de liens et plus encore avec le plugin déroulant Bootstrap.

Aperçu

Les listes déroulantes sont des superpositions contextuelles basculables pour afficher des listes de liens et plus encore. Ils sont rendus interactifs avec le plugin JavaScript déroulant Bootstrap inclus. Ils sont activés en cliquant, pas en survolant ; il s'agit d'une décision de conception intentionnelle.

Les listes déroulantes sont construites sur une bibliothèque tierce, Popper.js , qui fournit un positionnement dynamique et une détection de la fenêtre d'affichage. Assurez-vous d'inclure popper.min.js avant le JavaScript de Bootstrap ou utilisez bootstrap.bundle.min.js/ bootstrap.bundle.jsqui contient Popper.js. Popper.js n'est pas utilisé pour positionner les listes déroulantes dans les barres de navigation, car le positionnement dynamique n'est pas requis.

Si vous construisez notre JavaScript à partir de la source, cela nécessiteutil.js .

Accessibilité

La norme WAI ARIA définit un role="menu"widget réel , mais cela est spécifique aux menus de type application qui déclenchent des actions ou des fonctions. Les menus ARIA ne peuvent contenir que des éléments de menu, des éléments de menu de cases à cocher, des éléments de menu de boutons radio, des groupes de boutons radio et des sous-menus.

Les listes déroulantes de Bootstrap, en revanche, sont conçues pour être génériques et applicables à une variété de situations et de structures de balisage. Par exemple, il est possible de créer des listes déroulantes contenant des entrées supplémentaires et des contrôles de formulaire, tels que des champs de recherche ou des formulaires de connexion. Pour cette raison, Bootstrap n'attend (ni n'ajoute automatiquement) aucun des attributs roleet requis pour les vrais menus ARIA . Les auteurs devront inclure eux-mêmes ces attributs plus spécifiques.aria-

Cependant, Bootstrap ajoute une prise en charge intégrée pour la plupart des interactions de menu clavier standard, telles que la possibilité de parcourir des .dropdown-iteméléments individuels à l'aide des touches du curseur et de fermer le menu avec la ESCtouche .

Exemples

Enveloppez la bascule de la liste déroulante (votre bouton ou lien) et le menu déroulant dans .dropdown, ou un autre élément qui déclare position: relative;. Les listes déroulantes peuvent être déclenchées à partir de <a>ou d' <button>éléments pour mieux répondre à vos besoins potentiels.

Listes déroulantes à un seul bouton

Tout single .btnpeut être transformé en une bascule déroulante avec quelques modifications de balisage. Voici comment vous pouvez les utiliser avec l'un ou l'autre des <button>éléments :

<div class="dropdown">
  <button class="btn btn-secondary dropdown-toggle" type="button" id="dropdownMenuButton" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    Dropdown button
  </button>
  <div class="dropdown-menu" aria-labelledby="dropdownMenuButton">
    <a class="dropdown-item" href="#">Action</a>
    <a class="dropdown-item" href="#">Another action</a>
    <a class="dropdown-item" href="#">Something else here</a>
  </div>
</div>

Et avec <a>des éléments :

<div class="dropdown show">
  <a class="btn btn-secondary dropdown-toggle" href="#" role="button" id="dropdownMenuLink" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    Dropdown link
  </a>

  <div class="dropdown-menu" aria-labelledby="dropdownMenuLink">
    <a class="dropdown-item" href="#">Action</a>
    <a class="dropdown-item" href="#">Another action</a>
    <a class="dropdown-item" href="#">Something else here</a>
  </div>
</div>

La meilleure partie est que vous pouvez également le faire avec n'importe quelle variante de bouton :

<!-- Example single danger button -->
<div class="btn-group">
  <button type="button" class="btn btn-danger dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    Action
  </button>
  <div class="dropdown-menu">
    <a class="dropdown-item" href="#">Action</a>
    <a class="dropdown-item" href="#">Another action</a>
    <a class="dropdown-item" href="#">Something else here</a>
    <div class="dropdown-divider"></div>
    <a class="dropdown-item" href="#">Separated link</a>
  </div>
</div>

Listes déroulantes des boutons de fractionnement

De même, créez des listes déroulantes de boutons divisés avec pratiquement le même balisage que les listes déroulantes à un seul bouton, mais avec l'ajout d' .dropdown-toggle-splitun espacement approprié autour du curseur déroulant.

Nous utilisons cette classe supplémentaire pour réduire l'horizontale paddingde chaque côté du caret de 25 % et supprimer ce margin-leftqui est ajouté pour les listes déroulantes de boutons régulières. Ces modifications supplémentaires maintiennent le caret centré dans le bouton partagé et fournissent une zone de frappe de taille plus appropriée à côté du bouton principal.

<!-- Example split danger button -->
<div class="btn-group">
  <button type="button" class="btn btn-danger">Action</button>
  <button type="button" class="btn btn-danger dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    <span class="sr-only">Toggle Dropdown</span>
  </button>
  <div class="dropdown-menu">
    <a class="dropdown-item" href="#">Action</a>
    <a class="dropdown-item" href="#">Another action</a>
    <a class="dropdown-item" href="#">Something else here</a>
    <div class="dropdown-divider"></div>
    <a class="dropdown-item" href="#">Separated link</a>
  </div>
</div>

Dimensionnement

Les listes déroulantes de boutons fonctionnent avec des boutons de toutes tailles, y compris les boutons déroulants par défaut et divisés.

<!-- Large button groups (default and split) -->
<div class="btn-group">
  <button class="btn btn-secondary btn-lg dropdown-toggle" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    Large button
  </button>
  <div class="dropdown-menu">
    ...
  </div>
</div>
<div class="btn-group">
  <button class="btn btn-secondary btn-lg" type="button">
    Large split button
  </button>
  <button type="button" class="btn btn-lg btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    <span class="sr-only">Toggle Dropdown</span>
  </button>
  <div class="dropdown-menu">
    ...
  </div>
</div>

<!-- Small button groups (default and split) -->
<div class="btn-group">
  <button class="btn btn-secondary btn-sm dropdown-toggle" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    Small button
  </button>
  <div class="dropdown-menu">
    ...
  </div>
</div>
<div class="btn-group">
  <button class="btn btn-secondary btn-sm" type="button">
    Small split button
  </button>
  <button type="button" class="btn btn-sm btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    <span class="sr-only">Toggle Dropdown</span>
  </button>
  <div class="dropdown-menu">
    ...
  </div>
</div>

Variation de chute

Déclenchez des menus déroulants au-dessus des éléments en ajoutant .dropupà l'élément parent.

<!-- Default dropup button -->
<div class="btn-group dropup">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    Dropup
  </button>
  <div class="dropdown-menu">
    <!-- Dropdown menu links -->
  </div>
</div>

<!-- Split dropup button -->
<div class="btn-group dropup">
  <button type="button" class="btn btn-secondary">
    Split dropup
  </button>
  <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    <span class="sr-only">Toggle Dropdown</span>
  </button>
  <div class="dropdown-menu">
    <!-- Dropdown menu links -->
  </div>
</div>

Variante Dropright

Déclenchez des menus déroulants à droite des éléments en ajoutant .droprightà l'élément parent.

<!-- Default dropright button -->
<div class="btn-group dropright">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    Dropright
  </button>
  <div class="dropdown-menu">
    <!-- Dropdown menu links -->
  </div>
</div>

<!-- Split dropright button -->
<div class="btn-group dropright">
  <button type="button" class="btn btn-secondary">
    Split dropright
  </button>
  <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    <span class="sr-only">Toggle Dropright</span>
  </button>
  <div class="dropdown-menu">
    <!-- Dropdown menu links -->
  </div>
</div>

Variation Dropleft

Déclenchez des menus déroulants à gauche des éléments en ajoutant .dropleftà l'élément parent.

<!-- Default dropleft button -->
<div class="btn-group dropleft">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    Dropleft
  </button>
  <div class="dropdown-menu">
    <!-- Dropdown menu links -->
  </div>
</div>

<!-- Split dropleft button -->
<div class="btn-group">
  <div class="btn-group dropleft" role="group">
    <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
      <span class="sr-only">Toggle Dropleft</span>
    </button>
    <div class="dropdown-menu">
      <!-- Dropdown menu links -->
    </div>
  </div>
  <button type="button" class="btn btn-secondary">
    Split dropleft
  </button>
</div>

Historiquement, le contenu du menu déroulant devait être des liens, mais ce n'est plus le cas avec la v4. Maintenant, vous pouvez éventuellement utiliser des <button>éléments dans vos listes déroulantes au lieu de simplement <a>s.

<div class="dropdown">
  <button class="btn btn-secondary dropdown-toggle" type="button" id="dropdownMenu2" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    Dropdown
  </button>
  <div class="dropdown-menu" aria-labelledby="dropdownMenu2">
    <button class="dropdown-item" type="button">Action</button>
    <button class="dropdown-item" type="button">Another action</button>
    <button class="dropdown-item" type="button">Something else here</button>
  </div>
</div>

Par défaut, un menu déroulant est automatiquement positionné à 100 % du haut et le long du côté gauche de son parent. Ajouter .dropdown-menu-rightà a .dropdown-menupour aligner à droite le menu déroulant.

La tête haute! Les dropdowns sont positionnés grâce à Popper.js (sauf lorsqu'ils sont contenus dans une navbar).

<div class="btn-group">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    Right-aligned menu
  </button>
  <div class="dropdown-menu dropdown-menu-right">
    <button class="dropdown-item" type="button">Action</button>
    <button class="dropdown-item" type="button">Another action</button>
    <button class="dropdown-item" type="button">Something else here</button>
  </div>
</div>

Ajoutez un en-tête pour étiqueter les sections d'actions dans n'importe quel menu déroulant.

<div class="dropdown-menu">
  <h6 class="dropdown-header">Dropdown header</h6>
  <a class="dropdown-item" href="#">Action</a>
  <a class="dropdown-item" href="#">Another action</a>
</div>

Séparez les groupes d'éléments de menu associés avec un séparateur.

<div class="dropdown-menu">
  <a class="dropdown-item" href="#">Action</a>
  <a class="dropdown-item" href="#">Another action</a>
  <a class="dropdown-item" href="#">Something else here</a>
  <div class="dropdown-divider"></div>
  <a class="dropdown-item" href="#">Separated link</a>
</div>

Placez un formulaire dans un menu déroulant ou transformez-le en menu déroulant et utilisez des utilitaires de marge ou de remplissage pour lui donner l'espace négatif dont vous avez besoin.

<div class="dropdown-menu">
  <form class="px-4 py-3">
    <div class="form-group">
      <label for="exampleDropdownFormEmail1">Email address</label>
      <input type="email" class="form-control" id="exampleDropdownFormEmail1" placeholder="[email protected]">
    </div>
    <div class="form-group">
      <label for="exampleDropdownFormPassword1">Password</label>
      <input type="password" class="form-control" id="exampleDropdownFormPassword1" placeholder="Password">
    </div>
    <div class="form-check">
      <input type="checkbox" class="form-check-input" id="dropdownCheck">
      <label class="form-check-label" for="dropdownCheck">
        Remember me
      </label>
    </div>
    <button type="submit" class="btn btn-primary">Sign in</button>
  </form>
  <div class="dropdown-divider"></div>
  <a class="dropdown-item" href="#">New around here? Sign up</a>
  <a class="dropdown-item" href="#">Forgot password?</a>
</div>

<form class="dropdown-menu p-4">
  <div class="form-group">
    <label for="exampleDropdownFormEmail2">Email address</label>
    <input type="email" class="form-control" id="exampleDropdownFormEmail2" placeholder="[email protected]">
  </div>
  <div class="form-group">
    <label for="exampleDropdownFormPassword2">Password</label>
    <input type="password" class="form-control" id="exampleDropdownFormPassword2" placeholder="Password">
  </div>
  <div class="form-check">
    <input type="checkbox" class="form-check-input" id="dropdownCheck2">
    <label class="form-check-label" for="dropdownCheck2">
      Remember me
    </label>
  </div>
  <button type="submit" class="btn btn-primary">Sign in</button>
</form>

Ajoutez .activeaux éléments dans la liste déroulante pour les définir comme actifs .

<div class="dropdown-menu">
  <a class="dropdown-item" href="#">Regular link</a>
  <a class="dropdown-item active" href="#">Active link</a>
  <a class="dropdown-item" href="#">Another link</a>
</div>

Ajoutez .disableddes éléments dans la liste déroulante pour les définir comme désactivés .

<div class="dropdown-menu">
  <a class="dropdown-item" href="#">Regular link</a>
  <a class="dropdown-item disabled" href="#">Disabled link</a>
  <a class="dropdown-item" href="#">Another link</a>
</div>

Usage

Via les attributs de données ou JavaScript, le plug-in déroulant bascule le contenu masqué (menus déroulants) en basculant la .showclasse sur l'élément de la liste parent. L' data-toggle="dropdown"attribut est utilisé pour fermer les menus déroulants au niveau de l'application, c'est donc une bonne idée de toujours l'utiliser.

Sur les appareils tactiles, l'ouverture d'une liste déroulante ajoute des gestionnaires vides ( $.noop) mouseoveraux enfants immédiats de l' <body>élément. Ce piratage, certes laid, est nécessaire pour contourner une bizarrerie dans la délégation d'événements d'iOS , ce qui empêcherait autrement un appui n'importe où en dehors de la liste déroulante de déclencher le code qui ferme la liste déroulante. Une fois la liste déroulante fermée, ces mouseovergestionnaires vides supplémentaires sont supprimés.

Via les attributs de données

Ajouter data-toggle="dropdown"à un lien ou à un bouton pour basculer vers une liste déroulante.

<div class="dropdown">
  <button id="dLabel" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    Dropdown trigger
  </button>
  <div class="dropdown-menu" aria-labelledby="dLabel">
    ...
  </div>
</div>

Via Javascript

Appelez les listes déroulantes via JavaScript :

$('.dropdown-toggle').dropdown()

`data-toggle="dropdown"`encore nécessaire

Que vous appeliez votre liste déroulante via JavaScript ou que vous utilisiez à la place l'API de données, data-toggle="dropdown"il doit toujours être présent sur l'élément déclencheur de la liste déroulante.

Choix

Les options peuvent être transmises via des attributs de données ou JavaScript. Pour les attributs de données, ajoutez le nom de l'option à data-, comme dans data-offset="".

Nom	Taper	Défaut	La description
décalage	nombre \| chaîne \| fonction	0	Décalage de la liste déroulante par rapport à sa cible. Pour plus d'informations, reportez-vous à la documentation offset de Popper.js .
retourner	booléen	vrai	Autoriser Dropdown à basculer en cas de chevauchement sur l'élément de référence. Pour plus d'informations, consultez les flip docs de Popper.js .
frontière	chaîne \| élément	'scrollParent'	Limite de contrainte de débordement du menu déroulant. Accepte les valeurs de `'viewport'`, `'window'`, `'scrollParent'`ou une référence HTMLElement (JavaScript uniquement). Pour plus d'informations, reportez-vous à la documentation preventOverflow de Popper.js .

Notez que lorsque boundaryest défini sur une valeur autre que 'scrollParent', le style position: staticest appliqué au .dropdownconteneur.

Méthodes

Méthode	La description
`$().dropdown('toggle')`	Bascule le menu déroulant d'une barre de navigation donnée ou d'une navigation par onglets.
`$().dropdown('update')`	Met à jour la position de la liste déroulante d'un élément.
`$().dropdown('dispose')`	Détruit la liste déroulante d'un élément.

Événements

Tous les événements de liste déroulante sont déclenchés sur l' .dropdown-menuélément parent de et ont une relatedTargetpropriété, dont la valeur est l'élément d'ancrage basculant.

Événement	La description
`show.bs.dropdown`	Cet événement se déclenche immédiatement lorsque la méthode d'instance show est appelée.
`shown.bs.dropdown`	Cet événement est déclenché lorsque la liste déroulante a été rendue visible à l'utilisateur (attendra que les transitions CSS se terminent).
`hide.bs.dropdown`	Cet événement est déclenché immédiatement lorsque la méthode d'instance de masquage a été appelée.
`hidden.bs.dropdown`	Cet événement est déclenché lorsque la liste déroulante a fini d'être masquée pour l'utilisateur (attendra que les transitions CSS se terminent).

$('#myDropdown').on('show.bs.dropdown', function () {
  // do something…
})

Listes déroulantes

Aperçu

Accessibilité

Exemples

Listes déroulantes à un seul bouton

Listes déroulantes des boutons de fractionnement

Dimensionnement

Variation de chute

Variante Dropright

Variation Dropleft

Éléments de menu

Alignement des menus

En-têtes de menu

Séparateurs de menu

Formulaires de menu

Éléments de menu actifs

Éléments de menu désactivés

Usage

Via les attributs de données

Via Javascript

`data-toggle="dropdown"`encore nécessaire

Choix

Méthodes

Événements

Listes déroulantes

Aperçu

Accessibilité

Exemples

Listes déroulantes à un seul bouton

Listes déroulantes des boutons de fractionnement

Dimensionnement

Variation de chute

Variante Dropright

Variation Dropleft

Éléments de menu

Alignement des menus

En-têtes de menu

En-tête déroulant

Séparateurs de menu

Formulaires de menu

Éléments de menu actifs

Éléments de menu désactivés

Usage

Via les attributs de données

Via Javascript

data-toggle="dropdown"encore nécessaire

Choix

Méthodes

Événements

`data-toggle="dropdown"`encore nécessaire