Skip to main content Skip to docs navigation

Tooltips

Documentación y ejemplos para agregar tooltips de Bootstrap personalizados con CSS y JavaScript usando CSS3 para animaciones y data-bs-attributes para el almacenamiento local de títulos.

Descripción general

Cosas que debes saber al usar el complemento de tooltip:

  • Los tooltips se basan en la biblioteca de terceros Popper para el posicionamiento. Debes incluir popper.min.js antes de bootstrap.js o usar bootstrap.bundle.min.js / bootstrap.bundle.js que contiene Popper para que los tooltips funcionen!
  • Los tooltips no están habilitados por motivos de rendimiento, por lo que debes inicializarlos tú mismo.
  • Los tooltips con títulos de longitud cero nunca se muestran.
  • Especifica container: 'body' para evitar problemas de representación en componentes más complejos (como nuestros input groups, button groups, etc.).
  • La activación de tooltips en elementos ocultos no funcionará.
  • Los tooltips para los elementos .disabled o disabled deben activarse en un elemento contenedor.
  • Cuando se activa desde hipervínculos que abarcan varias líneas, el tooltip se centrará. Usa white-space: nowrap; en tus <a>s para evitar este comportamiento.
  • Los tooltips deben ocultarse antes de que sus elementos correspondientes se eliminen del DOM.
  • Los tooltips se puede activar gracias a un elemento dentro del shadow DOM.
De forma predeterminada, este componente utiliza el desinfectante de contenido incorporado, que elimina los elementos HTML que no están permitidos explícitamente. Consulta la sección de desinfección en nuestra documentación de JavaScript para obtener más detalles.
El efecto de animación de este componente depende de la media query prefers-reduced-motion. Consulta la sección de movimiento reducido de nuestra documentación de accesibilidad.

¿Lo tienes? Genial, veamos cómo funcionan con algunos ejemplos.

Ejemplo: habilita los tooltips en todas partes

Una forma de inicializar todos los tooltips en una página sería seleccionarlos por su atributo data-bs-toggle:

var tooltipTriggerList = Array.prototype.slice.call(document.querySelectorAll('[data-bs-toggle="tooltip"]'))
var tooltipList = tooltipTriggerList.map(function (tooltipTriggerEl) {
  return new bootstrap.Tooltip(tooltipTriggerEl)
})

Ejemplos

Pasa el cursor sobre los enlaces a continuación para ver sus tooltips:

Texto placeholder para demostrar algunos enlaces en línea con tooltips. Esto ahora es solo un relleno. Contenido colocado aquí solo para imitar la presencia de texto real. Y todo eso solo para darte una idea de cómo se vería el tooltip cuando se usa en situaciones del mundo real. Espero que ahora hayas visto cómo este tooltip en los enlaces puede funcionar en la práctica, una vez que los uses en tu propio sitio web o proyecto.

Pasa el cursor sobre los botones a continuación para ver las cuatro direcciones de tooltips: top, right, bottom, y left. Las direcciones se reflejan cuando se usa Bootstrap en RTL.

<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="top" title="Tooltip superior">
  Tooltip superior
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="right" title="Tooltip derecho">
  Tooltip derecho
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="bottom" title="Tooltip inferior">
  Tooltip inferior
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="left" title="Tooltip izquierdo">
  Tooltip izquierdo
</button>

Y con HTML personalizado:

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

Con un SVG:

Sass

Variables

$tooltip-font-size:                 $font-size-sm;
$tooltip-max-width:                 200px;
$tooltip-color:                     $white;
$tooltip-bg:                        $black;
$tooltip-border-radius:             $border-radius;
$tooltip-opacity:                   .9;
$tooltip-padding-y:                 $spacer * .25;
$tooltip-padding-x:                 $spacer * .5;
$tooltip-margin:                    0;

$tooltip-arrow-width:               .8rem;
$tooltip-arrow-height:              .4rem;
$tooltip-arrow-color:               $tooltip-bg;

Uso

El complemento de tooltip genera contenido y marcado a pedido y, de forma predeterminada, coloca tooltips después de tu elemento desencadenante.

Activa el tooltip a través de JavaScript:

var exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, options)
Desbordamiento auto y scroll

La posición del tooltip intenta cambiar automáticamente cuando un contenedor padre tiene overflow: auto o overflow: scroll como nuestro .table-responsive, pero aún mantiene el posicionamiento de la ubicación original. Para resolver esto, establece la opción boundary (para el modificador flip usando la opción popperConfig) a cualquier HTMLElement para sobrescribir el valor predeterminado, 'clippingParents', como document.body:

var exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, {
  boundary: document.body // o document.querySelector('#boundary')
})

Marcado

El marcado requerido para un tooltip es solo un atributo data y un title en el elemento HTML que deseas tener un tooltip. El marcado generado de un tooltip es bastante simple, aunque requiere una posición (de forma predeterminada, establecida en top por el complemento).

Hacer que el tooltip funcione para los usuarios de teclados y tecnología de asistencia

Solo debes agregar el tooltip a los elementos HTML que tradicionalmente se pueden enfocar con el teclado y son interactivos (como enlaces o controles de formulario). Aunque los elementos HTML arbitrarios (como <span>s) se pueden enfocar agregando el atributo tabindex="0", esto agregará tabulaciones potencialmente molestas y confusas en elementos no interactivos para usuarios de teclado, y actualmente la mayoría de las tecnologías de asistencia no anuncian el tooltip en esta situación. Además, no confíes únicamente en hover como el disparador de tu tooltip, ya que esto hará que tu tooltip sea imposible de activar para los usuarios del teclado.

<!-- HTML a escribir -->
<a href="#" data-bs-toggle="tooltip" title="Algo de texto tooltip!">Pasa el puntero de mouse aquí</a>

<!-- Marcado generado por el complemento -->
<div class="tooltip bs-tooltip-top" role="tooltip">
  <div class="tooltip-arrow"></div>
  <div class="tooltip-inner">
    Algo de texto tooltip!
  </div>
</div>

Elementos deshabilitados

Los elementos con el atributo disabled no son interactivos, lo que significa que los usuarios no pueden enfocarlos, desplazarlos o hacer clic en ellos para activar un tooltip (o un popover). Como solución alternativa, querrás activar el tooltip desde un contenedor <div> o <span>, idealmente enfocable desde el teclado usando tabindex="0".

<span class="d-inline-block" tabindex="0" data-bs-toggle="tooltip" title="Tooltip deshabilitado">
  <button class="btn btn-primary" type="button" disabled>Botón deshabilitado</button>
</span>

Opciones

Las opciones se pueden pasar a través de atributos de datos o JavaScript. Para los atributos de datos, agrega el nombre de la opción a data-bs-, como en data-bs-animation="". Asegúrate de cambiar el tipo de caso del nombre de la opción de camelCase a kebab-case al pasar las opciones a través de atributos de datos. Por ejemplo, en lugar de usar data-bs-customClass="beautifier", usa data-bs-custom-class="beautifier".

Ten en cuenta que, por razones de seguridad, las opciones sanitize, sanitizeFn y allowList no se pueden proporcionar mediante atributos de datos.
Nombre Tipo Por defecto Descripción
animation boolean true Aplicar una transición de fundido CSS al tooltip
container string | element | false false

Agrega el tooltip a un elemento específico. Ejemplo: container: 'body'. Esta opción es particularmente útil porque te permite colocar el tooltip en el flujo del documento cerca del elemento de activación, lo que evitará que el tooltip se aleje del elemento de activación durante el cambio de tamaño de la ventana.

delay number | object 0

Retraso en mostrar y ocultar el tooltip (ms): no se aplica al tipo de activación manual

Si se proporciona un número, se aplica un retraso tanto para ocultar como para mostrar

La estructura del objeto es: delay: { "show": 500, "hide": 100 }

html boolean false

Permitir HTML en el tooltip.

Si es true, las etiquetas HTML en el title del tooltip se renderizarán en el tooltip. Si es false, la propiedad innerText se usará para insertar contenido en el DOM.

Usa texto si te preocupan los ataques XSS.

placement string | function 'top'

Cómo colocar el tooltip - auto | top | bottom | left | right.
Cuando se especifica auto, reorientará dinámicamente el tooltip.

Cuando se usa una función para determinar la ubicación, se llama con el nodo DOM del tooltip como primer argumento y el nodo DOM del elemento desencadenante como segundo. El contexto this se establece en la instancia del tooltip.

selector string | false false Si se proporciona un selector, los objetos de tooltips se delegarán a los objetivos especificados. En la práctica, esto también se usa para aplicar tooltips a elementos DOM agregados dinámicamente (compatible con jQuery.on). Consulta this y un ejemplo informativo.
template string '<div class="tooltip" role="tooltip"><div class="tooltip-arrow"></div><div class="tooltip-inner"></div></div>'

HTML base para usar al crear el tooltip.

El title del tooltip se insertará en .tooltip-inner.

.tooltip-arrow se convertirá en la flecha del tooltip.

El elemento envolvente más externo debe tener la clase .tooltip y role="tooltip".

title string | element | function ''

Valor de título predeterminado si el atributo title no está presente.

Si se proporciona una función, se llamará con su referencia this establecida en el elemento al que se adjunta el tooltip.

trigger string 'hover focus'

Cómo se activa el tooltip: click | hover | focus | manual. Puedes pasar varios disparadores; sepáralas con un espacio.

'manual' indica que el tooltip se activará mediante programación a través de los métodos .show(), .hide() y .toggle(); este valor no se puede combinar con ningún otro disparador.

'hover' por sí solo, dará como resultado un tooltip que no se puede activar a través del teclado, y solo debe usarse si existen métodos alternativos para transmitir la misma información a los usuarios del teclado.

fallbackPlacements array ['top', 'right', 'bottom', 'left'] Define las ubicaciones de respaldo proporcionando una lista de ubicaciones en un array (en orden de preferencia). Para obtener más información, consulta documentos de comportamiento de Popper
boundary string | element 'clippingParents' Límite de restricción de desbordamiento del tooltip (se aplica solo al modificador preventOverflow de Popper). De forma predeterminada, es 'clippingParents' y puede aceptar una referencia HTMLElement (solo a través de JavaScript). Para obtener más información, consulta los detectOverflow docs de Popper.
customClass string | function ''

Agrega clases al tooltip cuando se muestre. Ten en cuenta que estas clases se agregarán además de las clases especificadas en el template. Para agregar varias clases, sepáralas con espacios: 'class-1 class-2'.

También puedes pasar una función que debería devolver una sola cadena que contenga nombres de clases adicionales.

sanitize boolean true Habilita o deshabilita la desinfección. Si está activado, las opciones 'template' y 'title' se desinfectarán. Consulta la sección de desinfección en nuestra documentación de JavaScript.
allowList object Default value Objeto que contiene atributos y etiquetas permitidas
sanitizeFn null | function null Aquí puedes proporcionar tu propia función de desinfección. Esto puede ser útil si prefieres usar una biblioteca dedicada para realizar la desinfección.
offset array | string | function [0, 0]

Desplazamiento del tooltip en relación con su destino. Puedes pasar una cadena en atributos de datos con valores separados por comas como: data-bs-offset="10,20"

Cuando se usa una función para determinar el desplazamiento, se llama con un objeto que contiene la ubicación del popper, la referencia y los rects del popper como su primer argumento. El nodo DOM del elemento desencadenante se pasa como segundo argumento. La función debe devolver un array con dos números: [skidding, distance].

Para obtener más información, consulta los documentos de compensación de Popper.

popperConfig null | object | function null

Para cambiar la configuración predeterminada de Popper de Bootstrap, consulta Configuración de Popper.

Cuando se usa una función para crear la configuración Popper, se llama con un objeto que contiene la configuración Popper predeterminada de Bootstrap. Te ayuda a usar y fusionar el valor predeterminado con tu propia configuración. La función debe devolver un objeto de configuración para Popper.

Atributos de datos para tooltips individuales

Las opciones para tooltips individuales se pueden especificar alternativamente mediante el uso de atributos de datos, como se explicó anteriormente.

Uso de la función con popperConfig

var tooltip = new bootstrap.Tooltip(element, {
  popperConfig: function (defaultBsPopperConfig) {
    // var newPopperConfig = {...}
    // usa defaultBsPopperConfig si es necesario...
    // return newPopperConfig
  }
})

Métodos

Transiciones y métodos asíncronos

Todos los métodos de la API son asincrónicos e inician una transition. Regresan al lugar donde se realizó la llamada tan pronto como se inicia la transición, pero antes de que finalice. Además, se ignorará una llamada de método en un componente en medio de una transición.

Consulte nuestra documentación de JavaScript para obtener más información.

show

Revela el tooltip de un elemento. Regresa al punto de la llamada antes de que se haya mostrado realmente la tooltip (es decir, antes de que ocurra el evento shown.bs.tooltip). Esto se considera una activación “manual” del tooltip. El tooltip con títulos de longitud cero nunca se muestra.

tooltip.show()

hide

Oculta el tooltip de un elemento. Regresa al punto de la llamada antes de que la tooltip se haya ocultado (es decir, antes de que ocurra el evento hidden.bs.tooltip). Esto se considera una activación “manual” del tooltip.

tooltip.hide()

toggle

Alterna el tooltip de un elemento. Regresa al punto de la llamada antes de que la tooltip se haya mostrado u ocultado (es decir, antes de que ocurra el evento shown.bs.tooltip o hidden.bs.tooltip). Esto se considera una activación “manual” del tooltip.

tooltip.toggle()

dispose

Oculta y destruye el tooltip de un elemento (elimina los datos almacenados en el elemento DOM). El tooltip que utiliza la delegación (que se crea mediante la opción selector) no se puede destruir individualmente en los elementos desencadenantes descendientes.

tooltip.dispose()

enable

Le da al tooltip de un elemento la capacidad de mostrarse. El tooltip está habilitada de forma predeterminada.

tooltip.enable()

disable

Elimina la capacidad de mostrar el tooltip de un elemento. El tooltip solo se podrá mostrar si se vuelve a habilitar.

tooltip.disable()

setContent

Brinda una forma de cambiar el contenido del tooltip después de su inicialización.

tooltip.setContent({ '.tooltip-inner': 'another title' })
El método setContent acepta un argumento object, donde cada clave de propiedad es un selector de string válido dentro de la plantilla emergente, y cada valor de propiedad relacionado puede ser string | element | function | null

toggleEnabled

Alterna la capacidad de mostrar u ocultar el tooltip de un elemento.

tooltip.toggleEnabled()

update

Actualiza la posición del tooltip de un elemento.

tooltip.update()

getInstance

Método estático que te permite obtener la instancia del tooltip asociado con un elemento DOM

var exampleTriggerEl = document.getElementById('example')
var tooltip = bootstrap.Tooltip.getInstance(exampleTriggerEl) // Devuelve una instancia del tooltip de Bootstrap

getOrCreateInstance

Método estático que te permite obtener la instancia de tooltip asociado con un elemento DOM, o crear uno nuevo en caso de que no se haya inicializado

var exampleTriggerEl = document.getElementById('example')
var tooltip = bootstrap.Tooltip.getOrCreateInstance(exampleTriggerEl) // Devuelve una instancia del tooltip de Bootstrap

Eventos

Tipo de evento Descripción
show.bs.tooltip Este evento se activa inmediatamente cuando se llama al método de instancia show.
shown.bs.tooltip Este evento se activa cuando el tooltip se hace visible para el usuario (esperará a que se completen las transiciones CSS).
hide.bs.tooltip Este evento se activa inmediatamente cuando se llama al método de instancia hide.
hidden.bs.tooltip Este evento se activa cuando el tooltip ha terminado de ocultarse para el usuario (esperará a que se completen las transiciones CSS).
inserted.bs.tooltip Este evento se activa después del evento show.bs.tooltip cuando el template de tooltip se ha agregado al DOM.
var myTooltipEl = document.getElementById('myTooltip')
var tooltip = new bootstrap.Tooltip(myTooltipEl)

myTooltipEl.addEventListener('hidden.bs.tooltip', function () {
  // hacer algo...
})

tooltip.hide()