Primitiveoverlay

Dialog

Stable

Overlay modal com trigger, título, descrição, corpo rolável, rodapé e fechamento. Composto sobre Base UI Dialog e sobre o Button do Up Web DS.

Instalação

npx up-web-ds add dialog

Gera close para a biblioteca de ícones do projeto (components.json → iconLibrary).

Preview

Default

Destructive

With Form

Scrollable Content

Without Close Button

With Status

All states

Default

Destructive

With Form

Disable Overlay Close

Scrollable Content

Without Close Button

With Status

Usage

Imports de Dialog

import {
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from '@/components/ui/dialog'
import { Button } from '@/components/ui/button'

Dialog

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22<Dialog>
  <DialogTrigger render={<Button variant="outline" />}>
    Abrir dialog
  </DialogTrigger>

  <DialogContent>
    <DialogHeader>
      <DialogTitle>Publicar no registry</DialogTitle>
      <DialogDescription>
        O item passa a ficar disponível para os projetos da equipe via{' '}
        <code className="font-mono">npx shadcn@latest add</code>.
      </DialogDescription>
    </DialogHeader>

    <DialogFooter>
      <DialogClose render={<Button variant="outline" />}>
        Cancelar
      </DialogClose>
      <DialogClose render={<Button />}>Publicar</DialogClose>
    </DialogFooter>
  </DialogContent>
</Dialog>

Props

Dialog

Props de Dialog
Prop	Type	Default	Description
disableOverlayClose	`boolean`	`false`	Locks dismissal to the dialog's own close actions: a press on the overlay and the Escape key no longer close it, only a `DialogClose` (the footer's Cancelar, the popup's close button) or a controlled `open` does. For a dialog whose content would be lost if it closed by accident, such as a half-filled form.
actionsRef	`React.RefObject<DialogRootActions \| null>`	sem valor padrão	A ref to imperative actions. - `unmount`: Manually unmounts the dialog. Call this after any externally controlled closing animation finishes. - `close`: Closes the dialog imperatively when called.
children	`React.ReactNode \| PayloadChildRenderFunction<unknown>`	sem valor padrão	The content of the dialog. This can be a regular React node or a render function that receives the `payload` of the active trigger.
defaultOpen	`boolean`	`false`	Whether the dialog is initially open. To render a controlled dialog, use the `open` prop instead.
defaultTriggerId	`string \| null`	sem valor padrão	ID of the trigger that the dialog is associated with. This is useful in conjunction with the `defaultOpen` prop to create an initially open dialog.
disablePointerDismissal	`boolean`	`false`	Whether to prevent the dialog from closing on outside presses. For non-modal dialogs, this also prevents the dialog from closing when focus moves outside of it.
handle	`DialogHandle<unknown>`	sem valor padrão	A handle to associate the dialog with a trigger. If specified, allows external triggers to control the dialog's open state. Can be created with the Dialog.createHandle() method.
modal	`boolean \| "trap-focus"`	`true`	Determines if the dialog enters a modal state when open. - `true`: user interaction is limited to just the dialog: focus is trapped, document page scroll is locked, and pointer interactions on outside elements are disabled. - `false`: user interaction with the rest of the document is allowed. - `'trap-focus'`: focus is trapped inside the dialog, but document page scroll is not locked and pointer interactions outside of it remain enabled. When `modal` is `true` or `'trap-focus'`, render `<Dialog.Close>` inside `<Dialog.Popup>` so touch screen readers can escape the popup.
onOpenChange	`((open: boolean, eventDetails: DialogRoot.ChangeEventDetails) => void)`	sem valor padrão	Event handler called when the dialog is opened or closed.
onOpenChangeComplete	`((open: boolean) => void)`	sem valor padrão	Event handler called after any animations complete when the dialog is opened or closed.
open	`boolean`	sem valor padrão	Whether the dialog is currently open.
triggerId	`string \| null`	sem valor padrão	ID of the trigger that the dialog is associated with. This is useful in conjunction with the `open` prop to create a controlled dialog. There's no need to specify this prop when the dialog is uncontrolled (that is, when the `open` prop is not set).

Estende DialogPrimitive.Root.Props.

DialogTrigger

Props de DialogTrigger
Prop	Type	Default	Description
className	`string \| ((state: DialogTriggerState) => string \| undefined)`	sem valor padrão	CSS class applied to the element, or a function that returns a class based on the component's state.
handle	`DialogHandle<unknown>`	sem valor padrão	A handle to associate the trigger with a dialog. Can be created with the Dialog.createHandle() method.
id	`string`	sem valor padrão	ID of the trigger. In addition to being forwarded to the rendered element, it is also used to specify the active trigger for the dialog in controlled mode (with the DialogRoot `triggerId` prop).
nativeButton	`boolean`	`true`	Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`).
payload	`unknown`	sem valor padrão	A payload to pass to the dialog when it is opened.
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, DialogTriggerState>`	sem valor padrão	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	`React.CSSProperties \| ((state: DialogTriggerState) => React.CSSProperties \| undefined)`	sem valor padrão	Style applied to the element, or a function that returns a style object based on the component's state.

Estende DialogPrimitive.Trigger.Props. Aceita também os atributos padrão de um elemento React (284 não listados).

DialogPortal

Props de DialogPortal
Prop	Type	Default	Description
className	`string \| ((state: DialogPortalState) => string \| undefined)`	sem valor padrão	CSS class applied to the element, or a function that returns a class based on the component's state.
container	`HTMLElement \| ShadowRoot \| React.RefObject<HTMLElement \| ShadowRoot \| null> \| null`	sem valor padrão	A parent element to render the portal element into.
keepMounted	`boolean`	`false`	Whether to keep the portal mounted in the DOM while the popup is hidden.
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, DialogPortalState>`	sem valor padrão	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	`React.CSSProperties \| ((state: DialogPortalState) => React.CSSProperties \| undefined)`	sem valor padrão	Style applied to the element, or a function that returns a style object based on the component's state.

Estende DialogPrimitive.Portal.Props. Aceita também os atributos padrão de um elemento React (275 não listados).

DialogClose

Props de DialogClose
Prop	Type	Default	Description
className	`string \| ((state: DialogCloseState) => string \| undefined)`	sem valor padrão	CSS class applied to the element, or a function that returns a class based on the component's state.
nativeButton	`boolean`	`true`	Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`).
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, DialogCloseState>`	sem valor padrão	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	`React.CSSProperties \| ((state: DialogCloseState) => React.CSSProperties \| undefined)`	sem valor padrão	Style applied to the element, or a function that returns a style object based on the component's state.

Estende DialogPrimitive.Close.Props. Aceita também os atributos padrão de um elemento React (285 não listados).

DialogOverlay

Props de DialogOverlay
Prop	Type	Default	Description
className	`string \| ((state: DialogBackdropState) => string \| undefined)`	sem valor padrão	CSS class applied to the element, or a function that returns a class based on the component's state.
forceRender	`boolean`	`false`	Whether the backdrop is forced to render even when nested.
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, DialogBackdropState>`	sem valor padrão	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	`React.CSSProperties \| ((state: DialogBackdropState) => React.CSSProperties \| undefined)`	sem valor padrão	Style applied to the element, or a function that returns a style object based on the component's state.

Estende DialogPrimitive.Backdrop.Props. Aceita também os atributos padrão de um elemento React (275 não listados).

DialogPopup

Props de DialogPopup
Prop	Type	Default	Description
showCloseButton	`boolean`	`true`
className	`string \| ((state: DialogPopupState) => string \| undefined)`	sem valor padrão	CSS class applied to the element, or a function that returns a class based on the component's state.
finalFocus	`boolean \| React.RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => boolean \| HTMLElement \| null \| void)`	sem valor padrão	Determines the element to focus when the dialog is closed. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (trigger or previously focused element). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing.
initialFocus	`boolean \| React.RefObject<HTMLElement \| null> \| ((openType: InteractionType) => boolean \| HTMLElement \| null \| void)`	sem valor padrão	Determines the element to focus when the dialog is opened. By default, focus moves to the first tabbable element inside the popup, except when the dialog is opened by touch — then the popup itself is focused to avoid opening the virtual keyboard. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (first tabbable element or popup). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing.
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, DialogPopupState>`	sem valor padrão	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	`React.CSSProperties \| ((state: DialogPopupState) => React.CSSProperties \| undefined)`	sem valor padrão	Style applied to the element, or a function that returns a style object based on the component's state.

Estende DialogPopupProps. Aceita também os atributos padrão de um elemento React (275 não listados).

DialogViewport

Props de DialogViewport
Prop	Type	Default	Description
className	`string \| ((state: DialogViewportState) => string \| undefined)`	sem valor padrão	CSS class applied to the element, or a function that returns a class based on the component's state.
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, DialogViewportState>`	sem valor padrão	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	`React.CSSProperties \| ((state: DialogViewportState) => React.CSSProperties \| undefined)`	sem valor padrão	Style applied to the element, or a function that returns a style object based on the component's state.

Estende DialogPrimitive.Viewport.Props. Aceita também os atributos padrão de um elemento React (275 não listados).

DialogContent

Props de DialogContent
Prop	Type	Default	Description
overlayClassName	`string`	sem valor padrão	Additional presentation classes for the backdrop created by `DialogContent`. This lets recipes customise the visual treatment of the overlay while keeping portal, modal semantics, focus management and interaction behaviour owned by the Dialog primitive.
showCloseButton	`boolean`	sem valor padrão
className	`string \| ((state: DialogPopupState) => string \| undefined)`	sem valor padrão	CSS class applied to the element, or a function that returns a class based on the component's state.
finalFocus	`boolean \| React.RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => boolean \| HTMLElement \| null \| void)`	sem valor padrão	Determines the element to focus when the dialog is closed. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (trigger or previously focused element). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing.
initialFocus	`boolean \| React.RefObject<HTMLElement \| null> \| ((openType: InteractionType) => boolean \| HTMLElement \| null \| void)`	sem valor padrão	Determines the element to focus when the dialog is opened. By default, focus moves to the first tabbable element inside the popup, except when the dialog is opened by touch — then the popup itself is focused to avoid opening the virtual keyboard. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (first tabbable element or popup). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing.
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, DialogPopupState>`	sem valor padrão	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	`React.CSSProperties \| ((state: DialogPopupState) => React.CSSProperties \| undefined)`	sem valor padrão	Style applied to the element, or a function that returns a style object based on the component's state.

Estende DialogContentProps. Aceita também os atributos padrão de um elemento React (275 não listados).

DialogBody

Estende React.ComponentProps<'div'>. Aceita também os atributos padrão de um elemento React (280 não listados).

DialogFooter

Props de DialogFooter
Prop	Type	Default	Description
showCloseButton	`boolean`	`false`

Estende React.ComponentProps<'div'>. Aceita também os atributos padrão de um elemento React (280 não listados).

DialogTitle

Props de DialogTitle
Prop	Type	Default	Description
className	`string \| ((state: DialogTitleState) => string \| undefined)`	sem valor padrão	CSS class applied to the element, or a function that returns a class based on the component's state.
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, DialogTitleState>`	sem valor padrão	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	`React.CSSProperties \| ((state: DialogTitleState) => React.CSSProperties \| undefined)`	sem valor padrão	Style applied to the element, or a function that returns a style object based on the component's state.

Estende DialogPrimitive.Title.Props. Aceita também os atributos padrão de um elemento React (275 não listados).

DialogDescription

Props de DialogDescription
Prop	Type	Default	Description
className	`string \| ((state: DialogDescriptionState) => string \| undefined)`	sem valor padrão	CSS class applied to the element, or a function that returns a class based on the component's state.
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, DialogDescriptionState>`	sem valor padrão	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	`React.CSSProperties \| ((state: DialogDescriptionState) => React.CSSProperties \| undefined)`	sem valor padrão	Style applied to the element, or a function that returns a style object based on the component's state.

Estende DialogPrimitive.Description.Props. Aceita também os atributos padrão de um elemento React (275 não listados).

Composition

Gatilho e conteúdo são irmãos. O DialogClose pode estar em qualquer lugar dentro do conteúdo; no rodapé é onde ele vira ação.

Composição de Dialog

Dialog

DialogTrigger
DialogContent
- DialogHeader
  - DialogTitle
  - DialogDescription
- DialogBody
- DialogFooter
  - DialogClose

Metadata

Notas de acessibilidade

Teclado e leitor de tela verificados por teste: abre pelo trigger e pelo teclado, fecha com Escape e por DialogClose, e é nomeado/descrito por DialogTitle e DialogDescription. Touch verificado em viewport de 375px com emulação de toque: alvos de 32x32 (fechar) e 293x36 (ação do rodapé), acima do mínimo de 24x24 da WCAG 2.2 SC 2.5.8; abrir, rolar o corpo, fechar pela ação e descartar pelo backdrop funcionam por toque. Reduced motion verificado em navegador com prefers-reduced-motion: reduce: o zoom de entrada e saída é aplicado em motion-safe:, então sob reduce o popup aparece sem escala; o animate-in, o fade e a duração continuam incondicionais, porque é o animationend deles que o Base UI espera para desmontar. Verificado nos dois modos: abre, fecha, o foco entra e volta ao gatilho, e o popup não fica preso em opacidade parcial nem em transform intermediário.

Classificação

Layer: Primitive
Domínio: Domain-free (compartilhado)
Categoria: overlay
Status: Stable

Origem e distribuição

Fonte: shadcn registry / dialog
Licença: MIT
URL: https://ui.shadcn.com/r/styles/base-vega/dialog.json
Distribuição: Interna

Acessibilidade

Teclado: revisado
Leitor de tela: revisado
Touch: revisado
Reduced motion: revisado

Dependências

Pacotes: @base-ui/react
Ícones: close
Construído sobre: Button
Usado por: Dialog Stack Hero Video Dialog