Saltearse al contenido

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:
JavaScript
const myModal = document.getElementById('myModal')
const myInput = document.getElementById('myInput')
myModal.addEventListener('shown.bs.modal', () => {
myInput.focus()
})

Sigue leyendo para ver demostraciones y pautas de uso.

Ejemplos del componente Modal

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.

HTML
<div class="modal position-static d-block" tabindex="-1">
<div class="modal-dialog">
<div class="modal-content">
<div class="modal-header">
<h5 class="modal-title">Título modal</h5>
<button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
</div>
<div class="modal-body">
<p>El texto del cuerpo modal va aquí.</p>
</div>
<div class="modal-footer">
<button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Cerrar</button>
<button type="button" class="btn btn-primary">Guardar cambios</button>
</div>
</div>
</div>
</div>

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.

HTML
<button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModalLive">
Iniciar modo de demostración
</button>
<div class="modal fade" id="exampleModalLive" tabindex="-1" aria-labelledby="exampleModalLiveLabel" style="display: none;" aria-hidden="true">
<div class="modal-dialog">
<div class="modal-content">
<div class="modal-header">
<h1 class="modal-title fs-5" id="exampleModalLiveLabel">Título modal</h1>
<button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
</div>
<div class="modal-body">
<p>Woo-hoo, ¡estás leyendo este texto en un modal!</p>
</div>
<div class="modal-footer">
<button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Cerrar</button>
<button type="button" class="btn btn-primary">Guardar cambios</button>
</div>
</div>
</div>
</div>

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.

HTML
<button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#staticBackdropLive">
Iniciar modo de fondo estático
</button>
<div class="modal fade" id="staticBackdropLive" data-bs-backdrop="static" data-bs-keyboard="false" tabindex="-1"
aria-labelledby="staticBackdropLiveLabel" style="display: none;" aria-hidden="true">
<div class="modal-dialog">
<div class="modal-content">
<div class="modal-header">
<h1 class="modal-title fs-5" id="staticBackdropLiveLabel">Título modal</h1>
<button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
</div>
<div class="modal-body">
<p>No me cerraré si haces clic fuera de mí. Ni siquiera intentes presionar la tecla Escape.</p>
</div>
<div class="modal-footer">
<button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Cerrar</button>
<button type="button" class="btn btn-primary">Entendido.</button>
</div>
</div>
</div>
</div>

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.

HTML
<!-- Scrollable modal -->
<div class="modal-dialog modal-dialog-scrollable">
...
</div>

Centrado verticalmente

Agrega .modal-dialog-centered a .modal-dialog para centrar verticalmente el modal.

HTML
<!-- Vertically centered modal -->
<div class="modal-dialog modal-dialog-centered">
...
</div>
<!-- Vertically centered scrollable modal -->
<div class="modal-dialog modal-dialog-centered modal-dialog-scrollable">
...
</div>

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.

HTML
<div class="modal-body">
<h2 class="fs-5">Popover in a modal</h2>
<p>This <button class="btn btn-secondary" data-bs-toggle="popover" title="Popover title" data-bs-content="Popover body content is set in this attribute.">button</button> triggers a popover on click.</p>
<hr>
<h2 class="fs-5">Tooltips in a modal</h2>
<p><a href="#" data-bs-toggle="tooltip" title="Tooltip">This link</a> and <a href="#" data-bs-toggle="tooltip" title="Tooltip">that link</a> have tooltips on hover.</p>
</div>

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.

HTML
<div class="modal-body">
<div class="container-fluid">
<div class="row">
<div class="col-md-4">.col-md-4</div>
<div class="col-md-4 ms-auto">.col-md-4 .ms-auto</div>
</div>
<div class="row">
<div class="col-md-3 ms-auto">.col-md-3 .ms-auto</div>
<div class="col-md-2 ms-auto">.col-md-2 .ms-auto</div>
</div>
<div class="row">
<div class="col-md-6 ms-auto">.col-md-6 .ms-auto</div>
</div>
<div class="row">
<div class="col-sm-9">
Level 1: .col-sm-9
<div class="row">
<div class="col-8 col-sm-6">
Level 2: .col-8 .col-sm-6
</div>
<div class="col-4 col-sm-6">
Level 2: .col-4 .col-sm-6
</div>
</div>
</div>
</div>
</div>
</div>

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.

HTML
<button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModal" data-bs-whatever="@mdo">Open modal for @mdo</button>
<button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModal" data-bs-whatever="@fat">Open modal for @fat</button>
<button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModal" data-bs-whatever="@getbootstrap">Open modal for @getbootstrap</button>
<div class="modal fade" id="exampleModal" tabindex="-1" aria-labelledby="exampleModalLabel" aria-hidden="true">
<div class="modal-dialog">
<div class="modal-content">
<div class="modal-header">
<h1 class="modal-title fs-5" id="exampleModalLabel">New message</h1>
<button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
</div>
<div class="modal-body">
<form>
<div class="mb-3">
<label for="recipient-name" class="col-form-label">Recipient:</label>
<input type="text" class="form-control" id="recipient-name">
</div>
<div class="mb-3">
<label for="message-text" class="col-form-label">Message:</label>
<textarea class="form-control" id="message-text"></textarea>
</div>
</form>
</div>
<div class="modal-footer">
<button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button>
<button type="button" class="btn btn-primary">Send message</button>
</div>
</div>
</div>
</div>

site/assets/js/snippets.js

site/assets/js/snippets.js
const exampleModal = document.getElementById('exampleModal')
if (exampleModal) {
exampleModal.addEventListener('show.bs.modal', event => {
// Button that triggered the modal
const button = event.relatedTarget
// Extract info from data-bs-* attributes
const recipient = button.getAttribute('data-bs-whatever')
// If necessary, you could initiate an Ajax request here
// and then do the updating in a callback.
// Update the modal's content.
const modalTitle = exampleModal.querySelector('.modal-title')
const modalBodyInput = exampleModal.querySelector('.modal-body input')
modalTitle.textContent = `New message to ${recipient}`
modalBodyInput.value = recipient
})
}

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.

HTML
<div class="modal fade" id="exampleModalToggle" aria-hidden="true" aria-labelledby="exampleModalToggleLabel" tabindex="-1">
<div class="modal-dialog modal-dialog-centered">
<div class="modal-content">
<div class="modal-header">
<h1 class="modal-title fs-5" id="exampleModalToggleLabel">Modal 1</h1>
<button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
</div>
<div class="modal-body">
Show a second modal and hide this one with the button below.
</div>
<div class="modal-footer">
<button class="btn btn-primary" data-bs-target="#exampleModalToggle2" data-bs-toggle="modal">Open second modal</button>
</div>
</div>
</div>
</div>
<div class="modal fade" id="exampleModalToggle2" aria-hidden="true" aria-labelledby="exampleModalToggleLabel2" tabindex="-1">
<div class="modal-dialog modal-dialog-centered">
<div class="modal-content">
<div class="modal-header">
<h1 class="modal-title fs-5" id="exampleModalToggleLabel2">Modal 2</h1>
<button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
</div>
<div class="modal-body">
Hide this modal and show the first with the button below.
</div>
<div class="modal-footer">
<button class="btn btn-primary" data-bs-target="#exampleModalToggle" data-bs-toggle="modal">Back to first</button>
</div>
</div>
</div>
</div>
<button class="btn btn-primary" data-bs-target="#exampleModalToggle" data-bs-toggle="modal">Open first modal</button>

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.

HTML
<div class="modal" tabindex="-1" aria-labelledby="..." aria-hidden="true">
...
</div>

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ñoClaseAncho máximo del modal
Pequeño.modal-sm300px
PredeterminadoNinguno500px
Grande.modal-lg800px
Extra grande.modal-xl1140px

Nuestro modal predeterminado sin clase modificadora constituye el modal de tamaño “mediano”.

HTML
<div class="modal-dialog modal-xl">...</div>
<div class="modal-dialog modal-lg">...</div>
<div class="modal-dialog modal-sm">...</div>

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.

ClaseDisponibilidad
.modal-fullscreenSiempre
.modal-fullscreen-sm-down576px
.modal-fullscreen-md-down768px
.modal-fullscreen-lg-down992px
.modal-fullscreen-xl-down1200px
.modal-fullscreen-xxl-down1400px

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

HTML
<!-- Full screen modal -->
<div class="modal-dialog modal-fullscreen-sm-down">
...
</div>

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.

scss/_modal.scss

scss/_modal.scss
--#{$prefix}modal-zindex: #{$zindex-modal};
--#{$prefix}modal-width: #{$modal-md};
--#{$prefix}modal-padding: #{$modal-inner-padding};
--#{$prefix}modal-margin: #{$modal-dialog-margin};
--#{$prefix}modal-color: #{$modal-content-color};
--#{$prefix}modal-bg: #{$modal-content-bg};
--#{$prefix}modal-border-color: #{$modal-content-border-color};
--#{$prefix}modal-border-width: #{$modal-content-border-width};
--#{$prefix}modal-border-radius: #{$modal-content-border-radius};
--#{$prefix}modal-box-shadow: #{$modal-content-box-shadow-xs};
--#{$prefix}modal-inner-border-radius: #{$modal-content-inner-border-radius};
--#{$prefix}modal-header-padding-x: #{$modal-header-padding-x};
--#{$prefix}modal-header-padding-y: #{$modal-header-padding-y};
--#{$prefix}modal-header-padding: #{$modal-header-padding}; // Todo in v6: Split this padding into x and y
--#{$prefix}modal-header-border-color: #{$modal-header-border-color};
--#{$prefix}modal-header-border-width: #{$modal-header-border-width};
--#{$prefix}modal-title-line-height: #{$modal-title-line-height};
--#{$prefix}modal-footer-gap: #{$modal-footer-margin-between};
--#{$prefix}modal-footer-bg: #{$modal-footer-bg};
--#{$prefix}modal-footer-border-color: #{$modal-footer-border-color};
--#{$prefix}modal-footer-border-width: #{$modal-footer-border-width};

scss/_modal.scss

scss/_modal.scss
--#{$prefix}backdrop-zindex: #{$zindex-modal-backdrop};
--#{$prefix}backdrop-bg: #{$modal-backdrop-bg};
--#{$prefix}backdrop-opacity: #{$modal-backdrop-opacity};

Variables Sass generales relacionadas

scss/_variables.scss

scss/_variables.scss
$modal-inner-padding: $spacer;
$modal-footer-margin-between: .5rem;
$modal-dialog-margin: .5rem;
$modal-dialog-margin-y-sm-up: 1.75rem;
$modal-title-line-height: $line-height-base;
$modal-content-color: null;
$modal-content-bg: var(--#{$prefix}body-bg);
$modal-content-border-color: var(--#{$prefix}border-color-translucent);
$modal-content-border-width: var(--#{$prefix}border-width);
$modal-content-border-radius: var(--#{$prefix}border-radius-lg);
$modal-content-inner-border-radius: subtract($modal-content-border-radius, $modal-content-border-width);
$modal-content-box-shadow-xs: var(--#{$prefix}box-shadow-sm);
$modal-content-box-shadow-sm-up: var(--#{$prefix}box-shadow);
$modal-backdrop-bg: $black;
$modal-backdrop-opacity: .5;
$modal-header-border-color: var(--#{$prefix}border-color);
$modal-header-border-width: $modal-content-border-width;
$modal-header-padding-y: $modal-inner-padding;
$modal-header-padding-x: $modal-inner-padding;
$modal-header-padding: $modal-header-padding-y $modal-header-padding-x; // Keep this for backwards compatibility
$modal-footer-bg: null;
$modal-footer-border-color: $modal-header-border-color;
$modal-footer-border-width: $modal-header-border-width;
$modal-sm: 300px;
$modal-md: 500px;
$modal-lg: 800px;
$modal-xl: 1140px;
$modal-fade-transform: translate(0, -50px);
$modal-show-transform: none;
$modal-transition: transform .3s ease-out;
$modal-scale-transform: scale(1.02);

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.

scss/_modal.scss

scss/_modal.scss
@each $breakpoint in map-keys($grid-breakpoints) {
$infix: breakpoint-infix($breakpoint, $grid-breakpoints);
$postfix: if($infix != "", $infix + "-down", "");
@include media-breakpoint-down($breakpoint) {
.modal-fullscreen#{$postfix} {
width: 100vw;
max-width: none;
height: 100%;
margin: 0;
.modal-content {
height: 100%;
border: 0;
@include border-radius(0);
}
.modal-header,
.modal-footer {
@include border-radius(0);
}
.modal-body {
overflow-y: auto;
}
}
}
}

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.

HTML
<button type="button" data-bs-toggle="modal" data-bs-target="#myModal">Launch modal</button>

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:

HTML
<button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>

o en un botón fuera del modal usando el data-bs-target adicional como se muestra a continuación:

HTML
<button type="button" class="btn-close" data-bs-dismiss="modal" data-bs-target="#my-modal" aria-label="Close"></button>

Vía JavaScript

Crea un modal con una sola línea de JavaScript:

JavaScript
const myModal = new bootstrap.Modal(document.getElementById('myModal'), options)
// or
const myModalAlternative = new bootstrap.Modal('#myModal', 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.

NombreTipoPredeterminadoDescripción
backdropboolean, 'static'trueIncluye un elemento de fondo modal. Alternativamente, especifica static para un fondo que no cierre el modal al hacer clic.
focusbooleantruePone el foco en el modal cuando se inicializa.
keyboardbooleantrueCierra el modal cuando se presiona la tecla escape.

Métodos

Opciones de paso

Activa tu contenido como modal. Acepta opciones opcionales object.

JavaScript
const myModal = new bootstrap.Modal('#myModal', {
keyboard: false
})
MétodoDescripción
disposeDestruye el modal de un elemento. (Elimina los datos almacenados en el elemento DOM)
getInstanceStatic método que te permite obtener la instancia modal asociada con un elemento DOM.
getOrCreateInstanceStatic 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.
handleUpdateReajusta 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).
hideOculta 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 ).
showAbre 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).
toggleConmuta 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">).

EventoDescripción
hide.bs.modalEste evento se activa inmediatamente cuando se llama al método de instancia hide.
hidden.bs.modalEste evento se activa cuando el modal termina de ocultarse al usuario (esperará a que se completen las transiciones CSS).
hidePrevented.bs.modalEste 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.modalEste 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.modalEste 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.
JavaScript
const myModalEl = document.getElementById('myModal')
myModalEl.addEventListener('hidden.bs.modal', event => {
// do something...
})