Listas suspensas

Alterne sobreposições contextuais para exibir listas de links e muito mais com o plug-in suspenso Bootstrap.

Nesta página

Visão geral

As listas suspensas são sobreposições contextuais alternáveis para exibir listas de links e muito mais. Eles são feitos interativos com o plug-in de JavaScript suspenso Bootstrap incluído. Eles são alternados clicando, não passando o mouse; esta é uma decisão de projeto intencional .

Os dropdowns são construídos em uma biblioteca de terceiros, Popper , que fornece posicionamento dinâmico e detecção de viewport. Certifique-se de incluir popper.min.js antes do JavaScript do Bootstrap ou use bootstrap.bundle.min.js/ bootstrap.bundle.jsque contém Popper. Popper não é usado para posicionar dropdowns em navbars, pois o posicionamento dinâmico não é necessário.

Acessibilidade

O padrão WAI ARIA define um role="menu"widget real , mas isso é específico para menus semelhantes a aplicativos que acionam ações ou funções. Os menus ARIA podem conter apenas itens de menu, itens de menu de caixa de seleção, itens de menu de botão de opção, grupos de botões de opção e submenus.

As listas suspensas do Bootstrap, por outro lado, são projetadas para serem genéricas e aplicáveis a uma variedade de situações e estruturas de marcação. Por exemplo, é possível criar dropdowns que contenham entradas e controles de formulário adicionais, como campos de pesquisa ou formulários de login. Por esse motivo, o Bootstrap não espera (nem adiciona automaticamente) nenhum dos atributos rolee necessários para menus ARIA verdadeiros. Os autores terão que incluir esses atributos mais específicos.aria-

No entanto, o Bootstrap adiciona suporte interno para a maioria das interações de menu de teclado padrão, como a capacidade de mover .dropdown-itemelementos individuais usando as teclas do cursor e fechar o menu com a ESCtecla.

Exemplos

Enrole a alternância do menu suspenso (seu botão ou link) e o menu suspenso dentro de .dropdown, ou outro elemento que declare position: relative;. As listas suspensas podem ser acionadas a partir de <a>elementos <button>para melhor atender às suas necessidades potenciais. Os exemplos mostrados aqui usam <ul>elementos semânticos quando apropriado, mas a marcação personalizada é suportada.

Botão único

Qualquer single .btnpode ser transformado em uma alternância suspensa com algumas alterações de marcação. Veja como você pode colocá-los para funcionar com qualquer um dos <button>elementos:

html

<div class="dropdown">
  <button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false">
    Dropdown button
  </button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Action</a></li>
    <li><a class="dropdown-item" href="#">Another action</a></li>
    <li><a class="dropdown-item" href="#">Something else here</a></li>
  </ul>
</div>

E com <a>elementos:

html

<div class="dropdown">
  <a class="btn btn-secondary dropdown-toggle" href="#" role="button" data-bs-toggle="dropdown" aria-expanded="false">
    Dropdown link
  </a>

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

A melhor parte é que você também pode fazer isso com qualquer variante de botão:

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

Botão de divisão

Da mesma forma, crie listas suspensas de botão dividido com praticamente a mesma marcação das listas suspensas de botão único, mas com a adição de .dropdown-toggle-splitespaçamento adequado ao redor do cursor suspenso.

Usamos essa classe extra para reduzir a horizontal paddingem ambos os lados do cursor em 25% e remover o margin-leftque é adicionado para menus suspensos de botões regulares. Essas alterações extras mantêm o cursor centralizado no botão de divisão e fornecem uma área de acerto de tamanho mais apropriado ao lado do botão 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-bs-toggle="dropdown" aria-expanded="false">
    <span class="visually-hidden">Toggle Dropdown</span>
  </button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Action</a></li>
    <li><a class="dropdown-item" href="#">Another action</a></li>
    <li><a class="dropdown-item" href="#">Something else here</a></li>
    <li><hr class="dropdown-divider"></li>
    <li><a class="dropdown-item" href="#">Separated link</a></li>
  </ul>
</div>

Dimensionamento

Os menus suspensos de botão funcionam com botões de todos os tamanhos, incluindo botões suspensos padrão e divididos.

<!-- Large button groups (default and split) -->
<div class="btn-group">
  <button class="btn btn-secondary btn-lg dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false">
    Large button
  </button>
  <ul class="dropdown-menu">
    ...
  </ul>
</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-bs-toggle="dropdown" aria-expanded="false">
    <span class="visually-hidden">Toggle Dropdown</span>
  </button>
  <ul class="dropdown-menu">
    ...
  </ul>
</div>

<div class="btn-group">
  <button class="btn btn-secondary btn-sm dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false">
    Small button
  </button>
  <ul class="dropdown-menu">
    ...
  </ul>
</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-bs-toggle="dropdown" aria-expanded="false">
    <span class="visually-hidden">Toggle Dropdown</span>
  </button>
  <ul class="dropdown-menu">
    ...
  </ul>
</div>

Listas suspensas escuras

Opte por menus suspensos mais escuros para corresponder a uma barra de navegação escura ou estilo personalizado adicionando .dropdown-menu-darkem um arquivo .dropdown-menu. Nenhuma alteração é necessária para os itens suspensos.

html

<div class="dropdown">
  <button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false">
    Dropdown button
  </button>
  <ul class="dropdown-menu dropdown-menu-dark">
    <li><a class="dropdown-item active" href="#">Action</a></li>
    <li><a class="dropdown-item" href="#">Another action</a></li>
    <li><a class="dropdown-item" href="#">Something else here</a></li>
    <li><hr class="dropdown-divider"></li>
    <li><a class="dropdown-item" href="#">Separated link</a></li>
  </ul>
</div>

E colocando-o para usar em uma barra de navegação:

html

<nav class="navbar navbar-expand-lg navbar-dark bg-dark">
  <div class="container-fluid">
    <a class="navbar-brand" href="#">Navbar</a>
    <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarNavDarkDropdown" aria-controls="navbarNavDarkDropdown" aria-expanded="false" aria-label="Toggle navigation">
      <span class="navbar-toggler-icon"></span>
    </button>
    <div class="collapse navbar-collapse" id="navbarNavDarkDropdown">
      <ul class="navbar-nav">
        <li class="nav-item dropdown">
          <a class="nav-link dropdown-toggle" href="#" role="button" data-bs-toggle="dropdown" aria-expanded="false">
            Dropdown
          </a>
          <ul class="dropdown-menu dropdown-menu-dark">
            <li><a class="dropdown-item" href="#">Action</a></li>
            <li><a class="dropdown-item" href="#">Another action</a></li>
            <li><a class="dropdown-item" href="#">Something else here</a></li>
          </ul>
        </li>
      </ul>
    </div>
  </div>
</nav>

instruções

RTL

As direções são espelhadas ao usar o Bootstrap no RTL, o que significa .dropstartque aparecerá no lado direito.

Centralizado

Faça o menu suspenso centralizado abaixo da alternância com .dropdown-centero elemento pai.

html

<div class="dropdown-center">
  <button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false">
    Centered dropdown
  </button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Action</a></li>
    <li><a class="dropdown-item" href="#">Action two</a></li>
    <li><a class="dropdown-item" href="#">Action three</a></li>
  </ul>
</div>

Soltar-se

Acione menus suspensos acima dos elementos adicionando .dropupao elemento pai.

<!-- Default dropup button -->
<div class="btn-group dropup">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false">
    Dropup
  </button>
  <ul class="dropdown-menu">
    <!-- Dropdown menu links -->
  </ul>
</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-bs-toggle="dropdown" aria-expanded="false">
    <span class="visually-hidden">Toggle Dropdown</span>
  </button>
  <ul class="dropdown-menu">
    <!-- Dropdown menu links -->
  </ul>
</div>

Dropup centralizado

Torne o menu suspenso centralizado acima da alternância .dropup-centerno elemento pai.

html

<div class="dropup-center dropup">
  <button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false">
    Centered dropup
  </button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Action</a></li>
    <li><a class="dropdown-item" href="#">Action two</a></li>
    <li><a class="dropdown-item" href="#">Action three</a></li>
  </ul>
</div>

Dropend

Acione menus suspensos à direita dos elementos adicionando .dropendao elemento pai.

<!-- Default dropend button -->
<div class="btn-group dropend">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false">
    Dropend
  </button>
  <ul class="dropdown-menu">
    <!-- Dropdown menu links -->
  </ul>
</div>

<!-- Split dropend button -->
<div class="btn-group dropend">
  <button type="button" class="btn btn-secondary">
    Split dropend
  </button>
  <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-bs-toggle="dropdown" aria-expanded="false">
    <span class="visually-hidden">Toggle Dropend</span>
  </button>
  <ul class="dropdown-menu">
    <!-- Dropdown menu links -->
  </ul>
</div>

Dropstart

Acione menus suspensos à esquerda dos elementos adicionando .dropstartao elemento pai.

<!-- Default dropstart button -->
<div class="btn-group dropstart">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false">
    Dropstart
  </button>
  <ul class="dropdown-menu">
    <!-- Dropdown menu links -->
  </ul>
</div>

<!-- Split dropstart button -->
<div class="btn-group dropstart">
  <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-bs-toggle="dropdown" aria-expanded="false">
    <span class="visually-hidden">Toggle Dropstart</span>
  </button>
  <ul class="dropdown-menu">
    <!-- Dropdown menu links -->
  </ul>
  <button type="button" class="btn btn-secondary">
    Split dropstart
  </button>
</div>

Você pode usar <a>ou <button>elementos como itens suspensos.

html

<div class="dropdown">
  <button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false">
    Dropdown
  </button>
  <ul class="dropdown-menu">
    <li><button class="dropdown-item" type="button">Action</button></li>
    <li><button class="dropdown-item" type="button">Another action</button></li>
    <li><button class="dropdown-item" type="button">Something else here</button></li>
  </ul>
</div>

Você também pode criar itens suspensos não interativos com .dropdown-item-text. Sinta-se à vontade para estilizar ainda mais com CSS personalizado ou utilitários de texto.

html

<ul class="dropdown-menu">
  <li><span class="dropdown-item-text">Dropdown item text</span></li>
  <li><a class="dropdown-item" href="#">Action</a></li>
  <li><a class="dropdown-item" href="#">Another action</a></li>
  <li><a class="dropdown-item" href="#">Something else here</a></li>
</ul>

Ativo

Adicione .activeitens na lista suspensa para estilizá- los como ativos . Para transmitir o estado ativo para tecnologias assistivas, use o aria-currentatributo — usando o pagevalor da página atual ou truedo item atual em um conjunto.

html

<ul class="dropdown-menu">
  <li><a class="dropdown-item" href="#">Regular link</a></li>
  <li><a class="dropdown-item active" href="#" aria-current="true">Active link</a></li>
  <li><a class="dropdown-item" href="#">Another link</a></li>
</ul>

Desabilitado

Adicione .disableditens na lista suspensa para estilizá- los como desabilitados .

html

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

Por padrão, um menu suspenso é posicionado automaticamente 100% na parte superior e no lado esquerdo de seu pai. Você pode alterar isso com as .drop*classes direcionais, mas também pode controlá-las com classes modificadoras adicionais.

Adicionar .dropdown-menu-enda .dropdown-menupara alinhar à direita o menu suspenso. As direções são espelhadas ao usar o Bootstrap em RTL, o que significa .dropdown-menu-endque aparecerá no lado esquerdo.

Atenção! As listas suspensas são posicionadas graças ao Popper, exceto quando estão contidas em uma barra de navegação.

html

<div class="btn-group">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false">
    Right-aligned menu example
  </button>
  <ul class="dropdown-menu dropdown-menu-end">
    <li><button class="dropdown-item" type="button">Action</button></li>
    <li><button class="dropdown-item" type="button">Another action</button></li>
    <li><button class="dropdown-item" type="button">Something else here</button></li>
  </ul>
</div>

Alinhamento responsivo

Se você quiser usar o alinhamento responsivo, desative o posicionamento dinâmico adicionando o data-bs-display="static"atributo e use as classes de variação responsiva.

Para alinhar à direita o menu suspenso com o ponto de interrupção fornecido ou maior, adicione .dropdown-menu{-sm|-md|-lg|-xl|-xxl}-end.

html

<div class="btn-group">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" data-bs-display="static" aria-expanded="false">
    Left-aligned but right aligned when large screen
  </button>
  <ul class="dropdown-menu dropdown-menu-lg-end">
    <li><button class="dropdown-item" type="button">Action</button></li>
    <li><button class="dropdown-item" type="button">Another action</button></li>
    <li><button class="dropdown-item" type="button">Something else here</button></li>
  </ul>
</div>

Para alinhar à esquerda o menu suspenso com o ponto de interrupção fornecido ou maior, adicione .dropdown-menu-ende .dropdown-menu{-sm|-md|-lg|-xl|-xxl}-start.

html

<div class="btn-group">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" data-bs-display="static" aria-expanded="false">
    Right-aligned but left aligned when large screen
  </button>
  <ul class="dropdown-menu dropdown-menu-end dropdown-menu-lg-start">
    <li><button class="dropdown-item" type="button">Action</button></li>
    <li><button class="dropdown-item" type="button">Another action</button></li>
    <li><button class="dropdown-item" type="button">Something else here</button></li>
  </ul>
</div>

Observe que você não precisa adicionar um data-bs-display="static"atributo aos botões suspensos nas barras de navegação, pois o Popper não é usado nas barras de navegação.

Opções de alinhamento

Tomando a maioria das opções mostradas acima, aqui está uma pequena demonstração de pia de cozinha de várias opções de alinhamento suspenso em um só lugar.

html

<div class="btn-group">
  <button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false">
    Dropdown
  </button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
  </ul>
</div>

<div class="btn-group">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false">
    Right-aligned menu
  </button>
  <ul class="dropdown-menu dropdown-menu-end">
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
  </ul>
</div>

<div class="btn-group">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" data-bs-display="static" aria-expanded="false">
    Left-aligned, right-aligned lg
  </button>
  <ul class="dropdown-menu dropdown-menu-lg-end">
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
  </ul>
</div>

<div class="btn-group">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" data-bs-display="static" aria-expanded="false">
    Right-aligned, left-aligned lg
  </button>
  <ul class="dropdown-menu dropdown-menu-end dropdown-menu-lg-start">
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
  </ul>
</div>

<div class="btn-group dropstart">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false">
    Dropstart
  </button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
  </ul>
</div>

<div class="btn-group dropend">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false">
    Dropend
  </button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
  </ul>
</div>

<div class="btn-group dropup">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false">
    Dropup
  </button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
  </ul>
</div>

Cabeçalhos

Adicione um cabeçalho para rotular seções de ações em qualquer menu suspenso.

html

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

Divisores

Grupos separados de itens de menu relacionados com um divisor.

html

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

Texto

Coloque qualquer texto de forma livre em um menu suspenso com texto e use utilitários de espaçamento . Observe que você provavelmente precisará de estilos de dimensionamento adicionais para restringir a largura do menu.

html

<div class="dropdown-menu p-4 text-muted" style="max-width: 200px;">
  <p>
    Some example text that's free-flowing within the dropdown menu.
  </p>
  <p class="mb-0">
    And this is more example text.
  </p>
</div>

Formulários

Coloque um formulário em um menu suspenso ou transforme-o em um menu suspenso e use utilitários de margem ou preenchimento para fornecer o espaço negativo necessário.

html

<div class="dropdown-menu">
  <form class="px-4 py-3">
    <div class="mb-3">
      <label for="exampleDropdownFormEmail1" class="form-label">Email address</label>
      <input type="email" class="form-control" id="exampleDropdownFormEmail1" placeholder="[email protected]">
    </div>
    <div class="mb-3">
      <label for="exampleDropdownFormPassword1" class="form-label">Password</label>
      <input type="password" class="form-control" id="exampleDropdownFormPassword1" placeholder="Password">
    </div>
    <div class="mb-3">
      <div class="form-check">
        <input type="checkbox" class="form-check-input" id="dropdownCheck">
        <label class="form-check-label" for="dropdownCheck">
          Remember me
        </label>
      </div>
    </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>

html

<div class="dropdown">
  <button type="button" class="btn btn-primary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false" data-bs-auto-close="outside">
    Dropdown form
  </button>
  <form class="dropdown-menu p-4">
    <div class="mb-3">
      <label for="exampleDropdownFormEmail2" class="form-label">Email address</label>
      <input type="email" class="form-control" id="exampleDropdownFormEmail2" placeholder="[email protected]">
    </div>
    <div class="mb-3">
      <label for="exampleDropdownFormPassword2" class="form-label">Password</label>
      <input type="password" class="form-control" id="exampleDropdownFormPassword2" placeholder="Password">
    </div>
    <div class="mb-3">
      <div class="form-check">
        <input type="checkbox" class="form-check-input" id="dropdownCheck2">
        <label class="form-check-label" for="dropdownCheck2">
          Remember me
        </label>
      </div>
    </div>
    <button type="submit" class="btn btn-primary">Sign in</button>
  </form>
</div>

Use data-bs-offsetou data-bs-referencepara alterar o local da lista suspensa.

html

<div class="d-flex">
  <div class="dropdown me-1">
    <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false" data-bs-offset="10,20">
      Offset
    </button>
    <ul class="dropdown-menu">
      <li><a class="dropdown-item" href="#">Action</a></li>
      <li><a class="dropdown-item" href="#">Another action</a></li>
      <li><a class="dropdown-item" href="#">Something else here</a></li>
    </ul>
  </div>
  <div class="btn-group">
    <button type="button" class="btn btn-secondary">Reference</button>
    <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-bs-toggle="dropdown" aria-expanded="false" data-bs-reference="parent">
      <span class="visually-hidden">Toggle Dropdown</span>
    </button>
    <ul class="dropdown-menu">
      <li><a class="dropdown-item" href="#">Action</a></li>
      <li><a class="dropdown-item" href="#">Another action</a></li>
      <li><a class="dropdown-item" href="#">Something else here</a></li>
      <li><hr class="dropdown-divider"></li>
      <li><a class="dropdown-item" href="#">Separated link</a></li>
    </ul>
  </div>
</div>

Comportamento de fechamento automático

Por padrão, o menu suspenso é fechado ao clicar dentro ou fora do menu suspenso. Você pode usar a autoCloseopção para alterar esse comportamento do menu suspenso.

html

<div class="btn-group">
  <button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" data-bs-auto-close="true" aria-expanded="false">
    Default dropdown
  </button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
  </ul>
</div>

<div class="btn-group">
  <button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" data-bs-auto-close="inside" aria-expanded="false">
    Clickable outside
  </button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
  </ul>
</div>

<div class="btn-group">
  <button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" data-bs-auto-close="outside" aria-expanded="false">
    Clickable inside
  </button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
  </ul>
</div>

<div class="btn-group">
  <button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" data-bs-auto-close="false" aria-expanded="false">
    Manual close
  </button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
  </ul>
</div>

CSS

Variáveis

Adicionado na v5.2.0

Como parte da abordagem de variáveis CSS em evolução do Bootstrap, os menus suspensos agora usam variáveis CSS locais .dropdown-menupara personalização aprimorada em tempo real. Os valores das variáveis CSS são definidos por meio do Sass, portanto, a personalização do Sass também é suportada.

  --#{$prefix}dropdown-zindex: #{$zindex-dropdown};
  --#{$prefix}dropdown-min-width: #{$dropdown-min-width};
  --#{$prefix}dropdown-padding-x: #{$dropdown-padding-x};
  --#{$prefix}dropdown-padding-y: #{$dropdown-padding-y};
  --#{$prefix}dropdown-spacer: #{$dropdown-spacer};
  @include rfs($dropdown-font-size, --#{$prefix}dropdown-font-size);
  --#{$prefix}dropdown-color: #{$dropdown-color};
  --#{$prefix}dropdown-bg: #{$dropdown-bg};
  --#{$prefix}dropdown-border-color: #{$dropdown-border-color};
  --#{$prefix}dropdown-border-radius: #{$dropdown-border-radius};
  --#{$prefix}dropdown-border-width: #{$dropdown-border-width};
  --#{$prefix}dropdown-inner-border-radius: #{$dropdown-inner-border-radius};
  --#{$prefix}dropdown-divider-bg: #{$dropdown-divider-bg};
  --#{$prefix}dropdown-divider-margin-y: #{$dropdown-divider-margin-y};
  --#{$prefix}dropdown-box-shadow: #{$dropdown-box-shadow};
  --#{$prefix}dropdown-link-color: #{$dropdown-link-color};
  --#{$prefix}dropdown-link-hover-color: #{$dropdown-link-hover-color};
  --#{$prefix}dropdown-link-hover-bg: #{$dropdown-link-hover-bg};
  --#{$prefix}dropdown-link-active-color: #{$dropdown-link-active-color};
  --#{$prefix}dropdown-link-active-bg: #{$dropdown-link-active-bg};
  --#{$prefix}dropdown-link-disabled-color: #{$dropdown-link-disabled-color};
  --#{$prefix}dropdown-item-padding-x: #{$dropdown-item-padding-x};
  --#{$prefix}dropdown-item-padding-y: #{$dropdown-item-padding-y};
  --#{$prefix}dropdown-header-color: #{$dropdown-header-color};
  --#{$prefix}dropdown-header-padding-x: #{$dropdown-header-padding-x};
  --#{$prefix}dropdown-header-padding-y: #{$dropdown-header-padding-y};

A customização por meio de variáveis CSS pode ser vista na .dropdown-menu-darkclasse onde sobrescrevemos valores específicos sem adicionar seletores CSS duplicados.

  --#{$prefix}dropdown-color: #{$dropdown-dark-color};
  --#{$prefix}dropdown-bg: #{$dropdown-dark-bg};
  --#{$prefix}dropdown-border-color: #{$dropdown-dark-border-color};
  --#{$prefix}dropdown-box-shadow: #{$dropdown-dark-box-shadow};
  --#{$prefix}dropdown-link-color: #{$dropdown-dark-link-color};
  --#{$prefix}dropdown-link-hover-color: #{$dropdown-dark-link-hover-color};
  --#{$prefix}dropdown-divider-bg: #{$dropdown-dark-divider-bg};
  --#{$prefix}dropdown-link-hover-bg: #{$dropdown-dark-link-hover-bg};
  --#{$prefix}dropdown-link-active-color: #{$dropdown-dark-link-active-color};
  --#{$prefix}dropdown-link-active-bg: #{$dropdown-dark-link-active-bg};
  --#{$prefix}dropdown-link-disabled-color: #{$dropdown-dark-link-disabled-color};
  --#{$prefix}dropdown-header-color: #{$dropdown-dark-header-color};

Variáveis atrevidas

Variáveis para todas as listas suspensas:

$dropdown-min-width:                10rem;
$dropdown-padding-x:                0;
$dropdown-padding-y:                .5rem;
$dropdown-spacer:                   .125rem;
$dropdown-font-size:                $font-size-base;
$dropdown-color:                    $body-color;
$dropdown-bg:                       $white;
$dropdown-border-color:             var(--#{$prefix}border-color-translucent);
$dropdown-border-radius:            $border-radius;
$dropdown-border-width:             $border-width;
$dropdown-inner-border-radius:      subtract($dropdown-border-radius, $dropdown-border-width);
$dropdown-divider-bg:               $dropdown-border-color;
$dropdown-divider-margin-y:         $spacer * .5;
$dropdown-box-shadow:               $box-shadow;

$dropdown-link-color:               $gray-900;
$dropdown-link-hover-color:         shade-color($dropdown-link-color, 10%);
$dropdown-link-hover-bg:            $gray-200;

$dropdown-link-active-color:        $component-active-color;
$dropdown-link-active-bg:           $component-active-bg;

$dropdown-link-disabled-color:      $gray-500;

$dropdown-item-padding-y:           $spacer * .25;
$dropdown-item-padding-x:           $spacer;

$dropdown-header-color:             $gray-600;
$dropdown-header-padding-x:         $dropdown-item-padding-x;
$dropdown-header-padding-y:         $dropdown-padding-y;
// fusv-disable
$dropdown-header-padding:           $dropdown-header-padding-y $dropdown-header-padding-x; // Deprecated in v5.2.0
// fusv-enable

Variáveis para a lista suspensa escura :

$dropdown-dark-color:               $gray-300;
$dropdown-dark-bg:                  $gray-800;
$dropdown-dark-border-color:        $dropdown-border-color;
$dropdown-dark-divider-bg:          $dropdown-divider-bg;
$dropdown-dark-box-shadow:          null;
$dropdown-dark-link-color:          $dropdown-dark-color;
$dropdown-dark-link-hover-color:    $white;
$dropdown-dark-link-hover-bg:       rgba($white, .15);
$dropdown-dark-link-active-color:   $dropdown-link-active-color;
$dropdown-dark-link-active-bg:      $dropdown-link-active-bg;
$dropdown-dark-link-disabled-color: $gray-500;
$dropdown-dark-header-color:        $gray-500;

Variáveis para os acentos circunflexos baseados em CSS que indicam a interatividade de uma lista suspensa:

$caret-width:                 .3em;
$caret-vertical-align:        $caret-width * .85;
$caret-spacing:               $caret-width * .85;

Mixins

Mixins são usados para gerar os acentos circunflexos baseados em CSS e podem ser encontrados em arquivos scss/mixins/_caret.scss.

@mixin caret-down {
  border-top: $caret-width solid;
  border-right: $caret-width solid transparent;
  border-bottom: 0;
  border-left: $caret-width solid transparent;
}

@mixin caret-up {
  border-top: 0;
  border-right: $caret-width solid transparent;
  border-bottom: $caret-width solid;
  border-left: $caret-width solid transparent;
}

@mixin caret-end {
  border-top: $caret-width solid transparent;
  border-right: 0;
  border-bottom: $caret-width solid transparent;
  border-left: $caret-width solid;
}

@mixin caret-start {
  border-top: $caret-width solid transparent;
  border-right: $caret-width solid;
  border-bottom: $caret-width solid transparent;
}

@mixin caret($direction: down) {
  @if $enable-caret {
    &::after {
      display: inline-block;
      margin-left: $caret-spacing;
      vertical-align: $caret-vertical-align;
      content: "";
      @if $direction == down {
        @include caret-down();
      } @else if $direction == up {
        @include caret-up();
      } @else if $direction == end {
        @include caret-end();
      }
    }

    @if $direction == start {
      &::after {
        display: none;
      }

      &::before {
        display: inline-block;
        margin-right: $caret-spacing;
        vertical-align: $caret-vertical-align;
        content: "";
        @include caret-start();
      }
    }

    &:empty::after {
      margin-left: 0;
    }
  }
}

Uso

Por meio de atributos de dados ou JavaScript, o plug-in suspenso alterna o conteúdo oculto (menus suspensos) alternando a .showclasse no arquivo pai .dropdown-menu. O data-bs-toggle="dropdown"atributo é usado para fechar menus suspensos em um nível de aplicativo, portanto, é uma boa ideia sempre usá-lo.

Em dispositivos habilitados para toque, abrir uma lista suspensa adiciona mouseovermanipuladores vazios aos filhos imediatos do <body>elemento. Esse hack reconhecidamente feio é necessário para contornar uma peculiaridade na delegação de eventos do iOS , que de outra forma impediria que um toque em qualquer lugar fora do menu suspenso acionasse o código que fecha o menu suspenso. Depois que a lista suspensa é fechada, esses mouseovermanipuladores vazios adicionais são removidos.

Por atributos de dados

Adicione data-bs-toggle="dropdown"a um link ou botão para alternar uma lista suspensa.

<div class="dropdown">
  <button type="button" data-bs-toggle="dropdown" aria-expanded="false">
    Dropdown trigger
  </button>
  <ul class="dropdown-menu">
    ...
  </ul>
</div>

Por JavaScript

Chame as listas suspensas via JavaScript:

const dropdownElementList = document.querySelectorAll('.dropdown-toggle')
const dropdownList = [...dropdownElementList].map(dropdownToggleEl => new bootstrap.Dropdown(dropdownToggleEl))

`data-bs-toggle="dropdown"`ainda é necessário

Independentemente de você chamar sua lista suspensa via JavaScript ou usar a API de dados, data-bs-toggle="dropdown"é sempre necessário estar presente no elemento de gatilho da lista suspensa.

Opções

Como as opções podem ser passadas por meio de atributos de dados ou JavaScript, você pode anexar um nome de opção a data-bs-, como em data-bs-animation="{value}". Certifique-se de alterar o tipo de caso do nome da opção de “ camelCase ” para “ kebab-case ” ao passar as opções por meio de atributos de dados. Por exemplo, use data-bs-custom-class="beautifier"em vez de data-bs-customClass="beautifier".

A partir do Bootstrap 5.2.0, todos os componentes oferecem suporte a um atributo experimental de dados reservados data-bs-configque pode abrigar a configuração simples do componente como uma string JSON. Quando um elemento tem atributos data-bs-config='{"delay":0, "title":123}'e data-bs-title="456", o valor final titleserá 456e os atributos de dados separados substituirão os valores fornecidos em data-bs-config. Além disso, os atributos de dados existentes podem hospedar valores JSON como data-bs-delay='{"show":0,"hide":150}'.

Nome	Modelo	Predefinição	Descrição
`autoClose`	booleano, string	`true`	Configure o comportamento de fechamento automático da lista suspensa: `true`- o menu suspenso será fechado clicando fora ou dentro do menu suspenso. `false`- o menu suspenso será fechado clicando no botão de alternância e chamando manualmente `hide`ou `toggle`método. (Também não será fechado pressionando `esc`a tecla) `'inside'`- a lista suspensa será fechada (somente) clicando dentro do menu suspenso. `'outside'`- o menu suspenso será fechado (somente) clicando fora do menu suspenso. Nota: o dropdown sempre pode ser fechado com a `ESC`chave.
`boundary`	corda, elemento	`'clippingParents'`	Limite de restrição de estouro do menu suspenso (aplica-se apenas ao modificador preventOverflow do Popper). Por padrão, é `clippingParents`e pode aceitar uma referência HTMLElement (somente via JavaScript). Para obter mais informações, consulte os documentos detectOverflow do Popper .
`display`	corda	`'dynamic'`	Por padrão, usamos Popper para posicionamento dinâmico. Desative isso com `static`.
`offset`	array, string, função	`[0, 2]`	Deslocamento da lista suspensa em relação ao seu destino. Você pode passar uma string em atributos de dados com valores separados por vírgulas como: `data-bs-offset="10,20"`. Quando uma função é usada para determinar o deslocamento, ela é chamada com um objeto contendo o posicionamento do popper, a referência e os retos do popper como seu primeiro argumento. O nó DOM do elemento acionador é passado como o segundo argumento. A função deve retornar um array com dois números: skidding , distance . Para obter mais informações, consulte os documentos de deslocamento de Popper .
`popperConfig`	nulo, objeto, função	`null`	Para alterar a configuração padrão do Popper do Bootstrap, consulte a configuração do Popper . Quando uma função é usada para criar a configuração do Popper, ela é chamada com um objeto que contém a configuração padrão do Popper do Bootstrap. Ele ajuda você a usar e mesclar o padrão com sua própria configuração. A função deve retornar um objeto de configuração para Popper.
`reference`	string, elemento, objeto	`'toggle'`	Elemento de referência do menu suspenso. Aceita os valores de `'toggle'`, `'parent'`, uma referência HTMLElement ou um objeto que fornece `getBoundingClientRect`. Para obter mais informações, consulte a documentação do construtor do Popper e a documentação do elemento virtual .

Usando a função com`popperConfig`

const dropdown = new bootstrap.Dropdown(element, {
  popperConfig(defaultBsPopperConfig) {
    // const newPopperConfig = {...}
    // use defaultBsPopperConfig if needed...
    // return newPopperConfig
  }
})

Métodos

Método	Descrição
`dispose`	Destrói a lista suspensa de um elemento. (Remove os dados armazenados no elemento DOM)
`getInstance`	Método estático que permite obter a instância suspensa associada a um elemento DOM, você pode usá-lo assim: `bootstrap.Dropdown.getInstance(element)`.
`getOrCreateInstance`	Método estático que retorna uma instância suspensa associada a um elemento DOM ou cria uma nova caso não tenha sido inicializada. Você pode usar assim: `bootstrap.Dropdown.getOrCreateInstance(element)`.
`hide`	Oculta o menu suspenso de uma determinada barra de navegação ou navegação com guias.
`show`	Mostra o menu suspenso de uma determinada barra de navegação ou navegação com guias.
`toggle`	Alterna o menu suspenso de uma determinada barra de navegação ou navegação com guias.
`update`	Atualiza a posição da lista suspensa de um elemento.

Eventos

Todos os eventos suspensos são disparados no elemento de alternância e, em seguida, borbulhados. Portanto, você também pode adicionar ouvintes de eventos no .dropdown-menuelemento pai do . hide.bs.dropdowne hidden.bs.dropdowneventos têm uma clickEventpropriedade (somente quando o tipo de evento original é click) que contém um objeto de evento para o evento de clique.

Tipo de evento	Descrição
`hide.bs.dropdown`	Dispara imediatamente quando o `hide`método de instância é chamado.
`hidden.bs.dropdown`	Acionado quando a lista suspensa termina de ser ocultada do usuário e as transições CSS são concluídas.
`show.bs.dropdown`	Dispara imediatamente quando o `show`método de instância é chamado.
`shown.bs.dropdown`	Acionado quando a lista suspensa se torna visível para o usuário e as transições CSS são concluídas.

const myDropdown = document.getElementById('myDropdown')
myDropdown.addEventListener('show.bs.dropdown', event => {
  // do something...
})

Listas suspensas

Visão geral

Acessibilidade

Exemplos

Botão único

Botão de divisão

Dimensionamento

Listas suspensas escuras

instruções

RTL

Centralizado

Soltar-se

Dropup centralizado

Dropend

Dropstart

Itens do menu

Ativo

Desabilitado

Alinhamento do menu

Alinhamento responsivo

Opções de alinhamento

Conteúdo do cardápio

Cabeçalhos

Divisores

Texto

Formulários

Comportamento de fechamento automático

CSS

Variáveis

Variáveis atrevidas

Mixins

Uso

Por atributos de dados

Por JavaScript

`data-bs-toggle="dropdown"`ainda é necessário

Opções

Usando a função com`popperConfig`

Métodos

Eventos

Listas suspensas

Visão geral

Acessibilidade

Exemplos

Botão único

Botão de divisão

Dimensionamento

Listas suspensas escuras

instruções

RTL

Centralizado

Soltar-se

Dropup centralizado

Dropend

Dropstart

Itens do menu

Ativo

Desabilitado

Alinhamento do menu

Alinhamento responsivo

Opções de alinhamento

Conteúdo do cardápio

Cabeçalhos

Cabeçalho suspenso

Divisores

Texto

Formulários

Opções suspensas

Comportamento de fechamento automático

CSS

Variáveis

Variáveis ​​atrevidas

Mixins

Uso

Por atributos de dados

Por JavaScript

data-bs-toggle="dropdown"ainda é necessário

Opções

Usando a função compopperConfig

Métodos

Eventos

Variáveis atrevidas

`data-bs-toggle="dropdown"`ainda é necessário

Usando a função com`popperConfig`