Popovers

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.

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.

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

<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

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

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

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

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

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.

Usar la 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
myPopover.setContent({
  '.popover-header': 'another title',
  '.popover-body': 'another content'
})

Eventos

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