Saltar al contenido principal Saltar a la navegación de la documentación

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

Descripción general

Cosas que debes saber al usar el complemento de tooltips:

  • Los tooltips se basan en la biblioteca de terceros Popper para su posicionamiento. Debes incluir popper.min.js antes de bootstrap.js, o utiliza un bootstrap.bundle.min.js que contenga Popper.
  • Los tooltips son opcionales 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 renderizado en componentes más complejos (como nuestros grupos de entrada, grupos de botones, etc.).
  • Activar tooltips en elementos ocultos no funcionará.
  • Los tooltips para los elementos .disabled o disabled deben activarse en un elemento contenedor.
  • Cuando se activan desde hipervínculos que abarcan varias líneas, los tooltips se centrarán. Utiliza 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 pueden activar gracias a un elemento dentro de un DOM oculto.

¿Tienes todo eso? Genial, veamos cómo funcionan con algunos ejemplos.

De forma predeterminada, este componente utiliza el desinfectante de contenido integrado, que elimina cualquier elemento HTML que no esté permitido explícitamente. Consulta la sección de desinfectante 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.

Ejemplos

Habilitar tooltips

Como se mencionó anteriormente, debes inicializar los tooltips antes de poder usarlos. Una forma de inicializar todos los tooltips en una página sería seleccionarlos por su atributo data-bs-toggle, así:

const tooltipTriggerList = document.querySelectorAll('[data-bs-toggle="tooltip"]')
const tooltipList = [...tooltipTriggerList].map(tooltipTriggerEl => new bootstrap.Tooltip(tooltipTriggerEl))

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

Texto de marcador de posición para demostrar algunos enlaces en línea con tooltips. Esto ahora es sólo un relleno. El contenido colocado aquí solo para imitar la presencia de texto real. Y todo eso sólo para darle una idea de cómo se vería la tooltips cuando se usa en situaciones del mundo real. Esperamos que ahora hayas visto cómo estas sugerencias sobre enlaces pueden funcionar en la práctica una vez que los utilices en tu propio sitio o proyecto.

html
<p class="muted">Placeholder text to demonstrate some <a href="#" data-bs-toggle="tooltip" data-bs-title="Default tooltip">inline links</a> with tooltips. This is now just filler, no killer. Content placed here just to mimic the presence of <a href="#" data-bs-toggle="tooltip" data-bs-title="Another tooltip">real text</a>. And all that just to give you an idea of how tooltips would look when used in real-world situations. So hopefully you've now seen how <a href="#" data-bs-toggle="tooltip" data-bs-title="Another one here too">these tooltips on links</a> can work in practice, once you use them on <a href="#" data-bs-toggle="tooltip" data-bs-title="The last tip!">your own</a> site or project.</p>
Siéntete libre de utilizar title o data-bs-title en tu HTML. Cuando se usa title, Popper lo reemplazará automáticamente con data-bs-title cuando se renderice el elemento.

Tooltips personalizado

Agregado en v5.2.0

Puedes personalizar la apariencia de los tooltips usando variables CSS. Configuramos una clase personalizada con data-bs-custom-class="custom-tooltip" para definir el alcance de nuestra apariencia personalizada y usarla para sobrescribir una variable CSS local.

.custom-tooltip {
  --bs-tooltip-bg: var(--bd-violet-bg);
  --bs-tooltip-color: var(--bs-white);
}
html
<button type="button" class="btn btn-secondary"
        data-bs-toggle="tooltip" data-bs-placement="top"
        data-bs-custom-class="custom-tooltip"
        data-bs-title="This top tooltip is themed via CSS variables.">
  Custom tooltip
</button>

Direcciones

Coloca el cursor sobre los botones a continuación para ver las cuatro direcciones de tooltips: arriba, derecha, abajo e izquierda. Las instrucciones se reflejan cuando se usa Bootstrap en RTL.

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

Y con HTML personalizado agregado:

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

Con un SVG:

CSS

Variables

Agregado en v5.2.0

Como parte del enfoque de variables CSS en evolución de Bootstrap, los tooltips ahora usan variables CSS locales en .tooltip para mejorar la personalización en tiempo real. Los valores de las variables CSS se establecen a través de Sass, por lo que la personalización de Sass también es compatible.

--#{$prefix}tooltip-zindex: #{$zindex-tooltip};
--#{$prefix}tooltip-max-width: #{$tooltip-max-width};
--#{$prefix}tooltip-padding-x: #{$tooltip-padding-x};
--#{$prefix}tooltip-padding-y: #{$tooltip-padding-y};
--#{$prefix}tooltip-margin: #{$tooltip-margin};
@include rfs($tooltip-font-size, --#{$prefix}tooltip-font-size);
--#{$prefix}tooltip-color: #{$tooltip-color};
--#{$prefix}tooltip-bg: #{$tooltip-bg};
--#{$prefix}tooltip-border-radius: #{$tooltip-border-radius};
--#{$prefix}tooltip-opacity: #{$tooltip-opacity};
--#{$prefix}tooltip-arrow-width: #{$tooltip-arrow-width};
--#{$prefix}tooltip-arrow-height: #{$tooltip-arrow-height};

Variables Sass

$tooltip-font-size:                 $font-size-sm;
$tooltip-max-width:                 200px;
$tooltip-color:                     var(--#{$prefix}body-bg);
$tooltip-bg:                        var(--#{$prefix}emphasis-color);
$tooltip-border-radius:             var(--#{$prefix}border-radius);
$tooltip-opacity:                   .9;
$tooltip-padding-y:                 $spacer * .25;
$tooltip-padding-x:                 $spacer * .5;
$tooltip-margin:                    null; // TODO: remove this in v6

$tooltip-arrow-width:               .8rem;
$tooltip-arrow-height:              .4rem;
// fusv-disable
$tooltip-arrow-color:               null; // Deprecated in Bootstrap 5.2.0 for CSS variables
// fusv-enable

Uso

El complemento de tooltips genera contenido y marcado a pedido y, de forma predeterminada, coloca tooltips después de su elemento desencadenante. Activa el tooltips a través de JavaScript:

const exampleEl = document.getElementById('example')
const tooltip = new bootstrap.Tooltip(exampleEl, options)

Los tooltips intentan cambiar automáticamente las posiciones cuando un contenedor principal tiene overflow: auto o overflow: scroll, pero aún conservan el posicionamiento original. Establece boundary (opción) (para el modificador de inversión usando la opción popperConfig) a cualquier HTMLElement para sobrescribir el valor predeterminado, 'clippingParents', como document.body:

const tooltip = new bootstrap.Tooltip('#example', {
  boundary: document.body // or document.querySelector('#boundary')
})

Markup

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

Mantén los tooltips accesibles para los usuarios de teclados y tecnologías de asistencia agregándolos únicamente a elementos HTML que tradicionalmente son interactivos y enfocables mediante el teclado (como enlaces o controles de formulario). Si bien se pueden enfocar otros elementos HTML agregando tabindex="0", esto puede crear tabulaciones molestas y confusas en elementos no interactivos para los usuarios del teclado, y la mayoría de las tecnologías de asistencia actualmente no anuncian tooltips en esta situación. Además, no confíes únicamente en hover como activador de tooltips, ya que esto hará que sea imposible activarlo para los usuarios del teclado.
<!-- HTML to write -->
<a href="#" data-bs-toggle="tooltip" data-bs-title="Some tooltip text!">Hover over me</a>

<!-- Generated markup by the plugin -->
<div class="tooltip bs-tooltip-auto" role="tooltip">
  <div class="tooltip-arrow"></div>
  <div class="tooltip-inner">
    Some tooltip text!
  </div>
</div>

Elementos deshabilitados

Los elementos con el atributo disabled no son interactivos, lo que significa que los usuarios no pueden enfocarse, pasar el cursor o hacer clic en ellos para activar una tooltips (o ventana emergente). Como solución alternativa, querrás activar los tooltips desde un contenedor <div> o <span>, idealmente considerando al teclado usando tabindex="0".

html
<span class="d-inline-block" tabindex="0" data-bs-toggle="tooltip" data-bs-title="Disabled tooltip">
  <button class="btn btn-primary" type="button" disabled>Disabled button</button>
</span>

Opciones

Como las opciones se pueden pasar a través de atributos de datos o JavaScript, puedes agregar un nombre de opción a data-bs-, como en data-bs-animation="{value}". 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, utiliza data-bs-custom-class="beautifier" en lugar de data-bs-customClass="beautifier".

A partir de Bootstrap 5.2.0, todos los componentes admiten un atributo de datos experimental reservado data-bs-config que puede albergar datos simples de configuración del componente como una cadena JSON. Cuando un elemento tiene los atributos data-bs-config='{"delay":0, "title":123}' y data-bs-title="456", el valor final de title será 456 y los atributos de datos separados sobrescribirán los valores proporcionados en data-bs-config. Además, los atributos de datos existentes pueden albergar valores JSON como data-bs-delay='{"show":0,"hide":150}'.

El objeto de configuración final es el resultado combinado de data-bs-config, data-bs- y js object donde el último valor-clave dado sobrescribe los demás.

Ten en cuenta que, por motivos de seguridad, las opciones sanitize, sanitizeFn y allowList no se pueden proporcionar mediante atributos de datos.
Nombre Tipo Predeterminado Descripción
allowList object Valor predeterminado Objeto que contiene atributos y etiquetas permitidos.
animation boolean true Aplica una transición de desvanecimiento CSS a tooltips.
boundary string, element 'clippingParents' Límite de restricción de desbordamiento de tooltips (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 la documentación de detectOverflow de Popper.
container string, element, false false Agrega tooltips a un elemento específico. Ejemplo: container: 'body'. Esta opción es particularmente útil porque te permite colocar tooltips en el flujo del documento cerca del elemento desencadenante, lo que evitará que los tooltips se alejen del elemento desencadenante durante el cambio de tamaño de la ventana.
customClass string, function '' Agrega clases a tooltips cuando se muestran. Ten en cuenta que estas clases se agregarán además de cualquier clase especificada en la plantilla. Para agregar varias clases, sepárelas con espacios: 'class-1 class-2'. También puedes pasar una función que debería devolver una única cadena que contenga nombres de clases adicionales.
delay number, object 0 Tiempo de retraso en mostrar y ocultar la tooltips (ms): no se aplica al tipo de disparador 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 }.
fallbackPlacements array ['top', 'right', 'bottom', 'left'] Define ubicaciones alternativas proporcionando una lista de ubicaciones en una matriz (en orden de preferencia). Para obtener más información, consulta la documentación de comportamiento de Popper.
html boolean false Permitir HTML en tooltips. Si es true, las etiquetas HTML en el title de los tooltips se representarán en el tooltips. Si es false, la propiedad innerText se utilizará para insertar contenido en el DOM. Utiliza texto si te preocupan los ataques XSS.
offset array, string, function [0, 0] Desplazamiento de tooltips en relación con su objetivo. 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 rectificadores del popper como primer argumento. El nodo DOM del elemento desencadenante se pasa como segundo argumento. La función debe devolver una matriz con dos números: skidding, distance. Para obtener más información, consult la documentación de offset de Popper.
placement string, function 'top' Cómo posicionar tooltips: auto, top, bottom, left, right. Cuando se especifica auto , reorientará dinámicamente el tooltips. Cuando se utiliza una función para determinar la ubicación, se llama con el nodo DOM de tooltips como primer argumento y el nodo DOM del elemento desencadenante como segundo. El contexto this se establece en la instancia de tooltips.
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 de Popper, se llama con un objeto que contiene la configuración de Popper predeterminada de Bootstrap. Te ayuda a utilizar y fusionar el valor predeterminado con tu propia configuración. La función debe devolver un objeto de configuración para Popper.
sanitize boolean true Activa o desactiva la desinfección. Si se activan las opciones 'template', 'content' y 'title' se desinfectarán.
sanitizeFn null, function null Aquí puedes proporcionar tu propia función de desinfección. Esto puede resultar útil si prefieres utilizar una biblioteca dedicada para realizar la desinfección.
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 utiliza para aplicar tooltips a elementos DOM agregados dinámicamente (compatible con jQuery.on). Consulta este problema y un ejemplo informativo. Nota: el atributo title no debe usarse como selector.
template string '<div class="tooltip" role="tooltip"><div class="tooltip-arrow"></div><div class="tooltip-inner"></div></div>' HTML base para usar al crear tooltips. El title de tooltips se inyectará en .tooltip-inner. .tooltip-arrow se convertirá en la flecha del tooltips. El elemento contenedor más externo debe tener la clase .tooltip y role="tooltip".
title string, element, function '' El título del tooltips. Si se proporciona una función, se llamará con su referencia this establecida en el elemento al que está adjunto el popover.
trigger string 'hover focus' Cómo se activa el tooltips: click, hover, focus, manual. Puedes pasar varios factores desencadenantes; sepáralos con un espacio. 'manual' indica que el tooltips se activará mediante programación mediante los métodos .tooltip('show'), .tooltip('hide') y .tooltip('toggle'); este valor no se puede combinar con ningún otro activador. 'hover' por sí solo generará tooltips 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.

Atributos de datos para tooltips individuales

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

Usar la función con popperConfig

const tooltip = new bootstrap.Tooltip(element, {
  popperConfig(defaultBsPopperConfig) {
    // const newPopperConfig = {...}
    // use defaultBsPopperConfig if needed...
    // return newPopperConfig
  }
})

Métodos

Todos los métodos API son asincrónicos e inician una transición. Regresan al punto de la llamada tan pronto como se inicia la transición, pero antes de que finalice. Además, se ignorará una llamada a un método en un componente en transición. Obtén más información en nuestra documentación de JavaScript.
Método Descripción
disable Elimina la capacidad de mostrar la tooltips de un elemento. Los tooltips solo podrán mostrarse si se vuelve a habilitar.
dispose Oculta y destruye tooltips de un elemento (elimina los datos almacenados en el elemento DOM). Los tooltips que utilizan la delegación (que se crea utilizando la opción selector,) no se puede destruir individualmente en elementos desencadenantes descendientes.
enable Da la posibilidad de mostrar tooltips de un elemento. Los tooltips está habilitados de forma predeterminada.
getInstance Static método que te permite obtener la instancia de tooltips asociados con un elemento DOM, o crear una nueva en caso de que no haya sido inicializada.
getOrCreateInstance Static método que te permite obtener la instancia de tooltips asociados con un elemento DOM, o crear una nueva en caso de que no haya sido inicializada.
hide Oculta tooltips de un elemento. Vuelve al punto de la llamada antes de que el tooltips se haya ocultado (es decir, antes de que se produzca el evento hidden.bs.tooltip). Esto se considera una activación “manual” del tooltips.
setContent Proporciona una manera de cambiar el contenido del tooltips después de su inicialización.
show Revela el tooltips de un elemento. Vuelve al punto de la llamada antes de que se haya mostrado realmente el tooltips (es decir, antes de que ocurra el evento shown.bs.tooltip). Esto se considera una activación "manual" del tooltips. Los tooltips con títulos de longitud cero nunca se muestran.
toggle Alterna tooltips de un elemento. Vuelve al punto de la llamada antes de que el tooltips se haya mostrado u ocultado (es decir, antes de que el evento shown.bs.tooltip o hidden.bs.tooltip ocurra). Esto se considera una activación “manual” de tooltips.
toggleEnabled Alterna la capacidad de mostrar u ocultar tooltips de un elemento.
update Actualiza la posición de tooltips de un elemento.
const tooltip = bootstrap.Tooltip.getInstance('#example') // Returns a Bootstrap tooltip instance

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

Eventos

Evento Descripción
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 tooltips termina de ocultarse al usuario (esperará a que se completen las transiciones CSS).
inserted.bs.tooltip Este evento se activa después del evento show.bs.tooltip cuando la plantilla de tooltips se ha agregado al DOM.
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 tooltips se hace visible para el usuario (esperará a que se completen las transiciones CSS).
const myTooltipEl = document.getElementById('myTooltip')
const tooltip = bootstrap.Tooltip.getOrCreateInstance(myTooltipEl)

myTooltipEl.addEventListener('hidden.bs.tooltip', () => {
  // do something...
})

tooltip.hide()