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

Documentación y ejemplos para agregar ventanas emergentes de Bootstrap, como las 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 dependen de 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 popovers requieren el complemento popover como dependencia.
  • Los popovers son opcionales por motivos de rendimiento, por lo que debes inicializarlos tú mismo.
  • Los valores title y content de longitud cero nunca mostrarán una ventana emergente.
  • Especifica container: 'body' para evitar problemas de renderizado en componentes más complejos (como nuestros grupos de entrada, grupos de botones, etc.).
  • Activar ventanas emergentes en elementos ocultos no funcionará.
  • Los elementos emergentes para los elementos .disabled o disabled deben activarse en un elemento contenedor.
  • Cuando se activan desde anchors (enlaces) que abarcan varias líneas, los popovers se centrarán entre el ancho total de los enlaces. Utiliza .text-nowrap en tus <a>para evitar este comportamiento.
  • Los popovers deben ocultarse antes de que sus elementos correspondientes se eliminen del DOM.
  • Los popovers se pueden activar gracias a un elemento dentro de un DOM oculto.
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.

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

Ejemplos

Habilitar popovers

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

const popoverTriggerList = document.querySelectorAll('[data-bs-toggle="popover"]')
const popoverList = [...popoverTriggerList].map(popoverTriggerEl => new bootstrap.Popover(popoverTriggerEl))

Demostración en vivo

Usamos JavaScript similar al fragmento anterior para representar el siguiente popover en vivo. Los títulos se configuran mediante data-bs-title y el contenido del cuerpo se establece mediante data-bs-content.

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.
html
<button type="button" class="btn btn-lg btn-danger" data-bs-toggle="popover" data-bs-title="Popover title" data-bs-content="And here's some amazing content. It's very engaging. Right?">Click to toggle popover</button>

Cuatro direcciones

Hay cuatro opciones disponibles: arriba, derecha, abajo e izquierda. Las instrucciones se reflejan cuando se usa Bootstrap en RTL. Establece data-bs-placement para cambiar la dirección.

html
<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 on top
</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 on right
</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 on bottom
</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 on left
</button>

Contenedor personalizado container

Cuando tienes algunos estilos en un elemento padre que interfieren con una ventana emergente, querrás especificar un container personalizado para que el HTML de la ventana emergente aparezca dentro de ese elemento. Esto es común en tablas responsive, grupos de entrada y similares.

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

Otra situación en la que querrás establecer un container personalizado explícito son los popovers dentro de un diálogo modal, para asegurarte de que la ventana emergente en sí se agregue al modal. Esto es particularmente importante para los popovers que contienen elementos interactivos: los cuadros de diálogo modales atraparán el foco, por lo que, a menos que el popover sea un elemento secundario del modal, los usuarios no podrán enfocar ni activar estos elementos interactivos.

const popover = new bootstrap.Popover('.example-popover', {
  container: '.modal-body'
})

Popovers personalizados

Agregado en v5.2.0

Puedes personalizar la apariencia de los popovers usando variables CSS. Configuramos una clase personalizada con data-bs-custom-class="custom-popover" para definir el alcance de nuestra apariencia personalizada y usarla para sobrescribir algunas de las variables CSS locales.

.custom-popover {
  --bs-popover-max-width: 200px;
  --bs-popover-border-color: var(--bd-violet-bg);
  --bs-popover-header-bg: var(--bd-violet-bg);
  --bs-popover-header-color: var(--bs-white);
  --bs-popover-body-padding-x: 1rem;
  --bs-popover-body-padding-y: .5rem;
}
html
<button type="button" class="btn btn-secondary"
        data-bs-toggle="popover" data-bs-placement="right"
        data-bs-custom-class="custom-popover"
        data-bs-title="Custom popover"
        data-bs-content="This popover is themed via CSS variables.">
  Custom popover
</button>

Descartar en el siguiente clic

Utiliza el disparador focus para descartar ventanas emergentes en el siguiente clic del usuario en un elemento que no sea el elemento de alternancia.

Para descartar en el siguiente clic se requiere HTML específico para un comportamiento adecuado entre navegadores y plataformas. Solo puedes usar elementos <a>, no elementos <button>s, y debes incluir un tabindex.
html
<a tabindex="0" class="btn btn-lg btn-danger" role="button" data-bs-toggle="popover" data-bs-trigger="focus" data-bs-title="Dismissible popover" data-bs-content="And here's some amazing content. It's very engaging. Right?">Dismissible popover</a>
const popover = new bootstrap.Popover('.popover-dismiss', {
  trigger: 'focus'
})

Elementos deshabilitados

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

Para los activadores de ventana emergente deshabilitados, también puedes preferir data-bs-trigger="hover focus" para que la ventana emergente aparezca como retroalimentación visual inmediata para tus usuarios ya que es posible que no intenten hacer clic en un elemento deshabilitado.

html
<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>Disabled button</button>
</span>

CSS

Variables

Agregado en v5.2.0

Como parte del enfoque de variables CSS en evolución de Bootstrap, los popovers ahora usan variables CSS locales en .popover para una personalización mejorada 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}popover-zindex: #{$zindex-popover};
--#{$prefix}popover-max-width: #{$popover-max-width};
@include rfs($popover-font-size, --#{$prefix}popover-font-size);
--#{$prefix}popover-bg: #{$popover-bg};
--#{$prefix}popover-border-width: #{$popover-border-width};
--#{$prefix}popover-border-color: #{$popover-border-color};
--#{$prefix}popover-border-radius: #{$popover-border-radius};
--#{$prefix}popover-inner-border-radius: #{$popover-inner-border-radius};
--#{$prefix}popover-box-shadow: #{$popover-box-shadow};
--#{$prefix}popover-header-padding-x: #{$popover-header-padding-x};
--#{$prefix}popover-header-padding-y: #{$popover-header-padding-y};
@include rfs($popover-header-font-size, --#{$prefix}popover-header-font-size);
--#{$prefix}popover-header-color: #{$popover-header-color};
--#{$prefix}popover-header-bg: #{$popover-header-bg};
--#{$prefix}popover-body-padding-x: #{$popover-body-padding-x};
--#{$prefix}popover-body-padding-y: #{$popover-body-padding-y};
--#{$prefix}popover-body-color: #{$popover-body-color};
--#{$prefix}popover-arrow-width: #{$popover-arrow-width};
--#{$prefix}popover-arrow-height: #{$popover-arrow-height};
--#{$prefix}popover-arrow-border: var(--#{$prefix}popover-border-color);

Variables Sass

$popover-font-size:                 $font-size-sm;
$popover-bg:                        var(--#{$prefix}body-bg);
$popover-max-width:                 276px;
$popover-border-width:              var(--#{$prefix}border-width);
$popover-border-color:              var(--#{$prefix}border-color-translucent);
$popover-border-radius:             var(--#{$prefix}border-radius-lg);
$popover-inner-border-radius:       calc(#{$popover-border-radius} - #{$popover-border-width}); // stylelint-disable-line function-disallowed-list
$popover-box-shadow:                var(--#{$prefix}box-shadow);

$popover-header-font-size:          $font-size-base;
$popover-header-bg:                 var(--#{$prefix}secondary-bg);
$popover-header-color:              $headings-color;
$popover-header-padding-y:          .5rem;
$popover-header-padding-x:          $spacer;

$popover-body-color:                var(--#{$prefix}body-color);
$popover-body-padding-y:            $spacer;
$popover-body-padding-x:            $spacer;

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

Uso

Habilitar ventanas emergentes a través de JavaScript:

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

Mantén los popovers 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 ventanas emergentes en esta situación. Además, no confíes únicamente en hover como activador de tus ventanas emergentes, ya que esto hará que sea imposible activarlas para los usuarios del teclado.

Evita agregar una cantidad excesiva de contenido en los popovers con la opción html. Una vez que se muestran los popovers, su contenido se vincula al elemento desencadenante con el atributo aria-describedby, lo que hace que todo el contenido del popover se anuncie a los usuarios de tecnología de asistencia como una secuencia larga e ininterrumpida.

Los popovers no administran el orden de enfoque del teclado y su ubicación puede ser aleatoria en el DOM, así que ten cuidado al agregar elementos interactivos (como formularios o enlaces), ya que puede llevar a un orden de enfoque ilógico o hacer que el contenido emergente sea completamente inaccesible para los usuarios de teclado. En los casos en los que debas utilizar estos elementos, considera utilizar un diálogo modal en su lugar.

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 al popover.
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 la documentación de detectOverflowde Popper.
container string, element, false false Agrega el popover a un elemento específico. Ejemplo: container: 'body'. Esta opción es particularmente útil porque te permite colocar la ventana emergente en el flujo del documento cerca del elemento desencadenante, lo que evitará que la ventana emergente flote lejos del elemento desencadenante durante el cambio de tamaño de la ventana.
content string, element, function '' El contenido de texto del popover. Si se proporciona una función, se llamará con su referencia this establecida en el elemento al que está adjunto el popover.
customClass string, function '' Agrega clases al popover cuando se muestra. Ten en cuenta que estas clases se agregarán además de cualquier clase especificada en la plantilla. Para agregar varias clases, sepáralas 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 espera para 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 }.
fallbackPlacements string, 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 la ventana emergente. Si es true, las etiquetas HTML en el title de la ventana emergente se representarán en la ventana emergente. Si es false, la propiedad innerText se utilizará para insertar contenido en el DOM. Utiliza texto si te preocupan los ataques XSS.
offset number, string, function [0, 0] Desplazamiento del popover 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, consulta la documentación de offset de Popper.
placement string, function 'top' Cómo posicionar el popover: auto, top, bottom, left, right. Cuando se especifica auto , reorientará dinámicamente la ventana emergente. Cuando se utiliza una función para determinar la ubicación, se llama con el nodo DOM emergente como primer argumento y el nodo DOM del elemento desencadenante como segundo. El contexto this se establece en la instancia de ventana emergente.
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 emergentes se delegarán a los objetivos especificados. En la práctica, esto también se utiliza para aplicar ventanas emergentes 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="popover" role="tooltip"><div class="popover-arrow"></div><div class="popover-inner"></div></div>' HTML base para usar al crear el popover. El title del popover se inyectará en el .popover-inner. .popover-arrow se convertirá en la flecha del popover. El elemento contenedor más externo debe tener la clase .popover y role="tooltip".
title string, element, function '' El título del popover. 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 popover: click, hover, manual. Puedes pasar varios factores desencadenantes; sepáralos con un espacio. 'manual' indica que el popover se activará mediante programación mediante los métodos .popover('show'), .popover('hide') y .popover('toggle'); este valor no se puede combinar con ningún otro activador. 'hover' por sí solo generará ventanas emergentes que no se pueden activar a través del teclado y solo deben usarse si existen métodos alternativos para transmitir la misma información a los usuarios del teclado.

Atributos de datos para popovers individuales

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

Usar la función con popperConfig

const popover = new bootstrap.Popover(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 posibilidad de que se muestre la ventana emergente de un elemento. La ventana emergente solo podrá mostrarse si se vuelve a habilitar.
dispose Oculta y destruye la ventana emergente de un elemento (elimina los datos almacenados en el elemento DOM). Los elementos emergentes que utilizan delegación (que se crean usando la opción selector, ) no se pueden destruir individualmente en elementos desencadenantes descendientes.
enable Le da al popover de un elemento la posibilidad de mostrarse. Las ventanas emergentes están habilitadas de forma predeterminada.
getInstance Static método que te permite obtener la instancia emergente asociada con un elemento DOM.
getOrCreateInstance Static método que te permite obtener la instancia emergente asociada con un elemento DOM, o crear una nueva en caso de que no haya sido inicializada.
hide Oculta la ventana emergente de un elemento. Vuelve al punto de la llamada antes de que la ventana emergente se haya ocultado (es decir, antes de que ocurra el evento hidden.bs.popover). Esto se considera una activación “manual” del popover.
setContent Proporciona una manera de cambiar el contenido del popover después de su inicialización.
show Revela el popover de un elemento. Vuelve al punto de la llamada antes de que se haya mostrado realmente la ventana emergente (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 tengan longitud cero nunca se muestran.
toggle Alterna la ventana emergente de un elemento. Vuelve al punto de la llamada antes de que la ventana emergente se haya mostrado u ocultado (es decir, antes de que ocurra el evento shown.bs.popover o hidden.bs.popover). Esto se considera una activación “manual” del popover.
toggleEnabled Alterna la capacidad de mostrar u ocultar la ventana emergente de un elemento.
update Actualiza la posición del popover de un elemento.
// getOrCreateInstance example
const popover = bootstrap.Popover.getOrCreateInstance('#example') // Returns a Bootstrap popover instance

// setContent example
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 string válido dentro de la plantilla emergente, y cada valor de propiedad relacionado puede ser string | element | function | null

Eventos

Evento Descripción
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 termina 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 la plantilla emergente se agrega al DOM.
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 la ventana emergente se hace visible para el usuario (esperará a que se completen las transiciones CSS).
const myPopoverTrigger = document.getElementById('myPopover')
myPopoverTrigger.addEventListener('hidden.bs.popover', () => {
  // do something...
})