AlertDialog
Cancelamento
import { AlertDialog } from '@rivocode/ui'Quando usar
A confirmação de coisa que não volta atrás: excluir, cancelar assinatura, sair sem salvar.
Compõe com AlertDialogTrigger, AlertDialogContent, AlertDialogTitle,
AlertDialogDescription, AlertDialogFooter e AlertDialogClose.
Não fecha com clique fora, e o foco começa no botão de cancelar. O Esc fecha, e
equivale a Cancelar: é o que o padrão de alertdialog da WAI-ARIA pede, e sair
sem fazer nada é o resultado seguro. Quem está prestes a apagar algo tem que
dizer que sim de propósito, no botão que confirma, e não esbarrar num clique.
No celular os botões empilham e ocupam a largura toda.
Quando a ação falha
O modal que confirma uma ação de rede não fecha antes de ela voltar, e quando
ela falha, diz isso dentro dele. error no AlertDialogContent é a frase:
sai acima dos botões do AlertDialogFooter, em danger-text, e é anunciada
ao leitor de tela. Para o modal ficar aberto, o botão que confirma é um
Button comum, e não um AlertDialogClose, e quem fecha é o sucesso:
const [open, setOpen] = useState(false)
const {
mutate: cancel,
isPending: canceling,
isError: failed,
} = useMutation({ mutationFn: cancelInvoice, onSuccess: () => setOpen(false) })
<AlertDialog open={open} onOpenChange={(next) => !canceling && setOpen(next)}>
<AlertDialogTrigger render={<Button variant="danger" />}>Cancelar nota</AlertDialogTrigger>
<AlertDialogContent error={failed ? 'Não foi possível cancelar a nota. Tente de novo.' : undefined}>
<AlertDialogTitle>Cancelar a nota 4813?</AlertDialogTitle>
<AlertDialogDescription>O cliente é avisado por e-mail.</AlertDialogDescription>
<AlertDialogFooter>
<AlertDialogClose render={<Button variant="secondary" />}>Manter nota</AlertDialogClose>
<Button variant="danger" loading={canceling} onClick={() => cancel()}>
Cancelar nota
</Button>
</AlertDialogFooter>
</AlertDialogContent>
</AlertDialog>
O useMutation limpa o erro no próximo mutate, e a frase sai junto. Sem
AlertDialogFooter, ela vai para o fim do modal. classNames.error veste a
caixa dela.
Quando não usar
Para qualquer outra janela modal (um formulário, um detalhe, uma escolha que
tem desfazer), use Dialog. O que este cobra a mais é sair pela porta: sem
clique fora, quem abriu por engano sai pelo Esc ou lendo os botões.
Cobrar isso de toda janela treina a pessoa a clicar em confirmar sem ler, que é
exatamente o hábito que ele existe para impedir.
No React Native
Traduz: o @rivocode/ui-native exporta AlertDialog - onConfirm, onCancel e labels em vez de composição, com os nomes do Popconfirm; tone danger ou neutral, e onConfirm que devolve promessa segura o modal em espera até ela terminar; promessa que rejeita deixa a frase de labels.error (ou o error de fora) dentro do modal, como o Popconfirm do web, e o error também é o nome do AlertDialogContent de lá; não fecha no toque fora, como no web. 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. O toque no fundo não fecha, nos dois.
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 |
handle0.4.0Um identificador que associa o diálogo de alerta a um gatilho. | AlertDialogHandle<Payload> | sem padrão |
onOpenChange0.4.0Chamado quando o diálogo de alerta abre ou fecha. | ((open: boolean, eventDetails: AlertDialogRootChangeEventDetails) => 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
AlertDialog 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.
AlertDialogClose
/alert-dialog-close.mdFecha sem confirmar.
Aqui ele é obrigatório na prática, e não uma conveniência: sem clique fora, e com o Esc só para quem tem teclado, este é o único caminho de saída visível do painel. Envolva o botão de cancelar com ele, e não deixe uma confirmação sair sem um.
| 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.
AlertDialogContent
/alert-dialog-content.mdO painel da confirmação, com a tarja e o portal por dentro.
Não fecha com clique fora, e é a única diferença que importa em relação ao
DialogContent. O Esc fecha, e vale como Cancelar. O foco começa no botão que cancela: quem abriu por
engano sai apertando Enter, e sair é o que ele deve conseguir fazer sem ler.
No celular os botões empilham e ocupam a largura toda, com o que confirma no alto da pilha e o que cancela rente ao polegar.
A tarja é irmã do painel dentro do portal, então nem className nem variante de
descendente alcançam ela. Para vestir a tarja, use classNames com a parte
backdrop:
<AlertDialogContent classNames={{ backdrop: "backdrop-blur-md" }}>
| Prop | Tipo |
|---|---|
classNamesClasse por parte: `backdrop` e `error`. | Partial<Record<"backdrop" | "error", string>> |
errorA frase de erro dentro do modal, quando a acao falhou e o modal ficou aberto: "Nao foi possivel cancelar a nota. | ReactNode |
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.
AlertDialogDescription
/alert-dialog-description.mdA consequência, em uma frase, ligada ao painel por aria-describedby.
É onde mora o que não volta atrás: o que se perde junto, quem mais enxerga a mudança, se há como desfazer. Confirmação sem essa linha pede um sim sobre uma informação que ninguém deu.
| 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.
AlertDialogFooter
/alert-dialog-footer.mdA fila com cancelar e confirmar.
O que confirma vai por último na marcação e costuma ser variant="danger", para
a cor concordar com o texto. No celular os dois empilham e ocupam a largura
toda, com o que confirma no alto da pilha e o cancelar rente ao polegar.
Sem prop própria: repassa ao elemento de baixo o que você mandar.
AlertDialogTitle
/alert-dialog-title.mdA pergunta, e o nome do painel para o leitor de tela.
Escreva o que vai acontecer, e não "Tem certeza?". "Excluir o projeto Site novo?" pode ser respondido por quem só leu o título; "Tem certeza?" obriga a ler o resto para descobrir do que se trata.
| 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.
AlertDialogTrigger
/alert-dialog-trigger.mdO que abre a confirmação.
Costuma ser o botão de excluir da linha ou do rodapé. Passe render com ele em
vez de aninhar um botão dentro de outro, e deixe o texto do gatilho dizer o
que vai acontecer, porque "Excluir" prepara a pergunta que vem, e "Ok" não.
| Prop | Tipo | Padrão |
|---|---|---|
handle0.4.0Um identificador que associa o gatilho a um diálogo de alerta. | AlertDialogHandle<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.