Popovers

Resumen

Cosas que debes saber al usar el plugin de popover:

• Los popovers dependen de la biblioteca de terceros Popper para el posicionamiento. Debes incluir popper.min.js antes de bootstrap.js, o usar un bootstrap.bundle.min.js que contenga Popper.
• Los popovers requieren el plugin de 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 con 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 en un elemento contenedor (wrapper).
• Cuando se activan desde enlaces que se extienden en varias líneas, los popovers se centrarán en el ancho total de los enlaces. Usa .text-nowrap en tus <a> para evitar este comportamiento.
• Los popovers deben ocultarse antes de que sus elementos correspondientes hayan sido eliminados del DOM.
• Los popovers se pueden activar 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 poder usarlos. 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

Utilizamos un JavaScript similar al fragmento de arriba para renderizar el siguiente popover en vivo. Los títulos se establecen a través de data-bs-title y el contenido del cuerpo se establece a través de data-bs-content.

<button type="button" class="btn btn-lg btn-danger" data-bs-toggle="popover" data-bs-title="Título del popover" data-bs-content="Y aquí hay un contenido increíble. Es muy atractivo. ¿Verdad?">Haz clic para alternar el popover</button>

Cuatro direcciones

Hay cuatro opciones disponibles: arriba (top), derecha (right), abajo (bottom) e izquierda (left). Las direcciones se reflejan cuando se usa 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="Popover superior">
  Popover arriba
</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 a la derecha
</button>
<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="bottom" data-bs-content="Popover inferior">
  Popover abajo
</button>
<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="left" data-bs-content="Popover izquierdo">
  Popover a la izquierda
</button>

container personalizado

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 en su lugar. Esto es común en tablas responsivas, 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 el popover en sí se agregue al modal. Esto es particularmente importante para los popovers que contienen interactive elements – modal dialogs will trap focus, so unless the popover is a child element of the modal, users won’t be able to focus or activate these interactive elements.

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 usarla para anular 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.">
  Popover personalizado
</button>

Descartar en el siguiente clic

Utiliza el activador focus para descartar los popovers al siguiente clic del usuario en un elemento que no sea el elemento alternador.

<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?">Popover descartable</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 sobre ellos ni hacer clic para activar un popover (o tooltip). Como solución alternativa, querrás activar el popover desde un contenedor <div> o <span>, idealmente enfocado con el teclado usando tabindex="0".

Para los activadores 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 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>

CSS

Variables

Como parte del enfoque evolutivo de las variables CSS 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 de 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

Habilita los popovers a través de JavaScript:

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

Opciones

Como las opciones se pueden pasar a través de atributos de datos 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 mayúsculas y minúsculas del nombre de la opción de “camelCase” a “kebab-case” al pasar las opciones a través de atributos de datos. 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 admiten un atributo de datos 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 de datos separados anulará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 fusionado de data-bs-config, data-bs- y el js object (objeto js) donde el último par clave-valor proporcionado anula a los demás.

Uso de función con popperConfig

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

Métodos

// Ejemplo de getOrCreateInstance
const popover = bootstrap.Popover.getOrCreateInstance('#example') // Devuelve una instancia de popover de Bootstrap

// Ejemplo de setContent
popover.setContent({
  '.popover-header': 'otro título',
  '.popover-body': 'otro contenido'
})

Eventos

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