Dialog

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 appearance="text" slot="footer">Close</pc-button>
</pc-dialog>

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

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

  openButton.addEventListener("click", () => dialog.show());
  closeButton.addEventListener("click", () => dialog.hide());
</script>

Code

Demos

Custom width

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

<pc-dialog label="Dialog" class="dialog-width" style="--width: 50vw">
  Lorem ipsum dolor sit amet, consectetur adipiscing elit.
  <pc-button appearance="text" slot="footer">Close</pc-button>
</pc-dialog>

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

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

  openButton.addEventListener("click", () => dialog.show());
  closeButton.addEventListener("click", () => dialog.hide());
</script>

Code

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="
          height: 150vh;
          border: 2px dashed var(--pc-color-neutral-200);
          border-radius: var(--pc-border-radius-l);
          padding: 0 var(--pc-spacing-l);
      "
  >
      <p>Scroll down and give it a try! 👇</p>
  </div>

  <pc-button appearance="text" slot="footer">Close</pc-button>
</pc-dialog>

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

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

  openButton.addEventListener("click", () => dialog.show());
  closeButton.addEventListener("click", () => dialog.hide());
</script>

Code

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-icon-button
      class="new-window"
      slot="header-actions"
      library="default"
      icon-style="solid"
      name="arrow-up-right-from-square"
  ></pc-icon-button>

  <pc-button appearance="text" slot="footer">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

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-request-close 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 determine what triggered the request to close. This example prevents the dialog from closing when the overlay is clicked, but allows the close button or Esc to dismiss it.

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

  <pc-button appearance="text" slot="footer">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-request-close", (event) => {
      if (event.detail.source === "overlay") {
          event.preventDefault();
      }
  });

  openButton.addEventListener("click", () => dialog.show());
  closeButton.addEventListener("click", () => dialog.hide());
</script>

Code

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-placeholder="I will have focus when the dialog is opened"
      autofocus
  ></pc-input>

  <pc-button appearance="text" slot="footer">Close</pc-button>
</pc-dialog>

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

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

  openButton.addEventListener("click", () => dialog.show());
  closeButton.addEventListener("click", () => dialog.hide());
</script>

Code

You can further customise initial focus behaviour by cancelling the pc-initial-focus event and setting focus yourself inside the event handler.

Properties

Name	Description	Default
`modal`	Exposes the internal modal utility that controls focus trapping. To temporarily disable focus trapping and allow third‐party modals spawned from an active Placer modal, call `modal.activateExternal()` when the third‐party modal opens. Upon closing, call `modal.deactivateExternal()` to restore Placer Toolkit’s focus trapping.	`new Modal(this)`
`open`	Indicates whether or not the dialog is open. You can toggle this attribute to show and hide the dialog, or you can use the `show()` and `hide()` methods and this attribute will reflect the dialog’s open state. `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. `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. `boolean`	`false`
`updateComplete`	A read‐only promise that resolves when the component has finished updating.	-

Learn more about attributes and properties.

Slots

Name	Description
(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-icon-button>`.
`footer`	The dialog’s footer, usually one or more buttons representing various options.

Learn more about using slots.

Methods

Name	Description	Arguments
`show()`	Shows the dialog.	-
`hide()`	Hides the dialog.	-

Learn more about methods.

Events

Name	Description	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.	-
`pc-after-hide`	Emitted after the dialog closes and all animations are complete.	-
`pc-initial-focus`	Emitted when the dialog opens and is ready to receive focus. Calling `event.preventDefault()` will prevent focusing and allow you to set it on a different element, such as an input.	-
`pc-request-close`	Emitted when the user attempts to close the dialog by clicking the close button, clicking the overlay or pressing `Esc`. Calling `event.preventDefault()` will keep the dialog open. Avoid using this unless closing the dialog will result in destructive behaviour such as data loss.	`{ source: "close-button" \| "keyboard" \| "overlay" }`

Learn more about events.

Custom properties

Name	Description	Default
`--width`	The preferred width of the dialog. Note that the dialog will shrink to accommodate smaller screens.	-
`--header-spacing`	The amount of spacing to use for the header.	-
`--body-spacing`	The amount of padding to use for the body.	-
`--footer-spacing`	The amount of padding to use for the footer.	-

Learn more about customising custom properties.

Parts

Name	Description
`base`	The component’s base wrapper.
`overlay`	The overlay that covers the screen behind the dialog.
`panel`	The dialog’s panel (where the dialog and its content are rendered).
`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-icon-button>`.
`title`	The dialog’s title.
`close-button`	The close button. Is a `<pc-icon-button>` under the hood.
`close-button__base`	The close button’s `base` part.
`body`	The dialog’s body.
`footer`	The dialog’s footer.

Learn more about customising CSS parts.

Animations

Name	Description
`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.
`dialog.overlay.show`	The animation to use when showing the dialog’s overlay.
`dialog.overlay.hide`	The animation to use when hiding the dialog’s overlay.

Learn more about customising animations.

Importing

If you’re using the autoloader or the standard loader, you can ignore this section. If you’re cherry picking, you can use any of the following snippets to import this component.

Script

Import

Bundler

To import this component from the CDN with a script tag, copy this snippet and paste it in your HTML.

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

To import this component from the CDN using a JavaScript import, copy this snippet and paste it in your JavaScript:

import "https://cdn.jsdelivr.net/npm/placer-toolkit@0.5.1/dist/components/dialog/dialog.js";

To import this component with a bundler using a JavaScript import, copy this snippet and paste it in your JavaScript:

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

Dependencies

This component automatically imports these components: