Dialog

Open dialog

Edit profile

Make changes to your profile here. Click save when you are done.

Name

Username

Cancel Save changes

Close

Show code

It is a real <dialog>

Focus trapping, Esc, the top layer and making the rest of the page inert all come from showModal(). partialkit only adds the wiring: opening, closing, backdrop dismissal, labelling and the state attribute.

A dialog is a place to do something, and it can be dismissed. When the user has to answer a question before anything else happens — anything destructive, in particular — use an alert dialog instead.

Usage

<button class="btn" data-pk-dialog-open="my-dialog">Open</button>

<dialog class="dialog" id="my-dialog">
  <div class="dialog-header">
    <h2 class="dialog-title">Title</h2>
  </div>
</dialog>

Composition

Open

Title

The description sits under the title.

Anything between the header and the footer is the body.

Cancel Save

Show code

Class	Part
.dialog	The <dialog> element itself
.dialog-close	Position for the corner dismiss control
.dialog-header	Title area
.dialog-title	Heading — becomes the accessible name
.dialog-description	Supporting line — becomes aria-describedby
.dialog-footer	A bar across the bottom, with its own surface

Attribute	On	Meaning
data-pk-dialog-open="<id>"	any control	Opens that dialog as a modal
data-pk-dialog-close	a control inside	Closes the enclosing dialog
data-pk-dialog-close="<value>"	a control inside	Closes it and sets returnValue
data-pk-dialog-static	the dialog	Clicking the backdrop does not close it
data-state="open" | "closed"	the dialog	Set by the runtime

Custom Close Button

.dialog-close only positions; the control itself is yours. shadcn/ui composes a ghost icon button, which is what the examples here use:

<button class="btn btn-ghost btn-icon-sm dialog-close" data-pk-dialog-close>
  <svg …></svg>
  <span class="sr-only">Close</span>
</button>

.sr-only text and aria-label both name the control. shadcn/ui uses the text node, which has one advantage: it survives translation tooling that skips attributes.

Anything else works the same way:

Open

Esc

Custom close control

.dialog-close only positions — the control is yours.

Show code

The aria-label is not optional on an icon-only control — the icon carries no text.

No Close Button

Leave it out. Esc and the backdrop still dismiss the dialog, so the user is never trapped.

Open

No close button

Escape and the backdrop still dismiss it.

Done

Show code

To stop the backdrop dismissing it — when clicking away would lose work — add data-pk-dialog-static:

Open static dialog

Unsaved changes

Clicking outside will not close this one.

Got it

Show code

Sticky Footer

The footer is already full-bleed: it cancels the dialog’s padding, carries a top border and its own surface. In a scrolling dialog it scrolls with the content rather than pinning, which keeps the whole panel one scroll context instead of two.

Scrollable Content

The panel caps at the viewport height minus a margin and scrolls past that. Nothing to configure.

Open long dialog

Terms of service

The panel scrolls once it runs out of room.

Section one. Everything here is ordinary body copy.

Section two. The dialog never grows past the viewport.

Section three. It caps at the screen height minus a margin.

Section four. Past that, this area scrolls.

Section five. Focus stays trapped while you scroll.

Section six. The header scrolls away with the rest.

Section seven.

Section eight.

Section nine.

Section ten.

Decline Accept

Show code

With a Form

Rename project

Rename project

Name

Cancel Save

Show code

Events

Event	Cancelable	Detail
pk:dialog:before-open	yes	—
pk:dialog:open	no	—
pk:dialog:close	no	{ returnValue }

document.getElementById("demo-dialog").addEventListener("pk:dialog:close", (event) => {
  if (event.detail.returnValue === "save") save();
});

Programmatic control

import { openDialog, closeDialog } from "partialkit";

openDialog("demo-dialog", triggerElement); // triggerElement gets focus back on close
closeDialog("demo-dialog", "save");

Pass the opener when you open a dialog from code. WebKit does not focus a button when it is clicked, so document.activeElement alone is not a reliable record of where focus should return.

RTL

Set dir="rtl" on the page or on any subtree — padding, corners and positions follow the reading direction on their own. See the button page for a live example.

Accessibility

Most of it is the platform’s, but three things are yours:

• A title. .dialog-title becomes the accessible name. A dialog without one is announced as just “dialog”.
• A heading level that fits the page, not one picked for its size.
• A name on the close control, since the icon has none.

Everything else — the focus trap, focus returning to whatever opened it, Esc, and the rest of the page going inert — comes from showModal(), with partialkit filling the gaps where engines differ.