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>

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>

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>

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>

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…
})

Dropdowns

Visão Geral

Acessibilidade

Exemplos

Único botão

Botão dividido

Tamanhos

Direções

Dropup

Dropright

Dropleft

Itens do menu

Ativo

Desativado

Alinhamento de menu

Conteúdo do menu

Cabeçalho

Divisórias

Texto

Formulários

Modo de uso

Via atributos data

Via JavaScript

`data-toggle="dropdown"` é obrigatório

Parâmetros

Métodos

Eventos

Dropdowns

Visão Geral

Acessibilidade

Exemplos

Único botão

Botão dividido

Tamanhos

Direções

Dropup

Dropright

Dropleft

Itens do menu

Ativo

Desativado

Alinhamento de menu

Conteúdo do menu

Cabeçalho

Cabeçalho dropdown

Divisórias

Texto

Formulários

Prâmetros do dropdown

Modo de uso

Via atributos data

Via JavaScript

data-toggle="dropdown" é obrigatório

Parâmetros

Métodos

Eventos

`data-toggle="dropdown"` é obrigatório