Popovers

Documentação e exemplos para criar popovers Bootstrap (igual aqueles do iOS), em qualquer elemento do seu site.

Visão geral

Coisas para saber, quando usando o plugin popover:

  • O popover depende da biblioteca externa Popper.js, para posicionamento. Você deve colocar popper.min.js antes de bootstrap.js ou usar bootstrap.bundle.min.js / bootstrap.bundle.js, os quais contém Popper.js para o popover funcionar.
  • Popovers precisam do plugin tooltip, como sua dependência;
  • Se você está montando o JavaScript a partir da fonte, vai precisar do util.js;
  • Popovers são opcionais por motivos de desempenho, então, você deve inciá-lo, por conta própria;
  • Atributos title e content vazios nunca vão ser mostrados em um popover;
  • Declare container: 'body' para evitar problemas de renderização, em componentes mais complexos (como nos grupos de inputs ou botões);
  • Acionar popovers em elementos ocultos não funciona;
  • Popovers em elementos .disabled ou disabled devem ser acionados em um elemento pai;
  • Quando acionados por âncoras que envolvem várias linhas, os popovers serão centralizados entre a largura total das âncoras. Use white-space: nowrap; em seus <a>, para evitar este comportamento.
  • Popovers devem ser ocultos, antes que seus elementos correspondentes sejam removidos do DOM.

Continue lendo, para ver como popovers funcionam, em alguns exemplos.

Ative popovers, em qualquer lugar.

Uma maneira de inicializar todos popovers, em uma página, seria selecioná-los por seus atributos data-toggle:

$(function () {
  $('[data-toggle="popover"]').popover()
})

Usando o parâmetro container.

Quando você tem alguns estilos em um elemento pai que interfere no popover, você vai querer especificar um container personalizado para que, pelo contrário, o HTML do popover apareça dentro do elemento.

$(function () {
  $('.popover-exemplo').popover({
    container: 'body'
  })
})

Demonstração

<button type="button" class="btn btn-lg btn-danger" data-toggle="popover" title="Título do popover" data-content="Aqui vai algum tipo de conteúdo. Muito da hora, né?!">Clique para ver o popover</button>

As quatro direções

Quatro opções de direção estão disponíveis: top, right, bottom e left.

<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="top" data-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
  Popover na parte superior
</button>

<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="right" data-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
  Popover na direita
</button>

<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="bottom" data-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
  Popover na parte inferior
</button>

<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="left" data-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
  Popover na esquerda
</button>

Dispensar no próximo clique

Use o gatilho focus para dispensar popovers, no próximo clique do usuário, em um elemento diferente do qual ativou o popover.

Marcação HTML necessária para dispensar, no próximo clique.

Para um comportamento cross-browser e cross-platform, adequado, você deve usar a tag <a>, mas não <button>. Além do mais, você deve usar o atributo tabindex.

Popover dispensável 
<a tabindex="0" class="btn btn-lg btn-danger" role="button" data-toggle="popover" data-trigger="focus" title="Popover dispensável" data-content="Aqui vai algum tipo de conteúdo. Muito da hora, né?!">Popover dispensável</a>
$('.popover-dismiss').popover({
  trigger: 'focus'
})

Elementos desativados

Elementos com o atributo disabled não são interativos, significando que usuários não podem passar o mouse sobre eles ou clicar para acionar um popover ou tooltip. Como uma forma de contornar a situação, você vai querer acionar o popover a partir de um elemento pai <div> ou <span> e sobrescrever o pointer-eventer, no elemento desativado.

Para acionadores de popovers desativados, você também podem preferir usar data-trigger="hover" para que o popover apareça como um feedback visual imediato para seus usuários, já que eles esperam não ter que clicar em um elemento desativado.

<span class="d-inline-block" data-toggle="popover" data-content="Popover desativado">
  <button class="btn btn-primary" style="pointer-events: none;" type="button" disabled>Botão desativado</button>
</span>

Modo de uso

Ative popovers, via JavaScript:

$('#exemplo').popover(options)

Parâmetros

Parâmetros podem ser passados via atributos data ou JavaScript. No caso de atributos data, anexe o nome do parâmetro ao prefixo data-, como em data-animation="".

Nome Tipo Padrão Descrição
animation booleano true Aplica um transição fade CSS, no popover.
container string | elemento | false false

Anexa o popover, em um elemento específico. Este parâmetro é, particularmente, útil porque permite você posiciona o popover, no fluxo do documento, perto do elemento gatilho. Isso vai evitar que o popover flutue para longe do elemento gatilho, durante redimensionamento de janela. Exemplo de uso: container: 'body'.
content string | elemento | função ''

Valor padrão do conteúdo, se o atributo data-content não está presente.

Se uma função é provida, ela vai ser invocada com sua referência this definida no elemento que o popover é anexado.
delay number | objeto 0

Atraso na hora de exibir ou ocultar o popover, em ms. Não se aplica ao tipo de acionamento manual.

Se um número é provido, o atraso é aplicado tanto em exibição, quanto em ocultação.

A estrutura do objeto é: delay: { "show": 500, "hide": 100 }
html booleano false Coloque HTML, dentro do popover. Se falso, o método jQuery text será usado para inserir conteúdo no DOM. Use texto, se você está preocupado com ataques XSS.
placement string | função 'right'

Define como posicionar o popover (auto, top, botton, left ou right). Quando auto é definido, ele vai reorientar o popover, dinamicamente.

Quando uma função é usada para determinar o posicionamento, ela é invocada com o nó DOM do popover, como seu primeiro argumento e aciona o nó DOM como o segundo argumento. O contexto this é definido na instância popover.
selector string | false false Se um seletor é provido, objetos popover serão delegados a alvos específicos. Na prática, isso é usado para permitir um conteúdo HTML dinâmico ter popover. Veja isto e um exemplo informativo.
template string '<div class="popover" role="tooltip"><div class="arrow"></div><h3 class="popover-header"></h3><div class="popover-body"></div></div>'

HTML base para criar um popover.

O title do popover será injetado em um .popover-header.

O content do popover será injetado em um .popover-body.

O .arrow se tornará a flecha do popover.

O elemento pai mais externo deve receber a classe .popover.
title string | elemento | função ''

Valor padrão para o título, se o atributo title não está presente.

Se uma função é provida, ela vai ser invocada com sua referência this definida no elemento que o popover é anexado.
trigger string 'click' Define como o popover é acionado - clique | hover | focus | manual. Você pode passar vários acionadores, separando eles com espaço. No entanto, manual não pode ser passado com outros acionadores.
offset number | string 0 Define o deslocamento do popover, em relação a seu alvo. Para mais informação, leia a documentação offset do Popper.js.
fallbackPlacement string | array 'flip' Permite especificar qual posição Popper vai usar, em fallback. Para mais informação leia a documentação de comportamento do Popper.js.
boundary string | elemento 'scrollParent' Limite de transbordamento do popover. Aceita os valores 'viewport', 'window', 'scrollParent' ou uma referência HTMLElement (apenas JavaScript). Para mais informação, leia a documentação preventOverflow do Popper.js.

Atributos data para popovers individuais

Parâmetros para popovers individuais podem ser, opcionalmente, especificados usando atributos data, como explicado acime.

Métodos

Métodos é transições assíncronas

Todos métodos API são assíncronos e iniciam a transição. Eles retornam ao invocador, assim que a transição é iniciada, mas que ela finalize. Além do mais, uma chamada de método em um componente transicionando é ignorada.

Veja nossa documentação JavaScript, para mais informação.

$().popover(options)

Inicializa popovers em uma coleção de elementos.

.popover('show')

Revela o popover de um elemento. Retorna ao invocador, antes do popover ter sido exibido, de fato (antes do evento shown.bs.popover ocorrer). Isto é considerado um acionamento “manual” do popover. Popovers, os quais possuem atributos title e content vazios, nunca são exibidos.

$('#elemento').popover('show')

.popover('hide')

Esconde o popover de um elemento. Retorna ao invocador, antes do popover ter sido escondido, de fato (antes do evento hidden.bs.popover ocorrer). Isto é considerado um acionamento “manual” do popover.

$('#elemento').popover('hide')

.popover('toggle')

Alterna a visibilidade do popover de um elemento. Retorna ao invocador, antes do popover ter sido escondido ou exibido, de fato (antes dos eventos shown.bs.popover e hidden.bs.popover ocorrerem). Isto é considerado um acionamento “manual” do popover.

$('#elemento').popover('toggle')

.popover('dispose')

Esconde e destrói o popover de um elemento. Popovers que usam delegação (são criados usando o parâmetro selector), não podem ser destruídos individualmente, em elementos gatilhos descendentes.

$('#elemento').popover('dispose')

.popover('enable')

Dá ao popover de um elemento a habildiade de ser exibido. Ativado por padrão.

$('#elemento').popover('enable')

.popover('disable')

Retira a habilidade do popover de um elemento de ser exibido. O popover só poderá ser exibido, se este método for reativado.

$('#elemento').popover('disable')

.popover('toggleEnabled')

Alterna a habilidade do popover de um elemento ser exibido ou oculto.

$('#elemento').popover('toggleEnabled')

.popover('update')

Atualiza a posição do popover de um elemento.

$('#elemento').popover('update')

Eventos

Evento Descrição
show.bs.popover Este evento é acionado, imediatamente, quando o método show é invocado.
shown.bs.popover Este evento é acionado quando o popover se torna visível ao usuário (espera as transições CSS serem finalizadas).
hide.bs.popover Este evento é acionado, imediatamente, quando o método hide é invocado.
hidden.bs.popover Este evento é acionado quando o popover não está mais oculto ao usuário (espera as transições CSS serem finalizadas).
inserted.bs.popover Este evento é acionado depois do evento show.bs.popover, quando o template do popover é adicionado ao DOM. 
$('#meuPopover').on('hidden.bs.popover', function () {
  // Faça algo, aqui…
})