Dialog

<pc-dialog>

0.5.1

experimental

Dieser Inhalt ist noch nicht in deiner Sprache verfügbar.

Dialogs, sometimes called “modals”, appear above the page and draw the user’s immediate attention.

<pc-dialog label="Dialog" class="dialog-overview">
    Lorem ipsum dolor sit amet, consectetur adipiscing elit.

    <pc-button variant="plain" slot="footer" data-dialog="close">
        Close
    </pc-button>
</pc-dialog>

<pc-button>Open dialog</pc-button>

<script>
    const dialog = document.querySelector(".dialog-overview");
    const openButton = dialog.nextElementSibling;

    openButton.addEventListener("click", () => (dialog.open = true));
</script>

Code

Edit

Demos#

Opening and closing dialogs declaratively#

You can open and close dialogs with JavaScript by toggling the open attribute, but you can also do it declaratively. Add the data-dialog="open id" to any button on the page, where id is the id of the dialog you want to open.

<pc-dialog label="Dialog" id="dialog-open-declarative">
    Lorem ipsum dolor sit amet, consectetur adipiscing elit.

    <pc-button variant="plain" slot="footer" data-dialog="close">
        Close
    </pc-button>
</pc-dialog>

<pc-button data-dialog="open dialog-open-declarative">
    Open dialog
</pc-button>

Code

Edit

Similarly, you can add data-dialog="close" to a button inside of the dialog to tell it to close it.

<pc-dialog label="Dialog" id="dialog-dismiss-declarative">
    Lorem ipsum dolor sit amet, consectetur adipiscing elit.

    <pc-button variant="plain" slot="footer" data-dialog="close">
        Close
    </pc-button>
</pc-dialog>

<pc-button data-dialog="open dialog-dismiss-declarative">
    Open dialog
</pc-button>

Code

Edit

Custom width#

Use the --width custom property to set the dialog’s width.

<pc-dialog label="Dialog" class="dialog-width" style="--width: 50vw">
    This dialog is always 50 % of the viewport.

    <pc-button variant="plain" slot="footer" data-dialog="close">
        Close
    </pc-button>
</pc-dialog>

<pc-button>Open dialog</pc-button>

<script>
    const dialog = document.querySelector(".dialog-width");
    const openButton = dialog.nextElementSibling;

    openButton.addEventListener("click", () => (dialog.open = true));
</script>

Code

Edit

Scrolling#

By design, a dialog’s height will never exceed that of the viewport. As such, dialogs will not scroll with the page ensuring the header and footer are always accessible to the user.

<pc-dialog label="Dialog" class="dialog-scrolling">
    <div
        style="
            padding: var(--pc-spacing-l);
            block-size: 150dvh;
            border: var(--pc-border-width-m) dashed
                var(--pc-color-neutral-border-normal);
            border-radius: var(--pc-border-radius-l);
        "
    >
        <p>Scroll down and give it a try! ⬇️</p>
    </div>

    <pc-button variant="plain" slot="footer" data-dialog="close">
        Close
    </pc-button>
</pc-dialog>

<pc-button>Open dialog</pc-button>

<script>
    const dialog = document.querySelector(".dialog-scrolling");
    const openButton = dialog.nextElementSibling;

    openButton.addEventListener("click", () => (dialog.open = true));
</script>

Code

Edit

Header actions#

The header shows a functional close button by default. You can use the header-actions slot to add additional icon buttons if needed.

<pc-dialog label="Dialog" class="dialog-header-actions">
    <pc-button
        class="new-window"
        size="small"
        variant="plain"
        slot="header-actions"
    >
        <pc-icon
            library="default"
            icon-style="solid"
            name="arrow-up-right-from-square"
            label="Open this page in a new window"
        ></pc-icon>
    </pc-button>

    Lorem ipsum dolor sit amet, consectetur adipiscing elit.

    <pc-button variant="plain" slot="footer" data-dialog="close">
        Close
    </pc-button>
</pc-dialog>

<pc-button>Open dialog</pc-button>

<script>
    const dialog = document.querySelector(".dialog-header-actions");
    const openButton = dialog.nextElementSibling;
    const closeButton = dialog.querySelector('pc-button[slot="footer"]');
    const newWindowButton = dialog.querySelector(".new-window");

    openButton.addEventListener("click", () => dialog.show());
    closeButton.addEventListener("click", () => dialog.hide());
    newWindowButton.addEventListener("click", () => window.open(location.href));
</script>

Code

Edit

Prevent light dismissal#

If you want to prevent the dialog from closing if the user clicks on the overlay, add the no-light-dismiss attribute.

<pc-dialog label="Dialog" class="dialog-no-light-dismiss" no-light-dismiss>
    This dialog will not close when you click on the overlay.

    <pc-button variant="plain" slot="footer" data-dialog="close">
        Close
    </pc-button>
</pc-dialog>

<pc-button>Open dialog</pc-button>

<script>
    const dialog = document.querySelector(".dialog-no-light-dismiss");
    const openButton = dialog.nextElementSibling;

    openButton.addEventListener("click", () => (dialog.open = true));
</script>

Code

Edit

Prevent dialog from closing#

By default, dialogs will close when the user clicks the close button, clicks the overlay or presses the Esc key. In most cases, the default behaviour is the best behaviour in terms of UX. However, there are situations where this may be undesirable, such as when data loss will occur.

To keep the dialog open in such cases, you can cancel the pc-hide event. When cancelled, the dialog will remain open and pulse briefly to draw the user’s attention to it.

You can use event.detail.source to check what triggered the close request. In this example, the dialog will only close when a custom close button inside the footer is clicked. Clicking the overlay, pressing Esc or using the built‐in header close button will all be prevented.

<pc-dialog label="Dialog" class="dialog-deny-close">
    This dialog will only close if you click on the button below.

    <pc-button variant="plain" slot="footer" data-dialog="close">
        Close
    </pc-button>
</pc-dialog>

<pc-button>Open dialog</pc-button>

<script>
    const dialog = document.querySelector(".dialog-deny-close");
    const openButton = dialog.nextElementSibling;
    const closeButton = dialog.querySelector('pc-button[slot="footer"]');

    dialog.addEventListener("pc-hide", (event) => {
        if (event.detail.source !== closeButton) {
            event.preventDefault();
        }
    });

    openButton.addEventListener("click", () => (dialog.open = true));
</script>

Code

Edit

Customise initial focus#

By default, the dialog’s panel will gain focus when opened. This allows a subsequent tab press to focus on the first tabbable element in the dialog. If you want a different element to have focus, add the autofocus attribute to it as shown below.

<pc-dialog label="Dialog" class="dialog-focus">
    <pc-input
        placeholder="I will have focus when the dialog is opened"
        aria-label="I will have focus when the dialog is opened"
        autofocus
    ></pc-input>

    <pc-button variant="plain" slot="footer" data-dialog="close">
        Close
    </pc-button>
</pc-dialog>

<pc-button>Open dialog</pc-button>

<script>
    const dialog = document.querySelector(".dialog-focus");
    const openButton = dialog.nextElementSibling;

    openButton.addEventListener("click", () => (dialog.open = true));
</script>

Code

Edit

Eigenschaften#

Name	Beschreibung	Standard
`open`	Indicates whether or not the dialog is open. Toggle this attribute to show and hide the dialog. Typ: `boolean`	`false`
`label`	The dialog’s label displayed in the header. You should always include a relevant label even when using the `no-header` attribute, as it is required for proper accessibility. If you need to display HTML, use the `label` slot instead. Typ: `string`	`""`
`noHeader` `no-header`	Removes the header. This will also remove the default close button, so please ensure you provide an easy, accessible way for users to dismiss the dialog. Typ: `boolean`	`false`
`noLightDismiss` `no-light-dismiss`	Prevents clicks on the backdrop causing the dialog to close. Typ: `boolean`	`false`
`updateComplete`	Ein schreibgeschütztes Promise, das erfüllt ist, sobald die Komponente fertig aktualisiert wurde.	‐

Erfahre mehr über Attribute und Eigenschaften.

Slots#

Name	Beschreibung
(default)	The dialog’s main content.
`label`	The dialog’s label. Alternatively, you can use the `label` attribute.
`header-actions`	Optional actions to add to the header. Works best with `<pc-button>`.
`footer`	The dialog’s footer, usually one or more buttons representing various options.

Erfahre mehr über die Benutzung von Slots.

Events#

Name	Beschreibung	Event‐Detail
`pc-show`	Emitted when the dialog opens.	‐
`pc-after-show`	Emitted after the dialog opens and all animations are complete.	‐
`pc-hide`	Emitted when the dialog closes.	`{ source: Element }`
`pc-after-hide`	Emitted after the dialog closes and all animations are complete.	‐

Erfahre mehr über Events.

Benutzerdefinierte Eigenschaften#

Name	Beschreibung	Standard
`--width`	The preferred width of the dialog. Note that the dialog will shrink to accommodate smaller screens.	`31rem`
`--header-spacing`	The amount of spacing to use for the header.	`var(--pc-spacing-xl)`
`--body-spacing`	The amount of padding to use for the body.	`var(--pc-spacing-s) var(--pc-spacing-xl)`
`--footer-spacing`	The amount of padding to use for the footer.	`var(--pc-spacing-s) var(--pc-spacing-xl) var(--pc-spacing-xl)`

Erfahre mehr über das Anpassen von benutzerdefinierten Eigenschaften.

Parts#

Name	Beschreibung
`dialog`	The dialog’s `<dialog>` element.
`header`	The dialog’s header. This element wraps the title and header actions.
`header-actions`	Optional actions to add to the header. Works best with `<pc-button>`.
`title`	The dialog’s title.
`close-button`	The close button. Is a `<pc-button>` under the hood.
`close-button-base`	The close button’s `base` part.
`body`	The dialog’s body.
`footer`	The dialog’s footer.

Erfahre mehr über das Anpassen von CSS‐Parts.

Animationen#

Name	Beschreibung
`dialog.show`	The animation to use when showing the dialog.
`dialog.hide`	The animation to use when hiding the dialog.
`dialog.denyClose`	The animation to use when a request to close the dialog is denied.

Erfahre mehr über das Anpassen von Animationen.

Importieren#

Wenn du den Autoloader oder den Standard‐Loader nutzt, kannst du diesen Abschnitt überspringen. Falls du „Cherry Picking“ betreibst, kannst du die folgenden Snippets verwenden, um diese Komponente zu importieren.

CDN (Skript‐Tag)

CDN (Import)

npm (Import)

Um diese Komponente manuell vom CDN zu importieren, kopiere dieses Code‐Snippet und füge es in dein HTML ein.

  <script type="module" src="https://cdn.jsdelivr.net/npm/placer-toolkit@1.0.0-alpha.3/cdn/components/dialog/dialog.js"></script> 

Um diese Komponente manuell vom CDN zu importieren, kopiere dieses Code‐Snippet und füge es in deine JavaScript‐Datei ein.

  import "https://cdn.jsdelivr.net/npm/placer-toolkit@1.0.0-alpha.3/cdn/components/dialog/dialog.js"; 

Um diese Komponente manuell via npm zu importieren, kopiere dieses Code‐Snippet und füge es in deine JavaScript‐Datei ein.

import "placer-toolkit/dist/components/dialog/dialog.js";

Abhängigkeiten#

Diese Komponente importiert automatisch folgende Komponenten:

Button