ContentDialog

Edit This Page

Dialog controls are modal UI overlays that provide contextual app information. They block interactions with the app window until being explicitly dismissed. They often request some kind of action from the user.

import { ContentDialog } from "fluent-svelte";

Usage

Opening and Closing

Dialogs are not rendered into the DOM initially. They need to be opened first, by setting the open property.

<ContentDialog open>
    This dialog is open by default.
</ContentDialog>

If you wish to control a dialog opening from a trigger button, you can two-way bind the open property to a variable.

<script>
    import { ContentDialog, Button } from "fluent-svelte";

    let open = false;
</script>

<Button on:click={() => open = true}>Open</Button>

<ContentDialog bind:open>
    I have been opened by a button click.
</ContentDialog>

Additionally, dialogs can be closed by pressing the escape key. If you wish to disable this behavior, you can set the closable property to false.

Titles

While not strictly required, it is recommended that you give the dialog a title to describe it’s purpose using the title property. This both visually adds a title at the top of the content area, and adds an accessible label through ARIA attributes for usage with assistive technologies.

<ContentDialog title="I have a title." />

A11Y Note

The ARIA 1.2 specification requires a dialog title in order to comply with the modal dialog pattern.

Footers

You can use the footer slot to insert various actions at the bottom of the dialog.

<script>
    import { ContentDialog, Button } from "fluent-svelte";

    let open = true;
</script>

<ContentDialog bind:open title="Dialog with action">
    <Button slot="footer" on:click={() => open = false}>Close Dialog</Button>
</ContentDialog>

Size

Dialogs come in three sizes - min, standard, and max. You can set the dialog’s size using the size property. With this in mind, dialogs will always responsively scale down if their width exceeds the viewport size.

Dialog Backdrops

The default behavior of a dialog is to open with a backdrop (“smoke”) layer which prevents user interaction and darkens the contents of the page behind the dialog.

You can disable backdrop darkening by setting the darken property to false.
You can configure the backdrop to close the dialog when it is clicked using the on:backdropclick and on:backdropmousedown events dispatched from the component.

Focus Behavior

In accordance to WAI-ARIA Authoring Practices, dialogs utilize a focus trap, which restricts keyboard navigation focus to only the dialog’s content. If you wish to disable this behavior, you can set the trapFocus property to false.

Appending

There are some situations where you might want the dialog’s elements to open appended to a specific element, separate from your markup structure. This can be useful if you want to trigger the dialog from inside a container element that has overflow: hidden; styles set, or if you want a single source of where dialogs should be opened from.

To do this, you can set the append property to any valid HTMLElement. This will append the dialog to the specified element when opened, rather than the position specified in your markup.

<ContentDialog title="Appended Dialog" append={document.body}>
    When opened, I will be appended to this page's <body> tag.
</ContentDialog>

Information

If you are familliar with React, this is essentially a portal.

Component API

API docs automatically generated by sveld and vite-plugin-sveld.

Props

Name	Type	Default	Description
`open`	`boolean`	`false`	Determines whether the dialog is open or not.
`title`	`string`	`""`	Title text displayed as the dialog header.
`size`	`string`	`"standard"`	Specifies the visual size of the dialog.
`closable`	`boolean`	`true`	Determines whether the dialog can be conventially closed using the escape key.
`append`	Unknown	`undefined`	Determines the node the dialog should be appended to.
`darken`	`boolean`	`true`	Determines if the dialog should darken the contents behind it.
`trapFocus`	`boolean`	`true`	Determines if keyboard focus should be locked to the dialog's contents.
`element`	`null \| HTMLDivElement`	`null`	Obtains a bound DOM reference to the inner dialog element.
`backdropElement`	`null \| HTMLDivElement`	`null`	Obtains a bound DOM reference to the dialog's backdrop container element.
`bodyElement`	`null \| HTMLDivElement`	`null`	Obtains a bound DOM reference to the dialog's inner body element.
`footerElement`	`null \| HTMLElement`	`null`	Obtains a bound DOM reference to the dialog's footer element.

This component uses $$restProps.

All unused props will be passed through to the underlying div element as regular attributes.

More Info

Slots

Name	Slot Props	Fallback
`Unnamed (Default)`	`{}`	Empty
`footer`	`{}`	Empty
`outer`	`{}`	Empty

Events

All DOM events are forwarded to this component's respective elements by default. Learn More

Dispatched Events

Name	Detail
`backdropclick`	None
`backdropmousedown`	None
`close`	None
`open`	None