Report an issue

Dialog

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

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>

Controlled Usage

If you want to control or be aware of the open state of the dialog from outside of the component, you can bind to the open prop.

	<script lang="ts">
	import { Dialog } from "bits-ui";
	let dialogOpen = false;
</script>
 
<button on:click={() => (dialogOpen = true)}>Open Dialog</button>
<Dialog.Root bind:open={dialogOpen}>
	<Dialog.Trigger />
	<Dialog.Portal>
		<Dialog.Overlay />
		<Dialog.Content>
			<Dialog.Title />
			<Dialog.Description />
			<Dialog.Close />
		</Dialog.Content>
	</Dialog.Portal>
</Dialog.Root>

API Reference

Dialog.Root

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

Property Type Description
preventScroll
boolean

Whether or not to prevent scroll on the body when the dialog is open.

Default: true
closeOnEscape
boolean

Whether to close the dialog when the escape key is pressed.

Default: true
closeOnOutsideClick
boolean

Whether to close the dialog when a click occurs outside of it.

Default: true
open
boolean

Whether or not the dialog is open.

Default: false
onOpenChange
function

A callback function called when the open state changes.

Default:  —— undefined
openFocus
FocusProp

Override the initial focus when the dialog is opened.

Default:  —— undefined
closeFocus
FocusProp

Override the focus when the dialog is closed.

Default:  —— undefined
portal
union

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

Default:  —— undefined
onOutsideClick
function

A callback function called when a click occurs outside of the element. If event.preventDefault() is called, the default behavior of closing the element will be prevented.

Default:  —— undefined
Slot Property Type Description
ids
object

The ids of the elements within the component, useful when you don't necessarily want to provide a custom ID, but still want access to the ID being assigned (if any).

Dialog.Trigger

The element which opens the dialog on press.

Property Type Description
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLButtonElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default:  —— undefined
Slot Property Type Description
builder
object

The builder attributes and actions to apply to the element if using the asChild prop with delegation.

Data Attribute Value Description
data-dialog-trigger
——

Present on the trigger.

Dialog.Content

The content displayed within the dialog modal.

Property Type Description
transition
function

A Svelte transition function to use when transitioning the content in and out.

Default:  —— undefined
transitionConfig
TransitionConfig

The configuration to apply to the transition.

Default:  —— undefined
inTransition
function

A Svelte transition function to use when transitioning the content in and out.

Default:  —— undefined
inTransitionConfig
TransitionConfig

The configuration to apply to the transition.

Default:  —— undefined
outTransition
function

A Svelte transition function to use when transitioning the content in and out.

Default:  —— undefined
outTransitionConfig
TransitionConfig

The configuration to apply to the transition.

Default:  —— undefined
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default:  —— undefined
Slot Property Type Description
builder
object

The builder attributes and actions to apply to the element if using the asChild prop with delegation.

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

A Svelte transition function to use when transitioning the content in and out.

Default:  —— undefined
transitionConfig
TransitionConfig

The configuration to apply to the transition.

Default:  —— undefined
inTransition
function

A Svelte transition function to use when transitioning the content in and out.

Default:  —— undefined
inTransitionConfig
TransitionConfig

The configuration to apply to the transition.

Default:  —— undefined
outTransition
function

A Svelte transition function to use when transitioning the content in and out.

Default:  —— undefined
outTransitionConfig
TransitionConfig

The configuration to apply to the transition.

Default:  —— undefined
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default:  —— undefined
Slot Property Type Description
builder
object

The builder attributes and actions to apply to the element if using the asChild prop with delegation.

Data Attribute Value Description
data-state
enum

The state of the dialog.

data-dialog-overlay
——

Present on the overlay.

Dialog.Portal

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

Property Type Description
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default:  —— undefined
Slot Property Type Description
builder
object

The builder attributes and actions to apply to the element if using the asChild prop with delegation.

Data Attribute Value Description
data-portal
——

Present on the portal.

data-dialog-portal
——

Present on the portal.

Dialog.Close

A button used to close the dialog.

Property Type Description
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLButtonElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default:  —— undefined
Slot Property Type Description
builder
object

The builder attributes and actions to apply to the element if using the asChild prop with delegation.

Data Attribute Value Description
data-dialog-close
——

Present on the close button.

Dialog.Title

An accessibile title for the dialog.

Property Type Description
level
enum

The heading level of the title.

Default:  —— undefined
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLHeadingElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default:  —— undefined
Slot Property Type Description
builder
object

The builder attributes and actions to apply to the element if using the asChild prop with delegation.

Data Attribute Value Description
data-dialog-title
——

Present on the title.

Dialog.Description

An accessibile description for the dialog.

Property Type Description
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default:  —— undefined
Slot Property Type Description
builder
object

The builder attributes and actions to apply to the element if using the asChild prop with delegation.

Data Attribute Value Description
data-dialog-description
——

Present on the description.