Source

Listas suspensas

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

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 .

As listas suspensas são criadas em uma biblioteca de terceiros, Popper.js , que fornece posicionamento dinâmico e detecção de janela de visualização. Certifique-se de incluir popper.min.js antes do JavaScript do Bootstrap ou use bootstrap.bundle.min.js/ bootstrap.bundle.jsque contém Popper.js. Popper.js não é usado para posicionar dropdowns em navbars, embora o posicionamento dinâmico não seja necessário.

Se você estiver construindo nosso JavaScript a partir da fonte, ele requerutil.js .

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.

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:

Ação Outra ação Outra coisa aqui 
<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>

E com <a>elementos:

Ação Outra ação Outra coisa aqui 
<div class="dropdown">
  <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>

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

Ação Outra ação Outra coisa aqui
Link separado
Ação Outra ação Outra coisa aqui
Link separado
Ação Outra ação Outra coisa aqui
Link separado
Ação Outra ação Outra coisa aqui
Link separado
Ação Outra ação Outra coisa aqui
Link separado
Ação Outra ação Outra coisa aqui
Link separado 
<!-- 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>

Botão de divisão

Da mesma forma, crie listas suspensas de botão dividido com praticamente a mesma marcação que as 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.

Ação Outra ação Outra coisa aqui
Link separado
Ação Outra ação Outra coisa aqui
Link separado
Ação Outra ação Outra coisa aqui
Link separado
Ação Outra ação Outra coisa aqui
Link separado
Ação Outra ação Outra coisa aqui
Link separado
Ação Outra ação Outra coisa aqui
Link separado 
<!-- 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>

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-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>

instruções

Soltar-se

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

Ação Outra ação Outra coisa aqui
Link separado
Ação Outra ação Outra coisa aqui
Link separado 
<!-- 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>

Dropright

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

Ação Outra ação Outra coisa aqui
Link separado
Ação Outra ação Outra coisa aqui
Link separado 
<!-- 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>

Dropleft

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

Ação Outra ação Outra coisa aqui
Link separado
Ação Outra ação Outra coisa aqui
Link separado 
<!-- 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>

Historicamente, o conteúdo do menu suspenso tinha que ser links, mas esse não é mais o caso da v4. Agora, opcionalmente, você pode usar <button>elementos em suas listas suspensas em vez de apenas <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>

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.

Texto do item suspenso Ação Outra ação Outra coisa aqui 
<div class="dropdown-menu">
  <span class="dropdown-item-text">Dropdown item text</span>
  <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>

Ativo

Adicione .activeitens na lista suspensa para estilizá- los como ativos .

Link normal Link ativo Outro link 
<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>

Desabilitado

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

Link normal Link desativado Outro link 
<div class="dropdown-menu">
  <a class="dropdown-item" href="#">Regular link</a>
  <a class="dropdown-item disabled" href="#" tabindex="-1" aria-disabled="true">Disabled link</a>
  <a class="dropdown-item" href="#">Another link</a>
</div>

Por padrão, um menu suspenso é posicionado automaticamente 100% na parte superior e no lado esquerdo de seu pai. Adicionar .dropdown-menu-righta .dropdown-menupara alinhar à direita o menu suspenso.

Atenção! Os dropdowns são posicionados graças ao Popper.js (exceto quando estão contidos em uma barra de navegação).

<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>

Alinhamento responsivo

Se você quiser usar o alinhamento responsivo, desative o posicionamento dinâmico adicionando o data-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}-right.

<div class="btn-group">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" data-display="static" aria-haspopup="true" aria-expanded="false">
    Left-aligned but right aligned when large screen
  </button>
  <div class="dropdown-menu dropdown-menu-lg-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>

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

<div class="btn-group">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" data-display="static" aria-haspopup="true" aria-expanded="false">
    Right-aligned but left aligned when large screen
  </button>
  <div class="dropdown-menu dropdown-menu-right dropdown-menu-lg-left">
    <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>

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

Conteúdo do cardápio

Cabeçalhos

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

Cabeçalho suspenso
Ação Outra ação 
<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>

Divisores

Grupos separados de itens de menu relacionados com um divisor.

Ação Outra ação Outra coisa aqui
Link separado 
<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>

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.

Alguns exemplos de texto que fluem livremente no menu suspenso.

E este é mais um texto de exemplo.

<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.

Novo por aqui? Inscrever-se Esqueceu a senha? 
<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-group">
      <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>
<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-group">
    <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>

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

Ação Outra ação Outra coisa aqui
Ação Outra ação Outra coisa aqui
Link separado 
<div class="d-flex">
  <div class="dropdown mr-1">
    <button type="button" class="btn btn-secondary dropdown-toggle" id="dropdownMenuOffset" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false" data-offset="10,20">
      Offset
    </button>
    <div class="dropdown-menu" aria-labelledby="dropdownMenuOffset">
      <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>
  <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" id="dropdownMenuReference" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false" data-reference="parent">
      <span class="sr-only">Toggle Dropdown</span>
    </button>
    <div class="dropdown-menu" aria-labelledby="dropdownMenuReference">
      <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>
</div>

Uso

Por meio de atributos de dados ou JavaScript, o plug-in suspenso alterna o conteúdo oculto (menus suspensos) alternando a .showclasse no item da lista pai. O data-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 manipuladores vazios ( $.noop) mouseoveraos 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-toggle="dropdown"a um link ou botão para alternar uma lista suspensa.

<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>

Por JavaScript

Chame as listas suspensas via JavaScript:

$('.dropdown-toggle').dropdown()
data-toggle="dropdown"ainda é necessário

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

Opções

As opções podem ser passadas por meio de atributos de dados ou JavaScript. Para atributos de dados, anexe o nome da opção a data-, como em data-offset="".

Nome Modelo Predefinição Descrição
Deslocamento número | seqüência | função 0 Deslocamento da lista suspensa em relação ao seu destino. Para obter mais informações, consulte os documentos de deslocamento do Popper.js .
virar boleano verdadeiro Permitir que o menu suspenso gire em caso de sobreposição no elemento de referência. Para obter mais informações, consulte os flip docs do Popper.js .
fronteira seqüência | elemento 'scrollParent' Limite de restrição de estouro do menu suspenso. Aceita os valores de 'viewport', 'window', 'scrollParent'ou uma referência HTMLElement (somente JavaScript). Para obter mais informações, consulte os documentos preventOverflow do Popper.js .
referência seqüência | elemento 'alternar' Elemento de referência do menu suspenso. Aceita os valores de 'toggle', 'parent'ou uma referência HTMLElement. Para obter mais informações, consulte os documentos referenceObject do Popper.js .
exibição corda 'dinâmico' Por padrão, usamos Popper.js para posicionamento dinâmico. Desative isso com static.

Observe que quando boundaryé definido com qualquer valor diferente de 'scrollParent', o estilo position: staticé aplicado ao .dropdowncontêiner.

Métodos

Método Descrição
$().dropdown('toggle') Alterna o menu suspenso de uma determinada barra de navegação ou navegação com guias.
$().dropdown('show') Mostra o menu suspenso de uma determinada barra de navegação ou navegação com guias.
$().dropdown('hide') Oculta o menu suspenso de uma determinada barra de navegação ou navegação com guias.
$().dropdown('update') Atualiza a posição da lista suspensa de um elemento.
$().dropdown('dispose') Destrói a lista suspensa de um elemento.

Eventos

Todos os eventos suspensos são disparados no .dropdown-menuelemento pai do 's e possuem uma relatedTargetpropriedade, cujo valor é o elemento âncora de alternância. 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.

Evento Descrição
show.bs.dropdown Este evento é acionado imediatamente quando o método de instância show é chamado.
shown.bs.dropdown Este evento é acionado quando a lista suspensa se torna visível para o usuário (aguardará as transições CSS para serem concluídas).
hide.bs.dropdown Este evento é disparado imediatamente quando o método de instância hide é chamado.
hidden.bs.dropdown Este evento é acionado quando a lista suspensa termina de ser ocultada do usuário (aguardará a conclusão das transições CSS). 
$('#myDropdown').on('show.bs.dropdown', function () {
  // do something…
})