Skip to main content Skip to docs navigation

Popovers

Documentación y ejemplos para agregar popovers de Bootstrap, como los que se encuentran en iOS, a cualquier elemento de tu sitio.

Descripción general

Cosas que debes saber al usar el complemento popover:

  • Los popovers 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 popovers funcionen!
  • Los popovers requieren el complemento tooltip como una dependencia.
  • Los popovers son opcionales por motivos de rendimiento, por lo que debes inicializarlos tú mismo.
  • Valores de longitud cero en title y content nunca mostrarán un popover.
  • 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 popovers en elementos ocultos no funcionará.
  • Los popovers para los elementos .disabled o disabled deben activarse en un elemento padre contenedor.
  • Cuando se activan desde enlaces que se envuelven en varias líneas, los popovers se centrarán entre el ancho total de los enlaces. Usa .text-nowrap en tus <a>s para evitar este comportamiento.
  • Los popovers deben estar ocultos antes de que sus elementos correspondientes hayan sido eliminados del DOM.
  • Los popovers se pueden 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.

Sigue leyendo para ver cómo funcionan los popovers con algunos ejemplos.

Ejemplo: habilitar popovers en todas partes

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

var popoverTriggerList = Array.prototype.slice.call(document.querySelectorAll('[data-bs-toggle="popover"]'))
var popoverList = popoverTriggerList.map(function (popoverTriggerEl) {
  return new bootstrap.Popover(popoverTriggerEl)
})

Ejemplo: Uso de la opción container

Cuando tienes algunos estilos en un elemento padre que interfieren con un popover, querrás especificar un container personalizado para que el HTML del popover aparezca dentro de ese elemento.

var popover = new bootstrap.Popover(document.querySelector('.example-popover'), {
  container: 'body'
})

Ejemplo

<button type="button" class="btn btn-lg btn-danger" data-bs-toggle="popover" title="Popover title" data-bs-content="And here's some amazing content. It's very engaging. Right?">Clic para alternar el popover</button>

Cuatro direcciones

Hay cuatro opciones disponibles: alineación superior, derecha, inferior e izquierda. Las direcciones se reflejan cuando se usa Bootstrap en RTL.

<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="top" data-bs-content="Top popover">
  Popover superior
</button>
<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="right" data-bs-content="Right popover">
  Popover derecho
</button>
<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="bottom" data-bs-content="Bottom popover">
  Popover inferior
</button>
<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="left" data-bs-content="Left popover">
  Popover izquierdo
</button>

Descartar (cerrar) en el siguiente clic

Usa el disparador focus para descartar popovers en el siguiente clic del usuario en un elemento diferente al elemento de alternancia.

Marcado específico requerido para descartar al siguiente clic

Para un comportamiento adecuado entre navegadores y plataformas, debes usar la etiqueta <a>, no la etiqueta <button>, y también debes incluir un atributo tabindex.

<a tabindex="0" class="btn btn-lg btn-danger" role="button" data-bs-toggle="popover" data-bs-trigger="focus" title="Dismissible popover" data-bs-content="And here's some amazing content. It's very engaging. Right?">Descartar popover</a>
var popover = new bootstrap.Popover(document.querySelector('.popover-dismiss'), {
  trigger: 'focus'
})

Elementos deshabilitados

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

Para activadores de popovers deshabilitados, también puedes preferir data-bs-trigger="hover focus" para que el popover aparezca como una respuesta visual inmediata a tus usuarios, ya que es posible que no esperen hacer clic en un elemento deshabilitado.

<span class="d-inline-block" tabindex="0" data-bs-toggle="popover" data-bs-trigger="hover focus" data-bs-content="Disabled popover">
  <button class="btn btn-primary" type="button" disabled>Botón deshabilitado</button>
</span>

Sass

Variables

$popover-font-size:                 $font-size-sm;
$popover-bg:                        $white;
$popover-max-width:                 276px;
$popover-border-width:              $border-width;
$popover-border-color:              rgba($black, .2);
$popover-border-radius:             $border-radius-lg;
$popover-inner-border-radius:       subtract($popover-border-radius, $popover-border-width);
$popover-box-shadow:                $box-shadow;

$popover-header-bg:                 shade-color($popover-bg, 6%);
$popover-header-color:              $headings-color;
$popover-header-padding-y:          .5rem;
$popover-header-padding-x:          $spacer;

$popover-body-color:                $body-color;
$popover-body-padding-y:            $spacer;
$popover-body-padding-x:            $spacer;

$popover-arrow-width:               1rem;
$popover-arrow-height:              .5rem;
$popover-arrow-color:               $popover-bg;

$popover-arrow-outer-color:         fade-in($popover-border-color, .05);

Uso

Habilitar popovers a través de JavaScript:

var exampleEl = document.getElementById('example')
var popover = new bootstrap.Popover(exampleEl, options)

Cómo hacer que los popovers funcionen para los usuarios de teclados y tecnología de asistencia

Para permitir que los usuarios del teclado activen sus ventanas emergentes, solo debes agregarlas a los elementos HTML que tradicionalmente se pueden enfocar con el teclado e 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 contenido del popover en esta situación. Además, no confíes únicamente en hover como disparador de tus popovers, ya que esto hará que sea imposible que los usuarios del teclado los activen.

Si bien puedes insertar HTML enriquecido y estructurado en popovers con la opción html, te recomendamos enfáticamente que evites agregar una cantidad excesiva de contenido. La forma en que funcionan actualmente los popovers es que, una vez que se muestran, su contenido está vinculado al elemento activador con el atributo aria-describedby. Como resultado, la totalidad del contenido de la ventana emergente se anunciará a los usuarios de tecnología de asistencia como una secuencia larga e ininterrumpida.

Además, si bien también es posible incluir controles interactivos (como elementos de formulario o enlaces) en tu ventana emergente (agregando estos elementos a la allowList de atributos y etiquetas permitidas), ten en cuenta que actualmente la ventana emergente no administra el enfoque del teclado. Cuando un usuario del teclado abre una ventana emergente, el foco permanece en el elemento activador y, como la ventana emergente generalmente no sigue inmediatamente al activador en la estructura del documento, no hay garantía de que presionando TAB se moverá un usuario de teclado en el propio popover. En resumen, es probable que el simple hecho de agregar controles interactivos a una ventana emergente haga que estos controles sean inalcanzables o inutilizables para los usuarios de teclados y usuarios de tecnologías de asistencia, o al menos generar un orden de enfoque general ilógico. En estos casos, considera usar un diálogo modal en su lugar.

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 popover
container string | element | false false

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

content string | element | function ''

Valor de contenido predeterminado si el atributo data-bs-content no está presente.

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

delay number | object 0

Retraso en mostrar y ocultar el popover (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 Inserta HTML en la ventana emergente. Si es falso, la propiedad innerText se usará para insertar contenido en el DOM. Usa texto si te preocupan los ataques XSS.
placement string | function 'right'

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

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

selector string | false false Si se proporciona un selector, los objetos emergentes se delegarán a los destinos especificados. En la práctica, esto se usa para permitir que se agreguen popovers a contenido HTML dinámico. Consulta this y un ejemplo informativo.
template string '<div class="popover" role="tooltip"><div class="popover-arrow"></div><h3 class="popover-header"></h3><div class="popover-body"></div></div>'

HTML base para usar al crear el popover.

El title del popover se insertará en .popover-header.

El content del popover se inyectará en el .popover-body.

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

El elemento contenedor más externo debe tener la clase .popover.

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 la ventana emergente.

trigger string 'click' Cómo se activa el popover: click | hover | focus | manual. Puedes pasar varios disparadores; sepáralos con un espacio. manual no se puede combinar con ningún otro disparador.
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 popover (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 popover cuando se muestre. Ten en cuenta que estas clases se agregarán además de las clases especificadas enl 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 se activan las opciones 'template', 'content' y 'title', serán desinfectadas. 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, 8]

Desplazamiento del popover relativo a 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 popovers individuales

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

Uso de la función con popperConfig

var popover = new bootstrap.Popover(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 popover de un elemento. Regresa al punte de la llamada antes de que se haya mostrado realmente el popover (es decir, antes de que ocurra el evento shown.bs.popover). Esto se considera una activación “manual” del popover. Los popovers cuyo título y contenido son ambos de longitud cero nunca se muestran.

myPopover.show()

hide

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

myPopover.hide()

toggle

Alterna el popover de un elemento. Regresa al punte de la llamada antes de que se muestre u oculte el popover (es decir, antes de que ocurra el evento shown.bs.popover o hidden.bs.popover). Esto se considera una activación “manual” del popover.

myPopover.toggle()

dispose

Oculta y destruye el popover de un elemento (elimina los datos almacenados en el elemento DOM). Los popovers que usan delegación (que se crean usando la opción selector) no se pueden destruir individualmente en elementos desencadenantes descendientes.

myPopover.dispose()

enable

Le da al popover de un elemento la capacidad de mostrarse. Las ventanas emergentes están habilitadas de manera predeterminada.

myPopover.enable()

disable

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

myPopover.disable()

setContent

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

myPopover.setContent({
  '.popover-header': 'another title',
  '.popover-body': 'another content'
})
El método setContent acepta un argumento object, donde cada clave de propiedad es un selector de string válido dentro del popover template, y cada valor de propiedad relacionado puede ser string | element | function | null

toggleEnabled

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

myPopover.toggleEnabled()

update

Actualiza la posición del popover de un elemento.

myPopover.update()

getInstance

Método estático que te permite obtener la instancia de popover asociada con un elemento DOM

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

getOrCreateInstance

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

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

Eventos

Tipo de evento Descripción
show.bs.popover Este evento se activa inmediatamente cuando se llama al método de instancia show.
shown.bs.popover Este evento se activa cuando el popover se hace visible para el usuario (esperará a que se completen las transiciones CSS).
hide.bs.popover Este evento se activa inmediatamente cuando se llama al método de instancia hide.
hidden.bs.popover Este evento se activa cuando el popover ha terminado de ocultarse al usuario (esperará a que se completen las transiciones CSS).
inserted.bs.popover Este evento se activa después del evento show.bs.popover cuando el template de popover se ha agregado al DOM.
var myPopoverTrigger = document.getElementById('myPopover')
myPopoverTrigger.addEventListener('hidden.bs.popover', function () {
  // hacer algo...
})