Popovers

Descripción general

Cosas a saber cuando se usa el plugin popover:

• Los popovers dependen de la librería de terceros Popper para el posicionamiento. Debes incluir popper.min.js antes de bootstrap.js, o usar bootstrap.bundle.min.js que contiene Popper.
• Los popovers requieren el plugin popover como dependencia.
• Los popovers son opt-in por razones de rendimiento, por lo que debes inicializarlos tú mismo.
• Los valores de title y content de longitud cero nunca mostrarán un popover.
• Especifica container: 'body' para evitar problemas de renderizado en componentes más complejos (como nuestros grupos de entrada, grupos de botones, etc).
• Activar popovers en elementos ocultos no funcionará.
• Los popovers para elementos .disabled o disabled deben activarse desde un elemento contenedor.
• Cuando se disparan desde anclajes que se ajustan a múltiples líneas, los popovers se centrarán entre el ancho total de los anclajes. Usa .text-nowrap en tus <a>s para evitar este comportamiento.
• Los popovers deben ocultarse antes de que sus elementos correspondientes hayan sido eliminados del DOM.
• Los popovers pueden activarse gracias a un elemento dentro de un shadow DOM.

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 que puedan usarse. Una forma de inicializar todos los popovers en 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 renderizar el siguiente popover en vivo. Los títulos se establecen mediante data-bs-title y el contenido del cuerpo se establece mediante data-bs-content.

<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 direcciones se invierten al usar Bootstrap en RTL. Establece data-bs-placement para cambiar la dirección.

<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>

container personalizado

Cuando tienes algunos estilos en un elemento padre que interfieren con un popover, querrás especificar un contenedor personalizado para que el HTML del popover aparezca dentro de ese elemento en su lugar. 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 contenedor personalizado explícito son los popovers dentro de un diálogo modal, para asegurar que el popover mismo se adjunte al modal. Esto es particularmente importante para los popovers que contienen elementos interactivos: los diálogos modales atraparán el foco, por lo que a menos que el popover sea un elemento hijo 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

Puedes personalizar la apariencia de los popovers usando variables CSS. Establecemos una clase personalizada con data-bs-custom-class="custom-popover" para delimitar nuestra apariencia personalizada y la usamos 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;
}

<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>

Cerrar al siguiente clic

Usa el trigger focus para cerrar los popovers en el siguiente clic del usuario en un elemento distinto al elemento de alternancia.

<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 interactivos, lo que significa que los usuarios no pueden pasar el cursor o hacer clic en ellos para activar un popover (o tooltip). Como solución alternativa, querrás activar el popover desde un <div> o <span> contenedor, idealmente enfocable por teclado usando tabindex="0".

Para los disparadores de popover deshabilitados, también puedes preferir data-bs-trigger="hover focus" para que el popover aparezca como retroalimentación visual inmediata para tus usuarios ya que pueden no esperar 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>Disabled button</button>
</span>

CSS

Variables

Como parte del enfoque evolutivo de variables CSS de Bootstrap, los popovers ahora usan variables CSS locales en .popover para una personalización en tiempo real mejorada. Los valores de las variables CSS se establecen mediante Sass, por lo que la personalización con Sass también sigue siendo 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 popovers vía JavaScript:

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

Opciones

Como las opciones se pueden pasar vía atributos data o JavaScript, puedes añadir un nombre de opción a data-bs-, como en data-bs-animation="{value}". Asegúrate de cambiar el tipo de capitalización del nombre de la opción de “camelCase” a “kebab-case” al pasar las opciones vía atributos data. Por ejemplo, usa data-bs-custom-class="beautifier" en lugar de data-bs-customClass="beautifier".

A partir de Bootstrap 5.2.0, todos los componentes soportan un atributo data reservado experimental data-bs-config que puede albergar una configuración simple 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 data separados sobrescribirán los valores dados en data-bs-config. Además, los atributos data existentes pueden albergar valores JSON como data-bs-delay='{"show":0,"hide":150}'.

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

Usando función con popperConfig

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

Métodos

// getOrCreateInstance example
const popover = bootstrap.Popover.getOrCreateInstance('#example') // Returns a Bootstrap popover instance

// setContent example
popover.setContent({
  '.popover-header': 'another title',
  '.popover-body': 'another content'
})

Eventos

const myPopoverTrigger = document.getElementById('myPopover')
myPopoverTrigger.addEventListener('hidden.bs.popover', () => {
  // do something...
})