Tooltips

Documentação e exemplos para criar tooltips Bootstrap personalizados com CSS e JavaScript, usando CSS3 para animações e atributos data para armazenamento local de título.

Visão geral

Oquê saber, quando usar o plugin tooltip:

  • Tooltips dependem da biblioteca externa Popper.js, para posicionamento;
    • Você deve colocar popper.min.js antes do bootstrap.js ou usar bootstrap.bundle.min.js / bootstrap.bundle.js, os quais já possuem Popper.js.
  • Se você está montando nosso JavaScript a partir da fonte, vai precisar do util.js;
  • Tooltips são opcionais por questões de desempenho, então, você deve inicializá-lo por conta própria;
  • Tooltips com title sem valor, nunca serão exibidos;
  • Declare container: 'body' para evitar problemas de renderização, em componentes mais complexos (como grupos de botões ou input);
  • Acionar tooltips em elementos ocultos não é possível;
  • Tooltips para elementos .disabled ou disabled devem ser acionados em um elemento pai;
  • Quando acionados a partir de âncoras que envolvem várias linhas, tooltips são centralizados;
    • Use white-space: nowrap; nos <a> para evitar este comportamento.
  • Tooltips devem ser escondidos, antes que seus elementos correspondentes sejam removidos do DOM.

Pegou tudo isso? Perfeito! Vamo ver como isso funciona, em algums exemplos.

Ative tooltips, em qualquer lugar.

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

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

Exemplos

Passe o mouse sobre os links abaixo, para ver tooltips:

Et sit consectetur laboriosam accusamus. Ipsam amet aut. Exercitationem quasi accusantium et et ut. Alias quam sed. Omnis minus ad repellendus. Et sit consectetur laboriosam accusamus. Ipsam amet aut. Exercitationem quasi accusantium et et ut. Alias quam sed. Omnis minus ad repellendus. Et sit consectetur laboriosam accusamus. Ipsam amet aut. Exercitationem quasi accusantium et et ut. Alias quam sed. Omnis minus ad repellendus. Et sit consectetur laboriosam accusamus. Ipsam amet aut. Exercitationem quasi accusantium et et ut. Alias quam sed. Omnis minus ad repellendus. Et sit consectetur laboriosam accusamus. Ipsam amet aut. Exercitationem quasi accusantium et et ut. Alias quam sed. Omnis minus ad repellendus.

Passe o mouse sobre os botões abaixo para ver as quatro direções de tooltip, possíveis: top, right, bottom e left.

<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="top" title="Tooltip na parte superior">
  Tooltip na parte superior
</button>
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="right" title="Tooltip na direita">
  Tooltip na direita
</button>
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="bottom" title="Tooltip na parte inferior">
  Tooltip na parte inferior
</button>
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="left" title="Tooltip na esquerda">
  Tooltip na esquerda
</button>

Ou um exemplo de tooltip que usa HTML, no seu conteúdo.

<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-html="true" title="<em>Tooltip</em> <u>with</u> <b>HTML</b>">
  Tooltip com HTML
</button>

Modo de uso

O plugin tooltip gera conteúdo e marcação sob demanda e, por padrão, posiciona tooltips depois de seus elementos acionadores.

Acione o tooltip via JavaScript:

$('#exemplo').tooltip(options)
Overflow auto e scroll

O tooltip tenta, automaticamente, mudar sua posição quando um container pai tem overflow: auto ou overflow: scroll (como acontece em .table-responsive), mas ainda assim preserva o espaço do posicionalmento original. Para resolver, altere o parâmetro boundary para qualquer coisa que não o valor padrão ('scrollParent'), como 'window'.

$('#example').tooltip({ boundary: 'window' })

Marcação

A marcação necessária para um tooltip só são os atributos data e title, no elemento HTML que você deseja ter um tooltip. A marcação gerada de um tooltip é bem simples, mas precisa de posicionamento (definido como top, por padrão).

Fazendo tooltips funcionarem para usuários de teclado e tecnologias assistivas

Você só deveria colocar tooltips em elementos HTML que são, tradicionalmente, focáveis com teclado e interativos (como links e campos de formulário). Apesar de elementos HTML genéricos (como <span>) poderem se tornar focáveis, adicionando o atributo tabindex="0", isso vai criar potenciais tabulações irritantes e confusas, em elementos não interativos para usuários de teclado. Além disso, a maioria das tecnologias assistivas, atualmente, não transmitem o tooltip, nesta situação.

Além do mais, não dependa só no hover como acionador para seu tooltip, já que isso vai fazer seus tooltips impossíveis de serem acionados por usuários de teclado.

<!-- HTML a se escrever -->
<a href="#" data-toggle="tooltip" title="Some tooltip text!">Passe o mouse em mim</a>

<!-- Marcação gerada, pelo pluguin -->
<div class="tooltip bs-tooltip-top" role="tooltip">
  <div class="arrow"></div>
  <div class="tooltip-inner">
    Algum texto de tooltip
  </div>
</div>

Elementos desativados

Elementos com o atributo disabled não são interativos, significando que usuários não podem focar, clicar ou passar o mouse sobre eles para acionar o tooltip (ou popover). Como uma forma de contornar a situação, você vai querer acionar o tooltip a partir de um elemento pai <div> ou <span>, idealmente, fazendo-os serem focáveis com tabindex="0" e sobrescrever a pointer-events, no elemento desativado.

<span class="d-inline-block" tabindex="0" data-toggle="tooltip" title="Tooltip em elemento desativado">
  <button class="btn btn-primary" style="pointer-events: none;" type="button" disabled>Botão desativado</button>
</span>

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 Description
animation booleano true Aplica uma transição CSS fade, no tooltip.
container string | elemento | false false

Anexa o tooltip ao elemento específico. Este parâmetro é, particularmente, útil porque permite você posicionar o tooltip no fluxo do documento, perto do elemento gatilho (o que vai evitar que o tooltip flutue para longe do elemento gatilho, no redimensionamento de página). Exemplo: container: 'body'.
delay number | objeto 0

Atraso na exibição e ocultação do tooltip, em ms. Não se aplica ao tipo de acionamento manual.

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

A estrutura do objeto é: delay: { "show": 500, "hide": 100 }
html booleano false

Permite HTML, no tooltip.

Se declarado como true, tags HTML no título do tooltip serão renderizadas. Se definido como false, o método jQuery text será usado para inserir conteúdo no DOM.
placement string | função 'top'

Define como posicionar o tooltip (auto, top, bottom, left e right). Quando auto é especificado, ele vai reorientar o tooltip, automaticamente.

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

HTML base para criação de tooltip.

O title do tooltip será injetado no .tooltip-inner.

A .arrow se tornará a flecha do tooltip.

O elemento pai mais exeterno deve ter a classe .tooltip e atributo role="tooltip".
title string | elemento | função ''

Define o título padrão, se o valor do atributo title não está presente.

Se uma função é declarada, ela será invocada com sua referência this definida para o elemento que o tooltip está anexado.
trigger string 'hover focus'

Define como o tooltip é acionado (click, hover, focus e manual). Você pode passar vários acionadores, separando-os com espaço.

'manual' indica que o tooltip será acionado, programaticamente, pelos métodos .tooltip('show'), .tooltip('hide') e .tooltip('toggle'). Este valor não pode ser combinado com os outros acionadores.

Usar só o 'hover' vai resultar em tooltips que não podem ser acionados por teclado e só devem ser usados se métodos alternativos, para transmitir a mesma informação para usuários de teclado, existem.
offset number | string 0 Deslocamento do tooltip, em relação ao seu alvo. Para mais informação, leia a documentação offset do Popper.js.
fallbackPlacement string | array 'flip' Permite especificar qual posição o Popper vai usar, em caso de fallback. Para mais informação, leia a documentação de comportamento do Popper.js.
boundary string | elemento 'scrollParent' Define o limite de transbordamento do tooltip. 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 tooltips individuais

Parâmetros para tooltips individuais podem, opcionalmente, serem especificados usando atributos data, como mostrado acima.

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.

$().tooltip(options)

Anexa um manipulador tooltip, em uma coleção de elementos.

.tooltip('show')

Revela o tooltip de um elemento. Retorna ao invocador, antes do tooltip ter sido exibido, de fato (antes do evento shown.bs.tooltip ocorrer). Isto é considerado um acionamento “manual” do tooltip. Tooltips com title vazios, nunca são mostrados.

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

.tooltip('hide')

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

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

.tooltip('toggle')

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

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

.tooltip('dispose')

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

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

.tooltip('enable')

Dá a habilide de se exibir ao tooltip de um elemento. Ativado por padrão.

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

.tooltip('disable')

Remove a habilidade de se exibir do tooltip de um elemento. O tooltip só será capaz de ser exibido se isto for reativado.

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

.tooltip('toggleEnabled')

Alterna a capacidade do tooltip de um elemento de ser exibido ou oculto.

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

.tooltip('update')

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

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

Eventos

Evento Descrição
show.bs.tooltip Este evento é acionado quando o método show é invocado.
shown.bs.tooltip Este evento é acionado quando o tooltip foi exibido ao usuário (espera as transições CSS finalizarem).
hide.bs.tooltip Este evento é acionado, imediatamente, quando o método hide é invocado.
hidden.bs.tooltip Este evento é acionado quando o tooltip acaba de se ocultar do usuário (espera as transições CSS finalizarem).
inserted.bs.tooltip Este evento é acionado depois do evento show.bs.tooltip, quando o template tooltip foi adicionado ao DOM. 
$('#meuTooltip').on('hidden.bs.tooltip', function () {
  // Faça algo, aqui…
})