Report an issue

Dialog

A modal window presenting content or seeking user input without navigating away from the current context.

	<script lang="ts">
  import { Dialog, Label, Separator } from "bits-ui";
  import LockKeyOpen from "phosphor-svelte/lib/LockKeyOpen";
  import X from "phosphor-svelte/lib/X";
</script>
 
<Dialog.Root>
  <Dialog.Trigger
    class="inline-flex h-12 items-center
	justify-center whitespace-nowrap rounded-input bg-dark px-[21px]
	text-[15px] font-semibold text-background shadow-mini transition-colors hover:bg-dark/95 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-foreground focus-visible:ring-offset-2 focus-visible:ring-offset-background active:scale-98"
  >
    New API key
  </Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Overlay
      class="fixed inset-0 z-50 bg-black/80 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0"
    />
    <Dialog.Content
      class="fixed left-[50%] top-[50%] z-50 w-full max-w-[94%] translate-x-[-50%] translate-y-[-50%] rounded-card-lg border bg-background p-5 shadow-popover outline-none data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[state=closed]:slide-out-to-left-1/2 data-[state=closed]:slide-out-to-top-[48%] data-[state=open]:slide-in-from-left-1/2 data-[state=open]:slide-in-from-top-[48%] sm:max-w-[490px] md:w-full"
    >
      <Dialog.Title
        class="flex w-full items-center justify-center text-lg font-semibold tracking-tight"
        >Create API key</Dialog.Title
      >
      <Separator.Root class="-mx-5 mb-6 mt-5 block h-px bg-muted" />
      <Dialog.Description class="text-sm text-foreground-alt">
        Create and manage API keys. You can create multiple keys to organize
        your applications.
      </Dialog.Description>
      <div class="flex flex-col items-start gap-1 pb-11 pt-7">
        <Label.Root for="apiKey" class="text-sm font-medium">API Key</Label.Root
        >
        <div class="relative w-full">
          <input
            id="apiKey"
            class="inline-flex h-input w-full items-center rounded-card-sm border border-border-input bg-background px-4 text-sm placeholder:text-foreground-alt/50 hover:border-dark-40 focus:outline-none focus:ring-2 focus:ring-foreground focus:ring-offset-2 focus:ring-offset-background"
            placeholder="secret_api_key"
            type="password"
            autocomplete="off"
          />
          <LockKeyOpen
            class="absolute right-4 top-[14px] size-[22px] text-dark/30"
          />
        </div>
      </div>
      <div class="flex w-full justify-end">
        <Dialog.Close
          class="inline-flex h-input items-center justify-center rounded-input bg-dark px-[50px] text-[15px] font-semibold text-background shadow-mini hover:bg-dark/95 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-dark focus-visible:ring-offset-2 focus-visible:ring-offset-background active:scale-98"
        >
          Save
        </Dialog.Close>
      </div>
      <Dialog.Close
        class="absolute right-5 top-5 rounded-md focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-foreground focus-visible:ring-offset-2 focus-visible:ring-offset-background active:scale-98"
      >
        <div>
          <X class="size-5 text-foreground" />
          <span class="sr-only">Close</span>
        </div>
      </Dialog.Close>
    </Dialog.Content>
  </Dialog.Portal>
</Dialog.Root>

Structure

	<script lang="ts">
	import { Dialog } from "bits-ui";
</script>
 
<Dialog.Root>
	<Dialog.Trigger />
	<Dialog.Portal>
		<Dialog.Overlay />
		<Dialog.Content>
			<Dialog.Title />
			<Dialog.Description />
			<Dialog.Close />
		</Dialog.Content>
	</Dialog.Portal>
</Dialog.Root>

Reusable Components

Bits UI provides a decent number of components to construct a Dialog. The idea is to provide a set of building blocks that can be used to create a variety of different layouts. It's recommended to use these components to build your own reusable Dialog components that can be used throughout your application.

The following example shows at a high level how you might create a reusable Dialog component. We've mixed and matched string props and snippets to demonstrate the flexibility of the component API. Use whatever makes sense for you.

MyDialog.svelte
	<script lang="ts">
	import type { Snippet } from "svelte";
	import { Dialog, type WithoutChild } from "bits-ui";
 
	type Props = Dialog.RootProps & {
		buttonText: string;
		title: Snippet;
		description: Snippet;
		contentProps?: WithoutChild<Dialog.ContentProps>;
		// ...other component props if you wish to pass them
	};
 
	let {
		open = $bindable(false),
		children,
		buttonText,
		contentProps,
		title,
		description,
		...restProps
	}: Props = $props();
</script>
 
<Dialog.Root bind:open {...restProps}>
	<Dialog.Trigger>
		{buttonText}
	</Dialog.Trigger>
	<Dialog.Portal>
		<Dialog.Overlay />
		<Dialog.Content {...contentProps}>
			<Dialog.Title>
				{@render title()}
			</Dialog.Title>
			<Dialog.Description>
				{@render description()}
			</Dialog.Description>
			{@render children?.()}
			<Dialog.Close>Close Dialog</Dialog.Close>
		</Dialog.Content>
	</Dialog.Portal>
</Dialog.Root>

You can then use the MyDialog component in your application like so:

	<script lang="ts">
	import MyDialog from "$lib/components/MyDialog.svelte";
</script>
 
<MyDialog buttonText="Open Dialog">
	{#snippet title()}
		Account settings
	{/snippet}
 
	{#snippet description()}
		Manage your account settings and preferences.
	{/snippet}
 
	<!-- Additional dialog content here... -->
</MyDialog>

Alternatively, you can define the snippets separately and pass them as props to the component:

	<script lang="ts">
	import MyDialog from "$lib/components/MyDialog.svelte";
</script>
 
{#snippet title()}
	Account settings
{/snippet}
 
{#snippet description()}
	Manage your account settings and preferences.
{/snippet}
 
<MyDialog buttonText="Open Dialog" {title} {description}>
	<!-- Additional dialog content here... -->
</MyDialog>

Managing Open State

Bits UI provides flexible options for controlling and synchronizing the Dialog's open state.

Two-Way Binding

Use the bind:open directive for effortless two-way synchronization between your local state and the Dialog's internal state.

	<script lang="ts">
	import { Dialog } from "bits-ui";
	let isOpen = $state(false);
</script>
 
<button on:click={() => (isOpen = true)}>Open Dialog</button>
 
<Dialog.Root bind:open={isOpen}>
	<!-- Dialog content -->
</Dialog.Root>

This setup enables opening the Dialog via the custom button and ensures the local isOpen state updates when the Dialog closes through any means (e.g., escape key).

Change Handler

You can also use the onOpenChange prop to update local state when the Dialog's open state changes. This is useful when you don't want two-way binding for one reason or another, or you want to perform additional logic when the Dialog opens or closes.

	<script lang="ts">
	import { Dialog } from "bits-ui";
	let isOpen = $state(false);
</script>
 
<Dialog.Root
	open={isOpen}
	onOpenChange={(open) => {
		isOpen = open;
		// additional logic here.
	}}
>
	<!-- ... -->
</Dialog.Root>

Managing Focus

Focus Trap

By default, when a Dialog is opened, focus will be trapped within the Dialog, preventing the user from interacting with the rest of the page. This follows the WAI-ARIA design pattern for modal dialogs.

Although it isn't recommended unless absolutely necessary, you can disabled this beahvior by setting the trapFocus prop to false on the Dialog.Content component.

	<Dialog.Content trapFocus={false}>
	<!-- ... -->
</Dialog.Content>

Open Focus

By default, when a Dialog is opened, focus will be set to the first focusable element with the Dialog.Content. This ensures that users navigating my keyboard end up somewhere within the Dialog that they can interact with.

You can override this behavior using the onOpenAutoFocus prop on the Dialog.Content component. It's highly recommended that you use this prop to focus something within the Dialog.

You'll first need to cancel the default behavior of focusing the first focusable element by cancelling the event passed to the onOpenAutoFocus callback. You can then focus whatever you wish.

	<script lang="ts">
	import { Dialog } from "bits-ui";
	let nameInput = $state<HTMLInputElement>();
</script>
 
<Dialog.Root>
	<Dialog.Trigger>Open Dialog</Dialog.Trigger>
	<Dialog.Content
		onOpenAutoFocus={(e) => {
			e.preventDefault();
			nameInput?.focus();
		}}
	>
		<input type="text" bind:this={nameInput} />
	</Dialog.Content>
</Dialog.Root>

Close Focus

By default, when a Dialog is closed, focus will be set to the trigger element of the Dialog. You can override this behavior using the onCloseAutoFocus prop on the Dialog.Content component.

You'll need to cancel the default behavior of focusing the trigger element by cancelling the event passed to the onCloseAutoFocus callback, and then focus whatever you wish.

	<script lang="ts">
	import { Dialog } from "bits-ui";
	let nameInput = $state<HTMLInputElement>();
</script>
 
<input type="text" bind:this={nameInput} />
<Dialog.Root>
	<Dialog.Trigger>Open Dialog</Dialog.Trigger>
	<Dialog.Content
		onCloseAutoFocus={(e) => {
			e.preventDefault();
			nameInput?.focus();
		}}
	>
		<!-- ... -->
	</Dialog.Content>
</Dialog.Root>

Scroll Lock

By default, when a Dialog is opened, scrolling the body will be disabled, which provides a more native experience for users. If you wish to disable this behavior, you can set the preventScroll prop to false on the Dialog.Content component.

	<Dialog.Content preventScroll={false}>
	<!-- ... -->
</Dialog.Content>

Escape Keydown

By default, when a Dialog is open, pressing the Escape key will close the dialog. Bits UI provides a couple ways to override this behavior.

escapeKeydownBehavior

You can set the escapeKeydownBehavior prop to 'ignore' on the Dialog.Content component to prevent the dialog from closing when the Escape key is pressed.

	<Dialog.Content escapeKeydownBehavior="ignore">
	<!-- ... -->
</Dialog.Content>

onEscapeKeydown

You can also override the default behavior by cancelling the event passed to the onEscapeKeydown callback on the Dialog.Content component.

	<Dialog.Content onEscapeKeydown={(e) => e.preventDefault()}>
	<!-- ... -->
</Dialog.Content>

Interact Outside

By default, when a Dialog is open, pressing the outside the content will close the dialog. Bits UI provides a couple ways to override this behavior.

interactOutsideBehavior

You can set the interactOutsideBehavior prop to 'ignore' on the Dialog.Content component to prevent the dialog from closing when the user interacts outside the content.

	<Dialog.Content interactOutsideBehavior="ignore">
	<!-- ... -->
</Dialog.Content>

onInteractOutside

You can also override the default behavior by cancelling the event passed to the onInteractOutside callback on the Dialog.Content component.

	<Dialog.Content onInteractOutside={(e) => e.preventDefault()}>
	<!-- ... -->
</Dialog.Content>

Nested Dialogs

Dialogs can be nested within each other to create more complex layouts.

	<script lang="ts">
	import MyDialog from "$lib/components/MyDialog.svelte";
</script>
 
<MyDialog buttonText="Open first dialog">
	{#snippet title()}
		First Dialog
	{/snippet}
	{#snippet description()}
		This is the first dialog.
	{/snippet}
	<MyDialog buttonText="Open second dialog">
		{#snippet title()}
			Second Dialog
		{/snippet}
		{#snippet description()}
			This is the second dialog.
		{/snippet}
	</MyDialog>
</MyDialog>

Svelte Transitions

You can use the forceMount prop along with the child snippet to forcefully mount the Dialog.Content and Dialog.Overlay components to use Svelte Transitions or another animation library that requires more control.

	<script lang="ts">
	import { Dialog } from "bits-ui";
	import { fly, fade } from "svelte/transition";
</script>
 
<Dialog.Root>
	<!-- ... other dialog components -->
	<Dialog.Overlay forceMount>
		{#snippet child({ props, open })}
			{#if open}
				<div {...props} transition:fade>
					<!-- ... -->
				</div>
			{/if}
		{/snippet}
	</Dialog.Overlay>
	<Dialog.Content forceMount>
		{#snippet child({ props, open })}
			{#if open}
				<div {...props} transition:fly>
					<!-- ... -->
				</div>
			{/if}
		{/snippet}
	</Dialog.Content>
</Dialog.Root>

Of course, this isn't the prettiest syntax, so it's recommended to create your own reusable content and overlay components that handle this logic if you intend to use this approach. For more information on using transitions with Bits UI components, see the Transitions documentation.

API Reference

Dialog.Root

The root component used to set and manage the state of the dialog.

Property Type Description
open bindable prop
boolean

Whether or not the dialog is open.

Default: false
onOpenChange
function

A callback function called when the open state changes.

Default: undefined
children
Snippet

The children content to render.

Default: undefined

Dialog.Trigger

The element which opens the dialog on press.

Property Type Description
ref bindable prop
HTMLButtonElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See delegation docs for more information.

Default: undefined
Data Attribute Value Description
data-dialog-trigger
''

Present on the trigger.

Dialog.Portal

A portal which renders the dialog into the body when it is open.

Property Type Description
to
union

Where to render the content when it is open. Defaults to the body. Can be disabled by passing null

Default: body
disabled
boolean

Whether the portal is disabled or not. When disabled, the content will be rendered in its original DOM location.

Default: false
children
Snippet

The children content to render.

Default: undefined

Dialog.Content

The content displayed within the dialog modal.

Property Type Description
onEscapeKeydown
function

Callback fired when an escape keydown event occurs in the floating content. You can call event.preventDefault() to prevent the default behavior of handling the escape keydown event.

Default: undefined
escapeKeydownBehavior
enum

The behavior to use when an escape keydown event occurs in the floating content. 'close' will close the content immediately. 'ignore' will prevent the content from closing. 'defer-otherwise-close' will defer to the parent element if it exists, otherwise it will close the content. 'defer-otherwise-ignore' will defer to the parent element if it exists, otherwise it will ignore the interaction.

Default: close
onInteractOutside
function

Callback fired when an outside interaction event completes, which is either a pointerup, mouseup, or touchend event, depending on the user's input device. You can call event.preventDefault() to prevent the default behavior of handling the outside interaction.

Default: undefined
onInteractOutsideStart
function

Callback fired when an outside interaction event starts, which is either a pointerdown, mousedown, or touchstart event, depending on the user's input device. You can call event.preventDefault() to prevent the continuation of the outside interaction.

Default: undefined
onFocusOutside
function

Callback fired when focus leaves the dismissable layer. You can call event.preventDefault() to prevent the default behavior on focus leaving the layer.

Default: undefined
interactOutsideBehavior
enum

The behavior to use when an interaction occurs outside of the floating content. 'close' will close the content immediately. 'ignore' will prevent the content from closing. 'defer-otherwise-close' will defer to the parent element if it exists, otherwise it will close the content. 'defer-otherwise-ignore' will defer to the parent element if it exists, otherwise it will ignore the interaction.

Default: close
onOpenAutoFocus
function

Event handler called when auto-focusing the content as it is opened. Can be prevented.

Default: undefined
onCloseAutoFocus
function

Event handler called when auto-focusing the content as it is closed. Can be prevented.

Default: undefined
trapFocus
boolean

Whether or not to trap the focus within the content when open.

Default: true
forceMount
boolean

Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.

Default: false
preventOverflowTextSelection
boolean

When true, prevents the text selection from overflowing the bounds of the element.

Default: true
preventScroll
boolean

When true, prevents the body from scrolling when the content is open. This is useful when you want to use the content as a modal.

Default: true
ref bindable prop
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See delegation docs for more information.

Default: undefined
Data Attribute Value Description
data-state
enum

The state of the dialog.

data-dialog-content
''

Present on the content.

Dialog.Overlay

An overlay which covers the body when the dialog is open.

Property Type Description
forceMount
boolean

Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.

Default: false
ref bindable prop
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See delegation docs for more information.

Default: undefined
Data Attribute Value Description
data-state
enum

The state of the dialog.

data-dialog-overlay
''

Present on the overlay.

Dialog.Close

A button used to close the dialog.

Property Type Description
ref bindable prop
HTMLButtonElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See delegation docs for more information.

Default: undefined
Data Attribute Value Description
data-dialog-close
''

Present on the close button.

Dialog.Title

An accessibile title for the dialog.

Property Type Description
level
union

The heading level of the title.

Default: 3
ref bindable prop
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See delegation docs for more information.

Default: undefined
Data Attribute Value Description
data-dialog-title
''

Present on the title.

Dialog.Description

An accessibile description for the dialog.

Property Type Description
ref bindable prop
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See delegation docs for more information.

Default: undefined
Data Attribute Value Description
data-dialog-description
''

Present on the description.