Pular para o conteúdo
Sobreposição

AlertDialog

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

Cancelamento

Importar
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

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
handle0.4.0

Um identificador que associa o diálogo de alerta a um gatilho.

AlertDialogHandle<Payload>sem padrão
onOpenChange0.4.0

Chamado quando o diálogo de alerta abre ou fecha.

((open: boolean, eventDetails: AlertDialogRootChangeEventDetails) => 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

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

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

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.

AlertDialogContent

/alert-dialog-content.md

O 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" }}>
PropTipo
classNames

Classe por parte: `backdrop` e `error`.

Partial<Record<"backdrop" | "error", string>>
error

A frase de erro dentro do modal, quando a acao falhou e o modal ficou aberto: "Nao foi possivel cancelar a nota.

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

AlertDialogDescription

/alert-dialog-description.md

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

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.

AlertDialogFooter

/alert-dialog-footer.md

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

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

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.

AlertDialogTrigger

/alert-dialog-trigger.md

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

PropTipoPadrão
handle0.4.0

Um identificador que associa o gatilho a um diálogo de alerta.

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