Dialog

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

llms.txt 
	<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="rounded-input bg-dark text-background
	  shadow-mini hover:bg-dark/95 focus-visible:ring-foreground focus-visible:ring-offset-background focus-visible:outline-hidden
	  inline-flex h-12 items-center justify-center whitespace-nowrap px-[21px] text-[15px] font-semibold transition-colors focus-visible:ring-2 focus-visible:ring-offset-2 active:scale-[0.98]"
  >
    New API key
  </Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Overlay
      class="data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 fixed inset-0 z-50 bg-black/80"
    />
    <Dialog.Content
      class="rounded-card-lg bg-background shadow-popover 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 outline-hidden fixed left-[50%] top-[50%] z-50 w-full max-w-[calc(100%-2rem)] translate-x-[-50%] translate-y-[-50%] border p-5 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="bg-muted -mx-5 mb-6 mt-5 block h-px" />
      <Dialog.Description class="text-foreground-alt text-sm">
        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="h-input rounded-card-sm border-border-input bg-background placeholder:text-foreground-alt/50 hover:border-dark-40 focus:ring-foreground focus:ring-offset-background focus:outline-hidden inline-flex w-full items-center border px-4 text-base focus:ring-2 focus:ring-offset-2 sm:text-sm"
            placeholder="secret_api_key"
            name="name"
          />
          <LockKeyOpen
            class="text-dark/30 absolute right-4 top-[14px] size-[22px]"
          />
        </div>
      </div>
      <div class="flex w-full justify-end">
        <Dialog.Close
          class="h-input rounded-input bg-dark text-background shadow-mini hover:bg-dark/95 focus-visible:ring-dark focus-visible:ring-offset-background focus-visible:outline-hidden inline-flex items-center justify-center px-[50px] text-[15px] font-semibold focus-visible:ring-2 focus-visible:ring-offset-2 active:scale-[0.98]"
        >
          Save
        </Dialog.Close>
      </div>
      <Dialog.Close
        class="focus-visible:ring-foreground focus-visible:ring-offset-background focus-visible:outline-hidden absolute right-5 top-5 rounded-md focus-visible:ring-2 focus-visible:ring-offset-2 active:scale-[0.98]"
      >
        <div>
          <X class="text-foreground size-5" />
          <span class="sr-only">Close</span>
        </div>
      </Dialog.Close>
    </Dialog.Content>
  </Dialog.Portal>
</Dialog.Root>

Overview

The Dialog component in Bits UI provides a flexible and accessible way to create modal dialogs in your Svelte applications. It follows a compound component pattern, allowing for fine-grained control over the dialog's structure and behavior while maintaining accessibility and ease of use.

Key Features

  • Compound Component Structure: Offers a set of sub-components that work together to create a fully-featured dialog.
  • Accessibility: Built with WAI-ARIA guidelines in mind, ensuring keyboard navigation and screen reader support.
  • Customizable: Each sub-component can be styled and configured independently.
  • Portal Support: Content can be rendered in a portal, ensuring proper stacking context.
  • Managed Focus: Automatically manages focus, with the option to take control if needed.
  • Flexible State Management: Supports both controlled and uncontrolled state, allowing for full control over the dialog's open state.

Architecture

The Dialog component is composed of several sub-components, each with a specific role:

  • Root: The main container component that manages the state of the dialog. Provides context for all child components.
  • Trigger: A button that toggles the dialog's open state.
  • Portal: Renders its children in a portal, outside the normal DOM hierarchy.
  • Overlay: A backdrop that sits behind the dialog content.
  • Content: The main container for the dialog's content.
  • Title: Renders the dialog's title.
  • Description: Renders a description or additional context for the dialog.
  • Close: A button that closes the dialog.

Structure

Here's an overview of how the Dialog component is structured in code:

	<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 comprehensive set of Dialog components that serve as building blocks for creating customized, reusable Dialog implementations. This approach offers flexibility in design while maintaining consistency and accessibility across your application.

Building a Reusable Dialog

The following example demonstrates how to create a versatile, reusable Dialog component using Bits UI building blocks. This implementation showcases the flexibility of the component API by combining props and snippets.

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>

Usage with Inline Snippets

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

Usage with Separate Snippets

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

Best Practices

  • Prop Flexibility: Design your component to accept props for any nested components for maximum flexibility
  • Styling Options: Use tools like clsx to merge class overrides
  • Binding Props: Use bind: and expose $bindable props to provide consumers with full control
  • Type Safety: Use the exported types from Bits UI to type your component props

Managing Open State

This section covers how to manage the open state of the component.

Two-Way Binding

Use bind:open for simple, automatic state synchronization:

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

Fully Controlled

Use a Function Binding for complete control over the state's reads and writes.

	<script lang="ts">
	import { Dialog } from "bits-ui";
	let myOpen = $state(false);
 
	function getOpen() {
		return myOpen;
	}
 
	function setOpen(newOpen: boolean) {
		myOpen = newOpen;
	}
</script>
 
<Dialog.Root bind:open={getOpen, setOpen}>
	<!-- ... -->
</Dialog.Root>

Focus Management

Proper focus management is crucial for accessibility and user experience in modal dialogs. Bits UI's Dialog component provides several features to help you manage focus effectively.

Focus Trap

By default, the Dialog implements a focus trap, adhering to the WAI-ARIA design pattern for modal dialogs. This ensures that keyboard focus remains within the Dialog while it's open, preventing users from interacting with the rest of the page.

Disabling the Focus Trap

While not recommended, you can disable the focus trap if absolutely necessary:

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

Open Focus

When a Dialog opens, focus is automatically set to the first focusable element within Dialog.Content. This ensures keyboard users can immediately interact with the Dialog contents.

Customizing Initial Focus

To specify which element receives focus when the Dialog opens, use the onOpenAutoFocus prop on Dialog.Content:

	<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

When a Dialog closes, focus returns to the element that triggered its opening (typically the Dialog.Trigger).

Customizing Close Focus

To change which element receives focus when the Dialog closes, use the onCloseAutoFocus prop on Dialog.Content:

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

Best Practices

  • Always maintain a clear focus management strategy for your Dialogs.
  • Ensure that focus is predictable and logical for keyboard users.
  • Test your focus management with keyboard navigation to verify its effectiveness.

Advanced Behaviors

Bits UI's Dialog component offers several advanced features to customize its behavior and enhance user experience. This section covers scroll locking, escape key handling, and interaction outside the dialog.

Scroll Lock

By default, when a Dialog opens, scrolling the body is disabled. This provides a more native-like experience, focusing user attention on the dialog content.

Customizing Scroll Behavior

To allow body scrolling while the dialog is open, use the preventScroll prop on Dialog.Content:

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

Escape Key Handling

By default, pressing the Escape key closes an open Dialog. Bits UI provides two methods to customize this behavior.

Method 1: escapeKeydownBehavior

The escapeKeydownBehavior prop allows you to customize the behavior taken by the component when the Escape key is pressed. It accepts one of the following values:

  • 'close' (default): Closes the Dialog immediately.
  • 'ignore': Prevents the Dialog from closing.
  • 'defer-otherwise-close': If an ancestor Bits UI component also implements this prop, it will defer the closing decision to that component. Otherwise, the Dialog will close immediately.
  • 'defer-otherwise-ignore': If an ancestor Bits UI component also implements this prop, it will defer the closing decision to that component. Otherwise, the Dialog will ignore the key press and not close.

To always prevent the Dialog from closing on Escape key press, set the escapeKeydownBehavior prop to 'ignore' on Dialog.Content:

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

Method 2: onEscapeKeydown

For more granular control, override the default behavior using the onEscapeKeydown prop:

	<Dialog.Content
	onEscapeKeydown={(e) => {
		e.preventDefault();
		// do something else instead
	}}
>
	<!-- ... -->
</Dialog.Content>

This method allows you to implement custom logic when the Escape key is pressed.

Interaction Outside

By default, interacting outside the Dialog content area closes the Dialog. Bits UI offers two ways to modify this behavior.

Method 1: interactOutsideBehavior

The interactOutsideBehavior prop allows you to customize the behavior taken by the component when an interaction (touch, mouse, or pointer event) occurs outside the content. It accepts one of the following values:

  • 'close' (default): Closes the Dialog immediately.
  • 'ignore': Prevents the Dialog from closing.
  • 'defer-otherwise-close': If an ancestor Bits UI component also implements this prop, it will defer the closing decision to that component. Otherwise, the Dialog will close immediately.
  • 'defer-otherwise-ignore': If an ancestor Bits UI component also implements this prop, it will defer the closing decision to that component. Otherwise, the Dialog will ignore the event and not close.

To always prevent the Dialog from closing when an interaction occurs outside the content, set the interactOutsideBehavior prop to 'ignore' on Dialog.Content:

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

Method 2: onInteractOutside

For custom handling of outside interactions, you can override the default behavior using the onInteractOutside prop:

	<Dialog.Content
	onInteractOutside={(e) => {
		e.preventDefault();
		// do something else instead
	}}
>
	<!-- ... -->
</Dialog.Content>

This approach allows you to implement specific behaviors when users interact outside the Dialog content.

Best Practices

  • Scroll Lock: Consider your use case carefully before disabling scroll lock. It may be necessary for dialogs with scrollable content or for specific UX requirements.
  • Escape Keydown: Overriding the default escape key behavior should be done thoughtfully. Users often expect the escape key to close modals.
  • Outside Interactions: Ignoring outside interactions can be useful for important dialogs or multi-step processes, but be cautious not to trap users unintentionally.
  • Accessibility: Always ensure that any customizations maintain or enhance the dialog's accessibility.
  • User Expectations: Try to balance custom behaviors with common UX patterns to avoid confusing users.

By leveraging these advanced features, you can create highly customized dialog experiences while maintaining usability and accessibility standards.

Nested Dialogs

Dialogs can be nested within each other to create more complex user interfaces:

	<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

The Dialog component can be enhanced with Svelte's built-in transition effects or other animation libraries.

Using forceMount and child Snippets

To apply Svelte transitions to Dialog components, use the forceMount prop in combination with the child snippet. This approach gives you full control over the mounting behavior and animation of Dialog.Content and Dialog.Overlay.

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

In this example:

  • The forceMount prop ensures the components are always in the DOM.
  • The child snippet provides access to the open state and component props.
  • Svelte's #if block controls when the content is visible.
  • Transition directives (transition:fade and transition:fly) apply the animations.

Best Practices

For cleaner code and better maintainability, consider creating custom reusable components that encapsulate this transition logic.

MyDialogOverlay.svelte
	<script lang="ts">
	import { Dialog, type WithoutChildrenOrChild } from "bits-ui";
	import { fade } from "svelte/transition";
	import type { Snippet } from "svelte";
 
	let {
		ref = $bindable(null),
		duration = 200,
		children,
		...restProps
	}: WithoutChildrenOrChild<Dialog.OverlayProps> & {
		duration?: number;
		children?: Snippet;
	} = $props();
</script>
 
<Dialog.Overlay forceMount bind:ref {...restProps}>
	{#snippet child({ props, open })}
		{#if open}
			<div {...props} transition:fade={{ duration }}>
				{@render children?.()}
			</div>
		{/if}
	{/snippet}
</Dialog.Overlay>

You can then use the MyDialogOverlay component alongside the other Dialog primitives throughout your application:

	<script lang="ts">
	import { Dialog } from "bits-ui";
	import { MyDialogOverlay } from "$lib/components";
</script>
 
<Dialog.Root>
	<Dialog.Trigger>Open</Dialog.Trigger>
	<Dialog.Portal>
		<MyDialogOverlay duration={300} />
		<Dialog.Content>
			<!-- ... -->
		</Dialog.Content>
	</Dialog.Portal>
</Dialog.Root>

Working with Forms

Form Submission

When using the Dialog component, often you'll want to submit a form or perform an asynchronous action and then close the dialog.

This can be done by waiting for the asynchronous action to complete, then programmatically closing the dialog.

	<script lang="ts">
	import { Dialog } from "bits-ui";
 
	function wait(ms: number) {
		return new Promise((resolve) => setTimeout(resolve, ms));
	}
 
	let open = $state(false);
</script>
 
<Dialog.Root bind:open>
	<Dialog.Portal>
		<Dialog.Overlay />
		<Dialog.Content>
			<Dialog.Title>Confirm your action</Dialog.Title>
			<Dialog.Description>Are you sure you want to do this?</Dialog.Description>
			<form
				method="POST"
				action="?/someAction"
				onsubmit={() => {
					wait(1000).then(() => (open = false));
				}}
			>
				<button type="submit">Submit form</Dialog.Action>
			</form>
		</Dialog.Content>
	</Dialog.Portal>
</Dialog.Root>

Inside a Form

If you're using a Dialog within a form, you'll need to ensure that the Portal is disabled or not included in the Dialog structure. This is because the Portal will render the dialog content outside of the form, which will prevent the form from being submitted correctly.

API Reference

Dialog.Root

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

Property Details
open
onOpenChange
children
Data Attribute Details

Dialog.Trigger

The element which opens the dialog on press.

Property Details
ref
children
child
Data Attribute Details
data-dialog-trigger

Dialog.Portal

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

Property Details
to
disabled
children
Data Attribute Details

Dialog.Content

The content displayed within the dialog modal.

Property Details
onEscapeKeydown
escapeKeydownBehavior
onInteractOutside
onFocusOutside
interactOutsideBehavior
onOpenAutoFocus
onCloseAutoFocus
trapFocus
forceMount
preventOverflowTextSelection
preventScroll
restoreScrollDelay
ref
children
child
Data Attribute Details
data-state
data-dialog-content

Dialog.Overlay

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

Property Details
forceMount
ref
children
child
Data Attribute Details
data-state
data-dialog-overlay

Dialog.Close

A button used to close the dialog.

Property Details
ref
children
child
Data Attribute Details
data-dialog-close

Dialog.Title

An accessible title for the dialog.

Property Details
level
ref
children
child
Data Attribute Details
data-dialog-title

Dialog.Description

An accessible description for the dialog.

Property Details
ref
children
child
Data Attribute Details
data-dialog-description