Modal

The <dsgn-modal> component wraps the native <dialog> element and showModal(), so the top layer, background inertness, and focus containment come from the platform rather than a hand-rolled focus trap. The same component covers a centered modal and a sheet/drawer entering from any viewport edge.

All production copy comes from the consumer through slots and content-bearing props under the system-wide content ownership policy. This includes the built-in close control’s accessible name, authored through close-label.

Usage

<dsgn-modal id="invite">
  <span slot="heading">Invite teammates</span>
  <span slot="description">They get access as soon as they accept.</span>
  <p>Anyone you invite can see every project in this workspace.</p>
  <div slot="footer">
    <dsgn-button appearance="outline">Cancel</dsgn-button>
    <dsgn-button>Send invites</dsgn-button>
  </div>
</dsgn-modal>

<script type="module">
  document.querySelector('#invite').show();
</script>

Import the component module in your application entrypoint:

import '@ds-gn/ui/modal';

Playground

Props

aria-label, close-label, no-close-control, no-backdrop-dismiss, and no-escape-dismiss are the attribute names; the matching JavaScript properties are ariaLabel, closeLabel, noCloseControl, noBackdropDismiss, and noEscapeDismiss.

Methods

Events

reason is one of 'api', 'escape', 'backdrop', or 'close-control'.

Slots

Empty regions collapse, so a modal with no footer has no stray padding. The header is the exception: it stays visible for the built-in close control unless no-close-control is set and no heading is supplied.

The built-in close control

Every modal renders its own close control in the header, so there is always a visible way out. It is the close slot’s fallback content, which means slotting your own control replaces it — no flag to unset:

<dsgn-modal>
  <span slot="heading">Invite teammates</span>
  <dsgn-button
    slot="close"
    appearance="ghost"
    icon-name="x"
    icon-position="only"
    aria-label="Close"
  ></dsgn-button>
</dsgn-modal>

Set no-close-control when the flow supplies its own dismissal, such as a footer “Cancel”. Never combine it with no-escape-dismiss — that leaves keyboard users with no way out.

Its accessible name is authored content: pass close-label from your application’s content source the way you would any other copy. Do not treat the component’s standalone 'Close' value as a production content default.

CSS parts

dsgn-modal::part(dialog) {
  border-radius: 1.25rem;
}

Examples

Sheet from the right

<dsgn-modal placement="right" size="lg">
  <span slot="heading">Activity</span>
  <p>Everything that happened today.</p>
</dsgn-modal>

Destructive confirmation

<dsgn-modal id="confirm" size="sm" no-backdrop-dismiss>
  <span slot="heading">Delete project</span>
  <span slot="description">This cannot be undone.</span>
  <p>Everyone loses access immediately.</p>
  <div slot="footer">
    <dsgn-button appearance="outline" onclick="confirm.requestClose()"
      >Cancel</dsgn-button
    >
    <dsgn-button onclick="confirm.close('deleted')">Delete project</dsgn-button>
  </div>
</dsgn-modal>

Guarding a close

modal.addEventListener('dsgn-modal-request-close', (event) => {
  if (formIsDirty) event.preventDefault();
});

Escape, the backdrop, and the close slot all route through this event, so one listener guards every dismissal path. close() deliberately bypasses it.

React

import { Modal } from '@ds-gn/ui/react';

<Modal open={open} placement="bottom" onDsgnModalClose={() => setOpen(false)}>
  <span slot="heading">Share</span>
  <p>Anyone with the link can view this.</p>
</Modal>;

Because the component closes itself, a controlled consumer has to mirror the change back in onDsgnModalClose — otherwise the two states drift on the next open.

Accessibility

• Built on showModal(), so the dialog is in the top layer, background content is inert, and focus is contained by the platform.
• On open, focus moves to the first [autofocus] element in the modal’s content, falling back to the dialog itself. The native autofocus algorithm is not relied on because it is inconsistent for slotted content.
• On close, focus returns to the element that was focused when the modal opened (following shadow roots), unless it has since been removed from the document.
• Every modal has a visible close control by default, so a pointer user is never left with only Escape or the backdrop as a way out.
• The accessible name comes from the heading slot via aria-labelledby, or from aria-label when there is no heading. aria-describedby is only set once the description slot has content — a dangling reference would leave the dialog with no description at all.
• The page behind the modal is pinned while it is open, so long content scrolls inside the body region rather than moving the page underneath.
• Backdrop dismissal requires the press and the release to land on the backdrop, so a text selection that ends outside the panel does not dismiss.
• With prefers-reduced-motion: reduce, every placement cross-fades in place instead of sliding. motion="none" opts into the same treatment for everyone.

Keyboard

Slotted content keeps its authored order, so the keyboard path runs heading → body → footer actions.