Dropdowns

Clique em botões para ver um lista de links e outras coisas, usando o plugin Bootstrap dropdown.

Visão Geral

Dropdowns são botões com alternância de visibilidade de listas de links e outras coisas. Conseguem ser interativos graças a sua construção que foi feita com o plugin JavaScript dropdown. A visibilidade do conteúdo é alternada com cliques e nunca só ao passar o mouse em cima do botão (uma decisão de design intencional).

Dropdowns são feitos em cima de uma biblioteca de terceiros, Popper.js, a qual permite posicionamento dinâmico e detecção de viewport. Se assegure de invocar popper.min.js, antes do JavaScript Bootstrap ou use bootstrap.bundle.min.js / bootstrap.bundle.js, os quais já possuem o Popper.js. No entanto, Popper.js não é usada para posicionar dropdowns em navbars, já que posicionamento dinâmico não é necessário.

Se você está construindo nosso JavaScript a partir da fonte, vai precisar do util.js.

Acessibilidade

O padrões WAI ARIA pedem o uso do atributo role="menu", mas ele é específico para menus de aplicações que ativam ações ou funções. Menus ARIA só podem conter itens de menu, checkbox, grupos e botões radio, além de sub-menus.

Os dropdowns Bootstrap, por outro lado, são desenhados para serem genéricos e aplicáveis em várias situações e estruturas de marcação. Por exemplo, é possível criar dropdowns que possuem inputs e form controls adicionais, como campos de pesquisa ou formulários de login. Por essa razão, Bootstrap não espera (nem adiciona automaticamente) a presença dos atributos role e aria, exigidos nos reais menus ARIA. Os autores terão que incluí-los, por si só.

No entanto, Bootstrap tem suporte para a maioria das interações padrões de teclado, como a habilidade de mover-se através de elementos individuais dropdown-item (usando o as setinhas do teclado) ou fechar o menu com a tecla ESC.

Exemplos

Envolte os itens ou menu dropdown dentro da classe .dropdown ou qualquer outro elemento que tenha position: relative; declarado. Dropdowns podem ser acionados de um elemento <a> ou <button>, te dando mais flexibilidade.

Único botão

Qualquer .btn pode se transformar em um dropdown, com algumas adições na marcação HTML.

Aqui está como você pode fazê-los funcionar, usando <button>:

<div class="dropdown">
  <button class="btn btn-secondary dropdown-toggle" type="button" id="dropdownMenuButton" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    Botão dropdown
  </button>
  <div class="dropdown-menu" aria-labelledby="dropdownMenuButton">
    <a class="dropdown-item" href="#">Alguma ação</a>
    <a class="dropdown-item" href="#">Outra ação</a>
    <a class="dropdown-item" href="#">Alguma coisa aqui</a>
  </div>
</div>

Já aqui, temos um exemplo de uso com o elemento <a>:

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

  <div class="dropdown-menu" aria-labelledby="dropdownMenuLink">
    <a class="dropdown-item" href="#">Alguma ação</a>
    <a class="dropdown-item" href="#">Outra ação</a>
    <a class="dropdown-item" href="#">Alguma coisa aqui</a>
  </div>
</div>

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

<!-- Exemplo de único botão danger -->
<div class="btn-group">
  <button type="button" class="btn btn-danger dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    Ação
  </button>
  <div class="dropdown-menu">
    <a class="dropdown-item" href="#">Alguma ação</a>
    <a class="dropdown-item" href="#">Outra ação</a>
    <a class="dropdown-item" href="#">Alguma coisa aqui</a>
    <div class="dropdown-divider"></div>
    <a class="dropdown-item" href="#">Link separado</a>
  </div>
</div>

Botão dividido

Similarmente, crie botões divididos com a mesma marcação HTML de botões dropdowns, mas com a adição da classe .dropdown-toggle-split para espaçamento apropriado, ao redor da setinha.

Nós usamos esta classe extra para reduzir o padding horizontal, em 25% dos lados da setinha e remover a margin-left que é adicionada em botões dropdowns comuns. Estas mudanças extras mantém a setinha centralizada e dá uma área de clique maior, no botão principal.

<!-- Exemplo de botão danger dividido -->
<div class="btn-group">
  <button type="button" class="btn btn-danger">Ação</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">Dropdown</span>
  </button>
  <div class="dropdown-menu">
    <a class="dropdown-item" href="#">Alguma ação</a>
    <a class="dropdown-item" href="#">Outra ação</a>
    <a class="dropdown-item" href="#">Alguma coisa aqui</a>
    <div class="dropdown-divider"></div>
    <a class="dropdown-item" href="#">Link separado</a>
  </div>
</div>

Tamanhos

Tanto os dropdowns padrões, quanto os divididos, funcionam em todos os tamanhos.

<!-- Grupo de botões grandes (padrões e divididos) -->
<div class="btn-group">
  <button class="btn btn-secondary btn-lg dropdown-toggle" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    Botão grande
  </button>
  <div class="dropdown-menu">
    ...
  </div>
</div>
<div class="btn-group">
  <button class="btn btn-secondary btn-lg" type="button">
    Botão grande dividido
  </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">Dropdown</span>
  </button>
  <div class="dropdown-menu">
    ...
  </div>
</div>

<!-- Grupo de botões pequenos (padrão e dividido) -->
<div class="btn-group">
  <button class="btn btn-secondary btn-sm dropdown-toggle" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    Botão pequeno
  </button>
  <div class="dropdown-menu">
    ...
  </div>
</div>
<div class="btn-group">
  <button class="btn btn-secondary btn-sm" type="button">
    Botão pequeno dividido
  </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">Dropdown</span>
  </button>
  <div class="dropdown-menu">
    ...
  </div>
</div>

Direções

Dropup

Acione menus para cima, usando a classe .dropup no elemento pai.

<!-- Botão dropup padrão -->
<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">
    <!-- Links do menu dropup -->
  </div>
</div>

<!-- Botão dropup dividido -->
<div class="btn-group dropup">
  <button type="button" class="btn btn-secondary">
    Dropup dividido
  </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">Dropdown</span>
  </button>
  <div class="dropdown-menu">
    <!-- Dropdown menu links -->
  </div>
</div>

Dropright

Acione menus para a direita, usando .dropright no elemento pai.

<!-- Botão dropright padrão -->
<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">
    <!-- Links do menu dropright -->
  </div>
</div>

<!-- Botão dropright dividido -->
<div class="btn-group dropright">
  <button type="button" class="btn btn-secondary">
    Dropright dividido
  </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">Dropright</span>
  </button>
  <div class="dropdown-menu">
    <!-- Links do menu dropright -->
  </div>
</div>

Dropleft

Acione menus a esquerda, usando a classe .dropleft no elemento pai.

<!-- Botão dropleft padrão -->
<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">
    <!-- Links do menu dropleft -->
  </div>
</div>

<!-- Botão dropleft dividido -->
<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">Dropleft</span>
    </button>
    <div class="dropdown-menu">
      <!-- Links do menu dropleft -->
    </div>
  </div>
  <button type="button" class="btn btn-secondary">
    Dropleft dividido
  </button>
</div>

Itens do menu

Historicamente, o conteúdo dos dropdowns tinham que ser links, mas isso não é mais o caso, na v4. Agora, você pode usar elementos <button> em seus dropdowns, invés de <a>.

<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">Ação</button>
    <button class="dropdown-item" type="button">Another Ação</button>
    <button class="dropdown-item" type="button">Something else here</button>
  </div>
</div>

Você também pode criar dropdowns com itens não interativos, usando .dropdown-item-text. Sinta-se livre para fazer mais estilizações com CSS ou utilitários de texto.

<div class="dropdown-menu">
  <span class="dropdown-item-text">Texto do item dropdown</span>
  <a class="dropdown-item" href="#">Alguma ação</a>
  <a class="dropdown-item" href="#">Outra ação</a>
  <a class="dropdown-item" href="#">Alguma coisa aqui</a>
</div>

Ativo

Use .active nos itens do dropdown para estilizar eles como ativos.

<div class="dropdown-menu">
  <a class="dropdown-item" href="#">Link comum</a>
  <a class="dropdown-item active" href="#">Link ativo</a>
  <a class="dropdown-item" href="#">Outro link</a>
</div>

Desativado

Coloque .disabled nos itens do dropdown para estilizar eles como desativados.

<div class="dropdown-menu">
  <a class="dropdown-item" href="#">Link comum</a>
  <a class="dropdown-item disabled" href="#">Link desativado</a>
  <a class="dropdown-item" href="#">Outro link</a>
</div>

Alinhamento de menu

Por padrão, o menu dropdown é, automaticamente, posicionado 100% a partir do topo e esquerda do elemento pai. Use .dropdown-menu-right em um .dropdown-menu para alinhar o menu dropdown a direita.

Atenção! Dropdowns são posicionados com ajuda do Popper.js (exceto quando estão dentro de uma navbar).

<div class="btn-group">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    Menu alinhado a direita
  </button>
  <div class="dropdown-menu dropdown-menu-right">
    <button class="dropdown-item" type="button">Ação</button>
    <button class="dropdown-item" type="button">Another Ação</button>
    <button class="dropdown-item" type="button">Algo mais aqui</button>
  </div>
</div>

Conteúdo do menu

Cabeçalho

Coloque um cabeçalho para rotular seções, no menu dropdown.

<div class="dropdown-menu">
  <h6 class="dropdown-header">Cabeçalho dropdown</h6>
  <a class="dropdown-item" href="#">Alguma ação</a>
  <a class="dropdown-item" href="#">Outra ação</a>
</div>

Divisórias

Separe grupos de itens, usando uma divisória.

<div class="dropdown-menu">
  <a class="dropdown-item" href="#">Alguma ação</a>
  <a class="dropdown-item" href="#">Outra ação</a>
  <a class="dropdown-item" href="#">Alguma coisa aqui</a>
  <div class="dropdown-divider"></div>
  <a class="dropdown-item" href="#">Link separado</a>
</div>

Texto

Coloque qualquer texto dentro do menu dropdown e use utilitários de espaçamentos. Perceba que você pode precisar estilizar o tamanho da fonte para se adequar a largura do menu.

<div class="dropdown-menu p-4 text-muted" style="max-width: 200px;">
  <p>
    Algum exemplo de texto, aqui dentro do menu.
  </p>
  <p class="mb-0">
    Mais um exemplo de texto.
  </p>
</div>

Formulários

Coloque um formulário dentro do menu dropdown ou transforme-o em um menu dropdown. Use utilitários de margem ou padding para conseguir o espaço negativo necessário.

<div class="dropdown-menu">
  <form class="px-4 py-3">
    <div class="form-group">
      <label for="exampleDropdownFormEmail1">Endereço de email</label>
      <input type="email" class="form-control" id="exampleDropdownFormEmail1" placeholder="email@exemplo.com">
    </div>
    <div class="form-group">
      <label for="exampleDropdownFormPassword1">Senha</label>
      <input type="password" class="form-control" id="exampleDropdownFormPassword1" placeholder="Senha">
    </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">Entrar</button>
  </form>
  <div class="dropdown-divider"></div>
  <a class="dropdown-item" href="#">Novo, por aqui? Regitre-se.</a>
  <a class="dropdown-item" href="#">Esqueceu a senha?</a>
</div>
<form class="dropdown-menu p-4">
  <div class="form-group">
    <label for="exampleDropdownFormEmail2">Endereço de email</label>
    <input type="email" class="form-control" id="exampleDropdownFormEmail2" placeholder="email@exemplo.com">
  </div>
  <div class="form-group">
    <label for="exampleDropdownFormPassword2">Senha</label>
    <input type="password" class="form-control" id="exampleDropdownFormPassword2" placeholder="Senha">
  </div>
  <div class="form-check">
    <input type="checkbox" class="form-check-input" id="dropdownCheck2">
    <label class="form-check-label" for="dropdownCheck2">
      Lembrar de mim
    </label>
  </div>
  <button type="submit" class="btn btn-primary">Entrar</button>
</form>

Prâmetros do dropdown

Use data-offset ou data-reference para mudar a localização do dropdown.

<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="#">Alguma ação</a>
      <a class="dropdown-item" href="#">Outra ação</a>
      <a class="dropdown-item" href="#">Alguma coisa aqui</a>
    </div>
  </div>
  <div class="btn-group">
    <button type="button" class="btn btn-secondary">Referência</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">Dropdown</span>
    </button>
    <div class="dropdown-menu" aria-labelledby="dropdownMenuReference">
      <a class="dropdown-item" href="#">Alguma ação</a>
      <a class="dropdown-item" href="#">Outra ação</a>
      <a class="dropdown-item" href="#">Alguma coisa aqui</a>
      <div class="dropdown-divider"></div>
      <a class="dropdown-item" href="#">Link separado</a>
    </div>
  </div>
</div>

Modo de uso

Usando JavaScript ou atributos data, o plugin dropdown alterna a visibilidade de conteúdo invisível (menus dropdown) trocando a classe .show, no elemento pai da lista. O atributo data-toggle="dropdown" é acreditado para fechar os menus dropdown em level de aplicação, então, é uma boa ideia sempre usá-lo.

Em dispositivos touch, abrir um menu adiciona manipuladores ($.noop) mouseover vazios em filhos imediatos do elemento <body>. Essa gambiarra feia é necessária para contornar um problema na delegação de eventos do iOS, o qual poderia evitar que toques fora do dropdown acionassem o código que fecha o próprio dropdown. Uma vez que o dropdown é fechado, esses manipuladores mouseover adicionais vazios são removidos.

Via atributos data

Use data-toggle="dropdown" em um link ou botão para alternar a visibilidade do menu dropdown.

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

Via JavaScript

Invoque os dropdowns, usando JavaScript:

$('.dropdown-toggle').dropdown()
data-toggle="dropdown" é obrigatório

Independente se você invoca seu dropdown com JavaScript ou com a data-api, o uso de data-toggle="dropdown" sempre é obrigatório no gatilho dropdown.

Parâmetros

Parâmetros sempre podem ser passados usando atributos ou JavaScript. Para atributos, anexe o parâmetro no prefixo data-, como em data-offset="".

Nome Tipo Padrão Descrição
offset number | string | função 0 Deslocamento do dropdown, em relação ao seu alvo. Para mais informações, veja a documentação do offset Popper.js.
flip boolean true Permite o dropdown virar, em caso de sobreposição no elemento de referência. Para mais informações, veja a documentação do flip Popper.js.
boundary string | elemento 'scrollParent' Limite de transbordamento do menu dropdown. Aceita os valores 'viewport', 'window', 'scrollParent' ou uma referência HTMLElement (JavaScript, apenas). Para mias informações, veja a documentação preventOverflow Popper.js.
reference string | elemento 'toggle' Elemento de referência do menu dropdown. Aceita os valores 'toggle', 'parent' ou uma referência HTMLElement. Para mais informações, veja a documentação referenceObject Popper.js.
display string 'dynamic' Por padrão, nós usamos o posicionamento dinâmico do Popper.js. Desative isso, usando o valor static.

Nota: quando boundary tem como valor definido qualquer coisa, que não 'scrollParent', o estilo position: static é aplicado no container .dropdown.

Métodos

Método Descrição
$().dropdown('toggle') Alterna a visibilidade do menu dropdown em uma dada navbar ou navegação por abas.
$().dropdown('update') Atualiza a posição do dropdown de um elemento.
$().dropdown('dispose') Destroi o dropdown de um elemento.

Eventos

Todos eventos dropdown são acionados no elemento pai do .dropdown-menu e possuem uma propriedade relatedTarget, a qual tem o valor referente ao elemento âncora de alternância.

Os eventos hide.bs.dropdown e hidden.bs.dropdown possuem uma propriedade clickEvent (só quando o tipo do evento original é click), a qual contém um objeto de evento (Event Object) para o evento do clique.

Evento Descrição
show.bs.dropdown Este evento é acionado, imediatamente, quando o método show é invocado.
shown.bs.dropdown Este evento é acionado quando o dropdown se torna visível ao usuário (espera as transições CSS finalizarem).
hide.bs.dropdown Este evento é acionado, imediatamente, quando o método hide foi invocado.
hidden.bs.dropdown Este evento é acionado quando o dropdown acaba de se esconder do usuário (espera as transições CSS finalizarem).
$('#myDropdown').on('show.bs.dropdown', function () {
  // Faça algo, aqui…
})