Modal

Diálogo que interrompe a tela para uma tarefa curta e focada.

O Modal abre uma camada sobre a tela para uma tarefa curta, como renomear uma Fonte ou ler um token. Ele bloqueia o resto da página até fechar. Para confirmar uma ação destrutiva use AlertDialog; para editar um objeto com vários campos, use Sheet.

import { Modal } from "@rastreio-x/ui";

Padrão

O gatilho (um Button) fica ao lado de Modal.Backdrop, que contém Modal.Container e Modal.Dialog. O rodapé tem a ação principal e a de cancelar; slot="close" fecha o diálogo.

Tamanhos

size no Modal.Container: xs, sm, md (padrão), lg, cover e full. Prefira md para formulários curtos.

Com formulário

Coloque o foco no primeiro campo com autoFocus. O rótulo do botão de salvar diz o que será salvo.

Controlado

Com isOpen e onOpenChange no Modal.Backdrop, o estado fica com você: abra por qualquer evento e feche depois de concluir a ação.

Estado: fechado

Fundo

Modal.Backdrop aceita opaque (padrão), blur e transparent.

Anatomia

Modal
├── Modal.Backdrop
├── Modal.Body
├── Modal.CloseTrigger
├── Modal.Container
├── Modal.Dialog
├── Modal.Footer
├── Modal.Header
├── Modal.Heading
├── Modal.Icon
└── Modal.Trigger

Modal.Backdrop: o fundo, que fecha ao clicar fora (isDismissable).
Modal.Container: posiciona e dimensiona o diálogo.
Modal.Dialog: a superfície do diálogo, com o papel dialog.
Modal.Header, Modal.Heading e Modal.Icon: o cabeçalho.
Modal.Body e Modal.Footer: o conteúdo e as ações.
Modal.CloseTrigger: o botão de fechar no canto.

Propriedades

Fundo (Modal.Backdrop):

Modal.Backdrop
Prop	Tipo	Padrão	Descrição
`children`	`ChildrenOrFunction<ModalRenderProps>`	-	Conteúdo do componente.
`className`	`ClassNameOrFunction<ModalRenderProps>`	`'react-aria-ModalOverlay'`	Classes CSS aplicadas ao elemento.
`defaultOpen`	`boolean`	-	Abre o elemento na primeira renderização (não controlado).
`isDismissable`	`boolean`	`true`	Permite fechar clicando fora ou arrastando.
`isEntering`	`boolean`	-	Indica que a animação de entrada está em andamento.
`isExiting`	`boolean`	-	Indica que a animação de saída está em andamento.
`isKeyboardDismissDisabled`	`boolean`	`false`	Impede que a tecla Esc feche a camada.
`isOpen`	`boolean`	-	Controla se o elemento está aberto (controlado).
`onOpenChange`	`((isOpen: boolean) => void)`	-	Chamada quando o elemento abre ou fecha.
`render`	`DOMRenderFunction<'div', ModalRenderProps>`	-	Troca o elemento DOM padrão por outro, mantendo o comportamento e as props do componente.
`shouldCloseOnInteractOutside`	`((element: Element) => boolean)`	-	Decide se uma interação fora da camada a fecha.
`style`	`StyleOrFunction<ModalRenderProps>`	-	Estilos em linha aplicados ao elemento.
`UNSTABLE_portalContainer`	`Element`	`document.body`	Elemento que recebe o portal da camada. Interface instável.
`variant`	`'blur' \| 'opaque' \| 'transparent'`	-	Fundo atrás da camada: `blur` (desfocado), `opaque` ou `transparent`.

Contêiner (Modal.Container):

Modal.Container
Prop	Tipo	Padrão	Descrição
`children`	`ChildrenOrFunction<ModalRenderProps>`	-	Conteúdo do componente.
`className`	`ClassNameOrFunction<ModalRenderProps>`	`'react-aria-ModalOverlay'`	Classes CSS aplicadas ao elemento.
`placement`	`ModalPlacement`	-	Posição do modal: `auto`, `top`, `center` ou `bottom`.
`scroll`	`'inside' \| 'outside'`	-	Onde rola o conteúdo longo: `inside` (dentro do modal) ou `outside` (a página).
`size`	`'cover' \| 'lg' \| 'md' \| 'sm' \| 'xs' \| 'full'`	-	Largura do modal: `xs`, `sm`, `md`, `lg`, `cover` ou `full`.

Animações

CSS
indicativo

O fundo faz fade e o diálogo entra com opacity e transform em transição curta. Com prefers-reduced-motion, a folha global da fachada reduz as transições a 0,01 ms e o diálogo aparece sem movimento.

Acessibilidade

Padrão WAI-ARIA de diálogo modal: o foco fica preso dentro do diálogo e volta ao gatilho ao fechar.
Esc fecha (desligue com isKeyboardDismissDisabled); Tab percorre os controles.
O título (Modal.Heading) dá o nome ao diálogo; o fundo da página fica inerte e a rolagem é travada.
Modal.CloseTrigger tem nome acessível localizado.

Boas práticas

Faça

Título que diz a tarefa e botão com o verbo da ação: Salvar Nome.

Evite

Rótulos genéricos como OK e Confirmar, ou um modal dentro de outro modal.

Uma tarefa por modal, curta; para fluxos longos, use uma página ou Sheet.
A ação principal à direita, no rodapé; cancelar ao lado, com peso menor.
Não abra modal sem ação da pessoa (exceto erros críticos).
Para ações destrutivas, use AlertDialog.

Relacionados

AlertDialog para confirmações que exigem decisão.
Sheet para edição ou detalhe com mais conteúdo.
Button para o gatilho e as ações do rodapé.