Pular para o conteúdo
Sobreposição

Dialog

/componentes/dialog.mdmarkdown cru, para quem lê com agent em vez de olho

Editar perfil

Importar
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

PropTipoPadrão
actionsRef0.4.0

Uma ref para as ações imperativas.

RefObject<DialogRootActions | null>sem padrão
defaultOpen0.4.0

Se o diálogo começa aberto.

booleanfalse
defaultTriggerId0.4.0

ID do gatilho ao qual o diálogo está associado.

string | nullsem padrão
disablePointerDismissal0.4.0

Se o diálogo deixa de fechar com um clique do lado de fora.

booleanfalse
handle0.4.0

Um elo para associar o diálogo a um gatilho.

DialogHandle<Payload>sem padrão
modal0.4.0

Se o diálogo aberto fica em estado modal.

"trap-focus" | booleantrue
onOpenChange0.4.0

Chamado quando o diálogo abre ou fecha.

((open: boolean, eventDetails: DialogRootChangeEventDetails) => void)sem padrão
onOpenChangeComplete0.4.0

Chamado depois que as animações terminam, quando o diálogo abre ou fecha.

((open: boolean) => void)sem padrão
open0.4.0

Se o diálogo está aberto agora.

booleansem padrão
triggerId0.4.0

ID do gatilho ao qual o diálogo está associado.

string | nullsem 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.md

Fecha 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.

PropTipoPadrão
nativeButton0.4.0

Se a peça renderiza um `<button>` nativo quando é trocada pela prop `render`.

booleantrue
render0.4.0

Troca 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.md

O 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.

PropTipo
classNames0.5.0

Classe por parte: `backdrop`.

Partial<Record<"backdrop", string>>
finalFocus0.4.0

O elemento que recebe o foco quando o diálogo fecha.

booleanRefObject<HTMLElement | null>((closeType: InteractionType) => void | boolean | HTMLElement | null)
initialFocus0.4.0

O elemento que recebe o foco quando o diálogo abre.

booleanRefObject<HTMLElement | null>((openType: InteractionType) => void | boolean | HTMLElement | null)
render0.4.0

Troca 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.md

A 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.

PropTipo
render0.4.0

Troca 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.md

A 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.md

O 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.

PropTipo
render0.4.0

Troca 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.md

O 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.

PropTipoPadrão
handle0.4.0

Um elo para associar o gatilho a um diálogo.

DialogHandle<Payload>sem padrão
nativeButton0.4.0

Se a peça renderiza um `<button>` nativo quando é trocada pela prop `render`.

booleantrue
payload0.4.0

Um dado a entregar ao diálogo quando ele abre.

Payloadsem padrão
render0.4.0

Troca 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.

@rivocode/ui, 149 peças no catálogo. Esta página é gerada dos mesmos arquivos que alimentam o design system, então ela não envelhece sozinha.

Feito por RivoCode.