Dialog

<Highlights features={[ Comes with styling, yet completely customizable and themeable., Accepts animations, themes, size props and more., Accessible with dev-time checks to ensure ARIA props., ]} />

Dialog is a great way to show content inside a new floating window above content. Dialogs automatically stack above other overlays. Be sure to open the code example above for a copy-paste implementation.

Installation

Dialog is already installed in tamagui, or you can install it independently:

npm install @tamagui/dialog

Anatomy

import { Dialog } from 'tamagui' // or '@tamagui/dialog'

export default () => (
  <Dialog>
    <Dialog.Trigger />
    <Dialog.Portal>
      <Dialog.Overlay />
      <Dialog.Content>
        <Dialog.Title />
        <Dialog.Description />
        <Dialog.Close />
      </Dialog.Content>
    </Dialog.Portal>
    <Dialog.FocusScope loop trapped focusOnIdle={true}>
      <Dialog.FocusScope.Scope>
      </Dialog.FocusScope.Scope>
    </Dialog.FocusScope>
  </Dialog>
)

Scoping

Dialog supports scoping which lets you mount one or more Dialog instances at the root of your app, while having a deeply nested child Trigger or Content attach to the proper parent Dialog instance.

In performance sensitive areas you may want to take advantage of this, it allows you to only need to render the Dialog.Trigger inside the sensitive area as Dialogs aren't the cheapest component - they have a lot of functionality.

Here's the basic anatomy of using scope and placing your Dialog higher up for performance:

import { Dialog } from 'tamagui'

// in your root layout:
export default ({ children }) => (
  <Dialog scope="user-profile">
    <Dialog.Portal>
      <Dialog.Overlay />
      <Dialog.Content>
        <Dialog.Title />
        <Dialog.Description />
        <Dialog.Close />
      </Dialog.Content>
    </Dialog.Portal>
    {children}
  </Dialog>
)

export default () => (
  <Dialog.Trigger scope="user-profile">
    <Button>Open Profile</Button>
  </Dialog.Trigger>
)

Note that the Trigger scope ties to the Dialog scope.

Dismissal Behavior

By default, dialogs can be dismissed by:

• Clicking outside the dialog content (on the overlay)
• Pressing the Escape key
• Clicking a Dialog.Close element

Modal vs Non-Modal Dialogs

• Modal dialogs (modal={true}, which is the default):
  • In v1, have disableOutsidePointerEvents set to true by default
  • Still dismiss on outside click, but prevent interaction with elements behind the dialog
  • Prevent right-click dismissal (right-clicks on the overlay are ignored)
• Non-modal dialogs (modal={false}):
  • Allow interaction with elements behind the dialog
  • Dismiss on any outside click
  • Do not trap focus

Preventing Outside Dismissal

To prevent a dialog from closing when clicking outside:

<Dialog.Content
  onPointerDownOutside={(event) => {
    event.preventDefault()
  }}
>
</Dialog.Content>

API Reference

Dialog

Contains every component for the dialog. Beyond Tamagui Props, adds:

<PropsTable data={[ { name: 'children', type: 'React.ReactNode', required: true, description: Must contain Dialog.Content, }, { name: 'size', type: 'SizeTokens', description: Passes size down to all sub-components when set for padding, arrow, borderRadius., }, { name: 'open', type: 'boolean', description: Controlled open state of the dialog., }, { name: 'defaultOpen', type: 'boolean', description: Initial open state when uncontrolled., }, { name: 'onOpenChange', type: '(open: boolean) => void', description: Called when the dialog opens or closes., }, { name: 'modal', type: 'boolean', default: 'true', description: Renders into root of app instead of inline., }, { name: 'keepChildrenMounted', type: 'boolean', default: 'false', description: When true, dialog content stays mounted in the DOM even when closed. Useful for preserving state across open/close cycles or when you need faster re-opening., }, { name: 'disableRemoveScroll', type: 'boolean', required: false, description: Used to disable the automatic removal of scrolling from the page when open., }, ]} />

Dialog.Trigger

Just Tamagui Props.

Dialog.Portal

Renders Dialog into appropriate container. Beyond Tamagui Props, adds:

<PropsTable data={[ { name: 'forceMount', type: 'boolean', required: false, description: Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries., }, { name: 'unstyled', required: false, type: boolean, description: Removes all default Tamagui styles., }, ]} />

Dialog.Content

Main container for Dialog content, this is where you should apply animations.

Beyond Tamagui Props, adds:

<PropsTable data={[ { name: 'forceMount', type: 'boolean', required: false, description: Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries., }, { name: 'unstyled', required: false, type: boolean, description: Removes all default Tamagui styles., }, { name: 'disableOutsidePointerEvents', type: 'boolean', required: false, description: When true, hover/focus/click interactions will be disabled on elements outside the Dialog. Users will need to click twice on outside elements to interact with them: once to close the Dialog, and again to trigger the element. Note: In v1, modal dialogs have this set to true by default., }, ]} />

Dialog.Overlay

Displays behind Content. Beyond Tamagui Props, adds:

<PropsTable data={[ { name: 'forceMount', type: 'boolean', required: false, description: Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries., }, ]} />

Dialog.Title

Required. Can wrap in VisuallyHidden to hide.

Defaults to H2, see Headings.

Dialog.Description

Required. Can wrap in VisuallyHidden to hide.

Defaults to Paragraph, see Paragraph.

Dialog.Close

Closes the Dialog, accepts the same props as YStack. Recommended to use with your own component and asChild.

<PropsTable data={[ { name: 'displayWhenAdapted', type: 'boolean', description: By default Close elements hide when Adapt is active. If set to true, they will show when adapted., }, ]} />

Just Tamagui Props.

Dialog.FocusScope

Provides access to the underlying FocusScope component used by Dialog for focus management. Can be used to control focus behavior from a parent component.

<PropsTable data={[ { name: 'enabled', type: 'boolean', default: 'true', description: Whether focus management is enabled, }, { name: 'loop', type: 'boolean', default: 'false', description: When true, tabbing from last item will focus first tabbable and shift+tab from first item will focus last tabbable, }, { name: 'trapped', type: 'boolean', default: 'false', description: When true, focus cannot escape the focus scope via keyboard, pointer, or programmatic focus, }, { name: 'focusOnIdle', type: 'boolean | number', default: 'false', description: When true, waits for idle before focusing. When a number, waits that many ms. This prevents reflows during animations, }, { name: 'onMountAutoFocus', type: '(event: Event) => void', description: Event handler called when auto-focusing on mount. Can be prevented, }, { name: 'onUnmountAutoFocus', type: '(event: Event) => void', description: Event handler called when auto-focusing on unmount. Can be prevented, }, ]} />

Dialog.Sheet

When used with Adapt, Dialog will render as a sheet when that breakpoint is active.

See Sheet for more props.

Must use Adapt.Contents inside the Dialog.Sheet.Frame to insert the contents given to Dialog.Content

import { Dialog } from 'tamagui' // or '@tamagui/dialog'

export default () => (
  <Dialog>
    <Dialog.Trigger />

    <Dialog.Portal>
      <Dialog.Overlay />
      <Dialog.Content>
        <Dialog.Title />
        <Dialog.Description />
        <Dialog.Close />
      </Dialog.Content>
    </Dialog.Portal>
    <Dialog.Adapt when="max-md">
      <Dialog.Sheet>
        <Dialog.Sheet.Frame>
          <Dialog.Adapt.Contents />
        </Dialog.Sheet.Frame>
        <Dialog.Sheet.Overlay />
      </Dialog.Sheet>
    </Dialog.Adapt>
  </Dialog>
)