Dialog
Editar perfil
import { Dialog } from '@rivocode/ui'Quando usar
Janela modal, para decisão que não pode continuar em segundo plano.
Compõe com DialogTrigger, DialogContent, DialogTitle, DialogDescription,
DialogFooter e DialogClose.
Renderiza em portal dentro do container do RivoProvider, que carrega o tema.
Sem o Provider ele lança erro, e não renderiza sem estilo.
Quando não usar
Para confirmar o que não volta atrás (excluir, cancelar uma assinatura, sair sem
salvar), use AlertDialog. Este aqui fecha com Esc e com clique fora, e é isso
que o separa do outro: uma janela que se dispensa por engano não serve para uma
pergunta cuja resposta errada não tem desfazer.
Para o painel que detalha o conteúdo da tela (o filtro de uma listagem, o
detalhe de um registro), prefira o Sheet. No celular os dois encostam
embaixo, e o Dialog já sai como folha sem os cantos de baixo, mas só a Sheet
fecha com o gesto de arrastar e, na mesa, abre pela lateral, ao lado do que ela
detalha, em vez de cobrir o meio da tela. E para o que só acrescenta
contexto ao lado de um botão (uma explicação, um formulário de duas linhas), o
Popover custa menos: o modal tranca o resto da página, e trancar a página para
mostrar um texto é cobrar caro por pouco.
No React Native
Traduz: o @rivocode/ui-native exporta Dialog - open, onOpenChange e title como props; sem DialogTrigger. Abre em fade, e sem transição quando o sistema pede para reduzir movimento; o cartão sobe para o espaço acima do teclado. A API não é a mesma do web (no nativo tudo é controlado), e a tabela de paridade diz o que muda peça a peça.
No iOS e no Android. A peça cobre a tela inteira, por cima da barra de status e da de navegação, e mede a área segura do aparelho com o react-native-safe-area-context, o mesmo número nos dois, e não a da tela, que a navegação zera embaixo do cabeçalho. No Android, o voltar do sistema fecha a peça. O iOS não tem voltar: fecha-se pelo botão da peça ou pelo gesto de escape do VoiceOver, o Z com dois dedos, que chama o mesmo fechar.
API
| Prop | Tipo | Padrão |
|---|---|---|
actionsRef0.4.0Uma ref para as ações imperativas. | RefObject<DialogRootActions | null> | sem padrão |
defaultOpen0.4.0Se o diálogo começa aberto. | boolean | false |
defaultTriggerId0.4.0ID do gatilho ao qual o diálogo está associado. | string | null | sem padrão |
disablePointerDismissal0.4.0Se o diálogo deixa de fechar com um clique do lado de fora. | boolean | false |
handle0.4.0Um elo para associar o diálogo a um gatilho. | DialogHandle<Payload> | sem padrão |
modal0.4.0Se o diálogo aberto fica em estado modal. | "trap-focus" | boolean | true |
onOpenChange0.4.0Chamado quando o diálogo abre ou fecha. | ((open: boolean, eventDetails: DialogRootChangeEventDetails) => void) | sem padrão |
onOpenChangeComplete0.4.0Chamado depois que as animações terminam, quando o diálogo abre ou fecha. | ((open: boolean) => void) | sem padrão |
open0.4.0Se o diálogo está aberto agora. | boolean | sem padrão |
triggerId0.4.0ID do gatilho ao qual o diálogo está associado. | string | null | sem padrão |
Partes
Dialog se monta com estas peças. Todas vivem nesta página, porque separar cada uma num endereço obrigaria a abrir seis abas para montar uma tela.
DialogClose
/dialog-close.mdFecha o diálogo sem você guardar estado.
Envolve o botão de cancelar, o X do canto ou qualquer coisa que deva fechar.
Com render, vira o elemento que você passar.
| Prop | Tipo | Padrão |
|---|---|---|
nativeButton0.4.0Se a peça renderiza um `<button>` nativo quando é trocada pela prop `render`. | boolean | true |
render0.4.0Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente. | ComponentRenderFn<HTMLProps, DialogCloseState> | ReactElement<unknown, string | JSXElementConstructor<any>> | sem padrão |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.
DialogContent
/dialog-content.mdO painel do diálogo, com a tarja de fundo e o portal já montados.
No desktop ele centraliza. No celular ele encosta embaixo e ocupa a largura toda, que é onde o polegar alcança, centralizado, sobraria tarja dos dois lados e o conteúdo ficaria espremido no meio da tela.
O portal usa o contêiner do RivoProvider, então o tema vale dentro dele.
| Prop | Tipo |
|---|---|
classNames0.5.0Classe por parte: `backdrop`. | Partial<Record<"backdrop", string>> |
finalFocus0.4.0O elemento que recebe o foco quando o diálogo fecha. | booleanRefObject<HTMLElement | null>((closeType: InteractionType) => void | boolean | HTMLElement | null) |
initialFocus0.4.0O elemento que recebe o foco quando o diálogo abre. | booleanRefObject<HTMLElement | null>((openType: InteractionType) => void | boolean | HTMLElement | null) |
render0.4.0Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente. | ComponentRenderFn<HTMLProps, DialogPopupState> | ReactElement<unknown, string | JSXElementConstructor<any>> |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.
DialogDescription
/dialog-description.mdA frase abaixo do título, com o que o diálogo pede.
Vira o aria-describedby do painel, então o leitor de tela lê o contexto junto
com o título, antes de chegar aos botões.
| Prop | Tipo |
|---|---|
render0.4.0Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente. | ComponentRenderFn<HTMLProps, DialogDescriptionState> | ReactElement<unknown, string | JSXElementConstructor<any>> |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.
DialogFooter
/dialog-footer.mdA fila de ações do diálogo, alinhada à direita.
A ação que confirma vai por último na marcação, encostada na borda: é a que o olho encontra por último no desktop.
No celular os dois botões empilham e ocupam a largura toda, porque o painel
já encosta embaixo e duas ações lado a lado numa tela estreita saem apertadas
demais. Na pilha a ordem se inverte: quem confirma sobe para o alto e quem
cancela fica rente ao polegar. É o mesmo comportamento do AlertDialogFooter.
Sem prop própria: repassa ao elemento de baixo o que você mandar.
DialogTitle
/dialog-title.mdO título do diálogo.
Não é enfeite: a Base UI liga ele no aria-labelledby do painel, e um diálogo
sem título é anunciado como "diálogo" e nada mais. Se o desenho não pede
título visível, mantenha a peça e esconda com sr-only.
| Prop | Tipo |
|---|---|
render0.4.0Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente. | ComponentRenderFn<HTMLProps, DialogTitleState> | ReactElement<unknown, string | JSXElementConstructor<any>> |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.
DialogTrigger
/dialog-trigger.mdO que abre o diálogo.
Por padrão sai como <button>. Para abrir a partir de outra peça, um item de
menu, um cartão inteiro, passe render com o elemento, e o estado de aberto
continua ligado no aria-expanded certo.
| Prop | Tipo | Padrão |
|---|---|---|
handle0.4.0Um elo para associar o gatilho a um diálogo. | DialogHandle<Payload> | sem padrão |
nativeButton0.4.0Se a peça renderiza um `<button>` nativo quando é trocada pela prop `render`. | boolean | true |
payload0.4.0Um dado a entregar ao diálogo quando ele abre. | Payload | sem padrão |
render0.4.0Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente. | ComponentRenderFn<HTMLProps, DialogTriggerState> | ReactElement<unknown, string | JSXElementConstructor<any>> | sem padrão |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.