Modal

Componente de diálogo para interacciones concentradas sobre la página actual, con captura del foco, bloqueo del desplazamiento e inertización del fondo.

Úsalo cuando necesites un diálogo para una interacción concentrada sobre la página, con captura del foco, bloqueo del desplazamiento e inertización del fondo. Gobierna <r-modal> con el atributo open o con los ayudantes imperativos Modal.confirm / Modal.info.

Inicio rápido

Uso básico

La visibilidad del modal se controla con el atributo open (o la propiedad open). Empieza cerrado y no dibuja nada hasta que se abre, así que conecta un disparador que lo alterne.

<r-button onclick="modal.open = true">Abrir modal</r-button>

<r-modal id="modal" heading="Modal básico">
  <p>Este es el contenido del modal.</p>
  <div slot="footer">
    <r-button type="primary" onclick="modal.open = false">Aceptar</r-button>
  </div>
</r-modal>

Referencia de la API

Propiedades

closing es un atributo de solo lectura que el elemento refleja sobre sí mismo (no una propiedad asignable): está presente desde el instante en que se ejecuta close() hasta que la transición de desvanecido y reducción de la máscara y el diálogo termina de verdad (~0,3 s después, la misma marca que el evento afterclose). Es útil para una página anfitriona que necesita que el modal siga contando como «presente» durante esa cola visual; véanse las buenas prácticas más abajo.

Título title

<r-modal open heading="Eliminar elemento">
  <p>¿Seguro que quieres eliminar este elemento?</p>
</r-modal>

Botón de cerrar closable

Oculta el botón de cerrar de la cabecera, de modo que el modal solo pueda descartarse desde tus propios controles.

<r-modal open heading="Términos" closable="false">
  <p>Debes aceptar los términos para continuar.</p>
  <div slot="footer">
    <r-button type="primary">Aceptar</r-button>
  </div>
</r-modal>

Cerrar con la máscara maskClosable

Por defecto, hacer clic en el fondo cierra el modal. Ponlo a false para exigir una acción explícita.

<r-modal open heading="Cambios sin guardar" maskClosable="false">
  <p>Hacer clic fuera no descartará este diálogo.</p>
</r-modal>

Cerrar con Escape closeOnEsc

<r-modal open heading="Informe" closeOnEsc="false">
  <p>La tecla Escape está desactivada para este diálogo.</p>
</r-modal>

Bloquear el desplazamiento lockScroll

<r-modal open heading="Vista previa" lockScroll="false">
  <p>La página detrás del modal todavía puede desplazarse.</p>
</r-modal>

Foco automático autoFocus

<r-modal open heading="Buscar" autoFocus="false">
  <input type="text" placeholder="Escribe para buscar" />
</r-modal>

Modo sin cabecera hideHeader

Suprime por completo la barra de título y su borde, y deja solo un botón de cerrar flotante (arriba a la derecha) cuando hay closable. Va bien para diálogos que son solo contenido, como una caja de luz con una imagen o un diagrama, donde una barra de título no haría más que comerse el contenido. El diálogo conserva un nombre accesible mediante aria-label (derivado de title) aunque el <h3> visible haya desaparecido, así que pon title para dar una etiqueta al lector de pantalla incluso en este modo.

<r-modal open hide-header>
  <img src="/diagram.png" alt="Diagrama de arquitectura" style="display: block; max-width: 100%;" />
</r-modal>

Slots

<r-modal open heading="Confirmar">
  <p>El contenido del cuerpo va en el slot por defecto.</p>
  <div slot="footer">
    <r-button onclick="modal.open = false">Cancelar</r-button>
    <r-button type="primary">Confirmar</r-button>
  </div>
</r-modal>

Eventos

Todos los eventos relacionados con el cierre llevan un trigger en event.detail que describe qué lo provocó: 'mask', 'button', 'escape' o 'program'.

<r-modal id="modal" heading="Ejemplo"></r-modal>

<script>
  const modal = document.getElementById('modal');

  modal.addEventListener('beforeclose', (e) => {
    if (!confirm('¿Descartar los cambios?')) e.preventDefault();
  });

  modal.addEventListener('close', (e) => {
    console.log('cerrado por', e.detail.trigger); // 'mask' | 'button' | 'escape' | 'program'
  });
</script>

API programática

La clase Modal expone ayudantes estáticos que crean, montan y resuelven un modal sin marcado. Cada uno devuelve una Promise<{ action, trigger }> donde action es 'confirm', 'cancel' o 'dismiss'.

Opciones (todas opcionales): title, content, okText, cancelText, showCancel, maskClosable, closeOnEsc, lockScroll, autoFocus, closable, onConfirm, onCancel. onConfirm / onCancel pueden devolver false (o una promesa que resuelva a false) para dejar el modal abierto.

import { Modal } from 'ranui/modal';

const result = await Modal.confirm({
  title: 'Eliminar proyecto',
  content: 'Esta acción no se puede deshacer.',
  okText: 'Eliminar',
  cancelText: 'Conservar',
  onConfirm: async () => {
    await deleteProject();
  },
});

if (result.action === 'confirm') {
  // eliminado
}

Parts CSS

Da estilo a las piezas internas con ::part().

r-modal::part(dialog) {
  border-radius: 8px;
}
r-modal::part(mask) {
  background: rgba(0, 0, 0, 0.6);
}

Estilos

<r-modal> expone 23 propiedades personalizadas de CSS propias, además de los tokens semánticos que lee del tema. Define una allí donde se herede: :root, un contenedor o el propio elemento:

r-modal {
  --ran-modal-mask-background: var(--ran-color-bg-subtle);
}

Partes: body · close · dialog · footer · header · mask · root · title

La lista completa está en tokens de estilo; cuál usar lo explica el sistema de diseño.

Buenas prácticas

• Disparador y alternancia: abre con modal.open = true y cierra con modal.open = false, o llama a close().
• Protege los cierres destructivos: escucha beforeclose y llama a preventDefault() para confirmar antes de descartar trabajo sin guardar.
• Acciones del pie: pon los botones primario y secundario en slot="footer"; la barra del pie solo aparece cuando el slot tiene contenido.
• Flujos que no se descartan: pon closable="false" y maskClosable="false" para forzar una elección explícita.
• Diálogos puntuales: usa Modal.confirm / Modal.info para preguntas rápidas en lugar de escribir marcado.
• Elevar una página anfitriona por encima del modal mientras está abierto: haz coincidir :has(r-modal[open]), :has(r-modal[closing]), no solo [open]. open desaparece en el instante en que se ejecuta close(), pero la transición de la máscara y el diálogo sigue pintando unos 0,3 s más; retirar la elevación de z-index a mitad del desvanecido deja que la máscara, todavía visible, se repinte por debajo de aquello sobre lo que estaba levantada.