El componente Modal de Bootstrap
Usa el complemento modal JavaScript de Bootstrap para agregar cuadros de diálogo a tu sitio para lightboxes, notificaciones de usuario o contenido completamente personalizado.
Cómo funciona el componente Modal
Antes de comenzar con el componente modal de Bootstrap, asegúrate de leer lo siguiente ya que nuestras opciones de menú han cambiado recientemente.
- Los modales se crean con HTML, CSS y JavaScript. Se colocan sobre todo lo demás en el documento y eliminan el desplazamiento del
<body>
para que el contenido modal se desplace. - Al hacer clic en el “fondo” detrás del modal, se cerrará automáticamente el modal.
- Bootstrap solo admite una ventana modal a la vez. Los modales anidados no son compatibles porque creemos que son malas experiencias para el usuario.
- Los modales usan
position: fixed
, lo que a veces puede ser un poco particular en cuanto a su representación. Siempre que sea posible, coloca tu HTML modal en una posición de nivel superior para evitar posibles interferencias de otros elementos. Probablemente tendrás problemas al anidar un.modal
dentro de otro elemento fijo. - Una vez más, debido a la
position: fixed
, existen algunas advertencias sobre el uso de modales en dispositivos móviles. Consulta nuestra documentación de soporte del navegador para obtener más detalles. - Debido a cómo HTML5 define su semántica, el
autofocus
(atributo HTML) no tiene ningún efecto en los modales de Bootstrap. Para lograr el mismo efecto, utiliza JavaScript personalizado:
Sigue leyendo para ver demostraciones y pautas de uso.
Ejemplos del componente Modal
Componentes modales
A continuación se muestra un ejemplo modal estático (lo que significa que su position
y display
han sido sobrescritos). Se incluyen el encabezado modal, el cuerpo modal (requerido para padding
) y el pie de página modal (opcional). Te solicitamos que incluyas encabezados modales con acciones de descarte siempre que sea posible, o que proporciones otra acción de descarte explícita.
Demostración en vivo
Alterna una demostración modal funcional haciendo clic en el botón a continuación. Se deslizará hacia abajo y desaparecerá desde la parte superior de la página.
Fondo estático
Cuando el fondo está configurado como estático, el modal no se cerrará al hacer clic fuera de él. Haz clic en el botón de abajo para probarlo.
Desplazarse por contenido extenso
Cuando los modales se vuelven demasiado largos para la viewport o el dispositivo del usuario, se desplazan independientemente de la página misma. Pruebe la demostración a continuación para ver a qué nos referimos.
También puedes crear un modal desplazable que permita desplazar el cuerpo del modal agregando .modal-dialog-scrollable
a .modal-dialog
.
Centrado verticalmente
Agrega .modal-dialog-centered
a .modal-dialog
para centrar verticalmente el modal.
Tooltips y ventanas emergentes
Tooltips y popovers se pueden colocar dentro de modales según sea necesario. Cuando se cierran los modales, cualquier tooltips y ventanas emergentes también se descartan automáticamente.
Usando la grilla
Utiliza el sistema de cuadrícula Bootstrap dentro de un modal anidando .container-fluid
dentro de .modal-body
. Luego, utiliza las clases normales del sistema grid como lo harías en cualquier otro lugar.
Contenido modal variable
¿Tienes un montón de botones que activan el mismo modal con contenidos ligeramente diferentes? Utiliza event.relatedTarget
y atributos data-bs-*
HTML para variar el contenido del modal dependiendo del botón en el que se hizo clic.
A continuación se muestra una demostración en vivo seguida de ejemplos de HTML y JavaScript. Para obtener más información, lee los documentación de eventos modales para obtener detalles sobre relatedTarget
.
Alternar entre modales
Alterna entre múltiples modales con una ubicación inteligente de los atributos data-bs-target
y data-bs-toggle
. Por ejemplo, puedes alternar un modal de restablecimiento de contraseña desde un modal de inicio de sesión ya abierto. Ten en cuenta que no se pueden abrir varios modales al mismo tiempo; este método simplemente alterna entre dos modales separados.
Cambiar animación
La variable $modal-fade-transform
determina el estado de transformación de .modal-dialog
antes de la animación de aparición gradual modal, la variable $modal-show-transform
determina la transformación de .modal-dialog
al final de la animación de aparición gradual del modal.
Si quieres, por ejemplo, una animación con zoom, puedes configurar $modal-fade-transform: scale(.8)
.
Quitar animación
Para los modales que simplemente aparecen en lugar de aparecer gradualmente, elimina la clase .fade
de tu marcado modal.
Alturas dinámicas
Si la altura de un modal cambia mientras está abierto, debes llamar a myModal.handleUpdate()
para reajustar la posición del modal en caso de que aparezca una barra de desplazamiento.
Accesibilidad
Asegúrate de agregar aria-labelledby="..."
, haciendo referencia al título modal, a .modal
. Además, puedes dar una descripción de tu diálogo modal con aria-describedby
en .modal
. Ten en cuenta que no necesitas agregar role="dialog"
ya que ya lo agregamos a través de JavaScript.
Incrustar videos de YouTube
Incrustar videos de YouTube en modales requiere JavaScript adicional, no en Bootstrap, para detener automáticamente la reproducción y más. Consulta esta útil publicación de Stack Overflow para obtener más información.
Tamaños opcionales del componente Modal
Los modales tienen tres tamaños opcionales, disponibles a través de clases modificadoras para colocarse en un .modal-dialog
. Estos tamaños se activan en ciertos puntos de interrupción para evitar barras de desplazamiento horizontales en viewports más estrechas.
Tamaño | Clase | Ancho máximo del modal |
---|---|---|
Pequeño | .modal-sm | 300px |
Predeterminado | Ninguno | 500px |
Grande | .modal-lg | 800px |
Extra grande | .modal-xl | 1140px |
Nuestro modal predeterminado sin clase modificadora constituye el modal de tamaño “mediano”.
Modal de pantalla completa
Otra sobrescritura es la opción de mostrar un modal que cubra el viewport del usuario, disponible a través de clases modificadoras que se colocan en un .modal-dialog
.
Clase | Disponibilidad |
---|---|
.modal-fullscreen | Siempre |
.modal-fullscreen-sm-down | 576px |
.modal-fullscreen-md-down | 768px |
.modal-fullscreen-lg-down | 992px |
.modal-fullscreen-xl-down | 1200px |
.modal-fullscreen-xxl-down | 1400px |
Pantalla completa Pantalla completa debajo de sm Pantalla completa debajo de md Pantalla completa debajo de lg Pantalla completa debajo de xl Pantalla completa debajo de xxl
Personalización del CSS del componente
Variables Sass del componente
Agregado en v5.2.0
Como parte del enfoque de variables CSS en evolución de Bootstrap, los modales ahora usan variables CSS locales en .modal
y .modal-backdrop
para 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.
Variables Sass generales relacionadas
Bucles Sass del componente
Los modales responsive de pantalla completa se generan a través del mapa $breakpoints
y un bucle en scss/_modal.scss
.
Uso del componente Modal
El complemento modal alterna tu contenido oculto según demanda, a través de atributos de datos o JavaScript. También sobrescribe el comportamiento de desplazamiento predeterminado y genera un .modal-backdrop
para proporcionar un área de clic para descartar los modales mostrados al hacer clic fuera del modal.
Vía atributos de datos
Alternar
Activar un modal sin escribir JavaScript. Establece data-bs-toggle="modal"
en un elemento del controlador, como un botón, junto con un data-bs-target="#foo"
o href="#foo"
para apuntar a un modal específico para alternar.
Descartar
El despido se puede lograr con el atributo data-bs-dismiss
en un botón dentro del modal como se muestra a continuación:
o en un botón fuera del modal usando el data-bs-target
adicional como se muestra a continuación:
Vía JavaScript
Crea un modal con una sola línea de JavaScript:
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.
Nombre | Tipo | Predeterminado | Descripción |
---|---|---|---|
backdrop | boolean, 'static' | true | Incluye un elemento de fondo modal. Alternativamente, especifica static para un fondo que no cierre el modal al hacer clic. |
focus | boolean | true | Pone el foco en el modal cuando se inicializa. |
keyboard | boolean | true | Cierra el modal cuando se presiona la tecla escape. |
Métodos
Opciones de paso
Activa tu contenido como modal. Acepta opciones opcionales object
.
Método | Descripción |
---|---|
dispose | Destruye el modal de un elemento. (Elimina los datos almacenados en el elemento DOM) |
getInstance | Static método que te permite obtener la instancia modal asociada con un elemento DOM. |
getOrCreateInstance | Static método que te permite obtener la instancia modal asociada con un elemento DOM, o crear una nueva en caso de que no haya sido inicializada. |
handleUpdate | Reajusta manualmente la posición del modal si la altura de un modal cambia mientras está abierto (es decir, en caso de que aparezca una barra de desplazamiento). |
hide | Oculta manualmente un modal. Vuelve al punto de la llamada antes de que el modal se haya ocultado (es decir, antes de que ocurra el evento hidden.bs.modal ). |
show | Abre manualmente un modal. Vuelve al punto de la llamada antes de que el modal se haya mostrado realmente (es decir, antes de que ocurra el evento shown.bs.modal ). Además, puedes pasar un elemento DOM como argumento que se puede recibir en los eventos modales (como la propiedad relatedTarget ). (es decir, const modalToggle = document.getElementById('toggleMyModal'); myModal.show(modalToggle) . |
toggle | Conmuta manualmente un modal. Vuelve al punto de la llamada antes de que el modal se haya mostrado u oculto (es decir, antes del evento shown.bs.modal o hidden.bs.modal ). |
Eventos
La clase modal de Bootstrap expone algunos eventos para conectarse a la funcionalidad modal. Todos los eventos modales se activan en el propio modal (es decir, en el <div class="modal">
).
Evento | Descripción |
---|---|
hide.bs.modal | Este evento se activa inmediatamente cuando se llama al método de instancia hide . |
hidden.bs.modal | Este evento se activa cuando el modal termina de ocultarse al usuario (esperará a que se completen las transiciones CSS). |
hidePrevented.bs.modal | Este evento se activa cuando se muestra el modal, su fondo es static y se realiza un clic fuera del modal. El evento también se activa cuando se presiona la tecla Escape y la opción keyboard está configurada en false . |
show.bs.modal | Este evento se activa inmediatamente cuando se llama al método de instancia show . Si es causado por un clic, el elemento en el que se hizo clic está disponible como la propiedad relatedTarget del evento. |
shown.bs.modal | Este evento se activa cuando el modal se ha hecho visible para el usuario (esperará a que se completen las transiciones CSS). Si es causado por un clic, el elemento en el que se hizo clic está disponible como la propiedad relatedTarget del evento. |