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." />

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>

Component API

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

Props

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

Slots

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

NameDetail
backdropclick None
backdropmousedown None
close None
open None