'/%3e%3cg%20transform='translate(170%20205)%20scale(0.3606)'%20fill='%23111011'%3e%3cpath%20d='M497%20640H359L248%20320%20122%20640H0L256%200z'/%3e%3cpath%20d='M292.43%20640H200.8L248%20522z'/%3e%3cpath%20d='M335%200h138l111%20320L710%200h122L576%20640z'/%3e%3c/g%3e%3c/svg%3e){kind=small}
Capas
Modal
Un modal que contiene cualquier cosa: un formulario, una galería, un video, un asistente. Encabezado y pie opcionales, siete tamaños, centrado o arriba, scroll en el cuerpo o en todo el modal, multimedia a sangre y tres fondos.
import { Modal } from '@alea/ui';
Ejemplos
Cualquier contenido
Un disparador, un título y lo que quieras adentro: aquí una pequeña galería con un texto. El pie es una función que recibe close.
Contenido largo y scroll
scrollBehavior="inside" mantiene el encabezado y el pie en su lugar mientras el cuerpo hace scroll (formularios, términos, listas); "outside" deja que todo el modal haga scroll con la página, para lectura larga.
Multimedia a sangre
padding="none" deja que una imagen o un video toque los bordes; sin título el modal necesita un aria-label, y el botón de cerrar flota sobre la imagen. size="auto" se ajusta al contenido.
Tamaños, posición y fondos
size de xs (320 px) a xl (960 px), full o auto; placement="top" se queda quieto mientras el contenido crece (una búsqueda); backdrop es dim, blur o transparent. En teléfonos, fullscreenBelow="sm" ocupa toda la pantalla.
Un flujo dentro de un modal
Cambia el contenido en lugar de apilar modales: un encabezado con Steps, el cuerpo de cada paso, y el pie avanzando y retrocediendo.
¿Modal, Dialog o Drawer?
| Uso | Cuándo |
|---|---|
| Modal | Cualquier contenido: multimedia, galerías, flujos de varios pasos, formularios largos, tu propio diseño. |
| Dialog | Un título, una oración, quizá un campo, y dos botones. |
| AlertDialog | Confirmar algo que no se puede deshacer. |
| Drawer o Sheet | Detalles o filtros junto a la página, donde la gente no pierde su lugar. |
Tokens
Los tokens de diseño que usa este componente, con su valor en el tema actual. Cambia cualquiera para darle otro estilo.
Color
--alea-bg…--alea-border…--alea-surface…--alea-surface-overlay…
Space
--alea-space-2…--alea-space-3…--alea-space-4…
Radius
--alea-radius-lg…
Type
--alea-font-family-display…--alea-font-leading-tight…--alea-font-size-2xl…--alea-font-tracking-display…--alea-font-weight-light…
Shadow
--alea-shadow-card…--alea-shadow-pop…
Layer
--alea-z-modal…
Component
--alea-glass-blur…--alea-glass-rim…--alea-glass-saturate…--alea-glass-tint…
Props
Modal props
Un modal con cualquier contenido: encabezado y pie si los quieres, siete tamaños, centrado o arriba, scroll en el cuerpo o en todo el modal, multimedia a sangre, tres fondos. Atrapa el foco, se cierra con Escape y con un clic afuera, y devuelve el foco a lo que lo abrió. Para un título, un texto y dos botones, Dialog es más rápido; para confirmar algo destructivo, AlertDialog.
| Prop | Tipo | Por defecto | Descripción |
|---|---|---|---|
childrenobligatoria | Render | - | Cualquier cosa: un formulario, una galería, un video, un asistente, una página entera. Una función recibe close. |
aria-label | string | - | Nombre para lectores de pantalla cuando no hay título. |
backdrop | "blur" | "dim" | "transparent" | 'dim' | Lo que hay detrás: dim (por defecto), blur (oscurece y desenfoca) o transparent (solo para modales que ya se destacan). |
className | string | - | Clases extra para la superficie del modal. |
footer | Render | - | Contenido fijo abajo: acciones, un resumen. Una función recibe close. |
fullscreenBelow | "sm" | "md" | - | Ocupa toda la pantalla por debajo de este breakpoint (teléfonos): sm (640 px) o md (768 px). |
header | ReactNode | - | Tu propio encabezado en lugar de la fila del título (igual recibe el botón de cerrar). |
motion | MotionProp | - | Cómo entra y sale (por defecto rise): un preset, false, u opciones. |
padding | "none" | "normal" | 'normal' | normal (por defecto) o none, para multimedia que debe tocar los bordes (una imagen, un video, un mapa). |
placement | "center" | "top" | 'center' | center (por defecto) o top (se queda quieto mientras su contenido crece, ideal para búsqueda y formularios largos). |
scrollBehavior | "inside" | "outside" | 'inside' | inside: el encabezado y el pie se quedan, el cuerpo hace scroll (por defecto). outside: todo el modal hace scroll con la página, para lectura larga. |
showClose | boolean | true | Muestra el botón de cerrar. Por defecto true. |
size | "sm" | "md" | "lg" | "xl" | "xs" | "auto" | "full" | 'md' | xs 320, sm 400, md 560 (por defecto), lg 760, xl 960, full (toda la ventana menos un margen), o auto (tan ancho como su contenido). |
title | ReactNode | - | Un título en el encabezado, que se lee al abrirse. Sin título, dale al modal un aria-label. |
trigger | ReactNode | - | El botón (o cualquier elemento presionable) que lo abre. Omítelo y controla isOpen tú. |
Especificaciones
Generado desde el código: las variantes de los tipos, los estados y tokens del CSS, y los patrones de motion que aplican. Las grillas muestran el componente real en ambos temas; los números se miden en la página.
- Variantes
backdropblurdimtransparentfullscreenBelowsmmdpaddingnonenormalplacementcentertopscrollBehaviorinsideoutsidesizesmmdlgxlxsautofull- Motion
- riseAcepta una prop motion para su entrada y salida.
- Oscuro y claro
- Cada color viene de tokens del tema, así que sigue a data-theme (y a presets como Graphite) en la página o en cualquier contenedor. El contraste se revisa en ambos temas.
- Clases para estilos
.alea-modal-overlay.alea-xmodal-overlay.alea-modal.alea-xmodal.alea-xmodal-dialog.alea-xmodal-head.alea-dialog-title.alea-dialog-x.alea-xmodal-x.alea-xmodal-body.alea-xmodal-footer- Atributos data
data-size=smdata-size=lgdata-size=fulldata-fullscreen-below=smdata-fullscreen-below=mddata-size=xsdata-size=mddata-size=xldata-size=autodata-placement=topdata-backdrop=transparentdata-backdrop=dimdata-backdrop=blurdata-scroll=insidedata-padding=nonedata-scroll=outside
Accesibilidad
- El foco entra al modal y se queda ahí; al cerrarlo vuelve a lo que lo abrió.
- La página de atrás queda oculta para lectores de pantalla y no se puede desplazar.
- Su nombre es su título, o aria-label cuando no hay título (obligatorio en ese caso).
- El botón de cerrar siempre se puede alcanzar, también cuando el contenido tiene scroll o es multimedia a sangre.
- Escape y un clic en el fondo lo cierran; usa isDismissable={false} o isKeyboardDismissDisabled para trabajo que no se debe perder.
Teclado
| Tecla | Acción |
|---|---|
| Tab | Recorre el interior del modal |
| Shift+Tab | Recorre hacia atrás |
| Escape | Lo cierra |
Qué hacer y qué evitar
Hacer
- Usa un título, o un aria-label, para que los lectores de pantalla digan qué se abrió.
- Usa scrollBehavior="inside" en formularios y listas para que las acciones del pie sigan visibles.
- Usa placement="top" para contenido que crece mientras se escribe (búsqueda, filtros).
- Hazlo de pantalla completa en teléfonos (fullscreenBelow="sm") cuando el contenido es largo.
Evitar
- No abras un modal al cargar la página.
- No apiles modales: reemplaza el contenido, o usa pasos dentro de uno.
- No lo uses para un sí o no rápido: AlertDialog está hecho para eso.
- No uses backdrop="transparent" para contenido en el que hay que concentrarse.
En Figma
Modal con Size, Placement y Padding, y slots para encabezado, cuerpo y pie.