Dialog Modal

DialogModal

A native Astro equivalent of @fpkit/acss DialogModal. Uses the HTML <dialog> element with showModal() for accessible modal behavior — backdrop, Escape key, and focus trap are all handled natively by the browser.

Import

---
import DialogModal from '#components/astro/DialogModal.astro'
---

Or via the component barrel:

---
import { DialogModal } from '#components'
---

Basic Usage

---
import DialogModal from '#components/astro/DialogModal.astro'
---

<DialogModal id="my-dialog" dialogTitle="My Dialog">
  <p>Dialog body content goes here.</p>
</DialogModal>

This renders a trigger button and the modal dialog. The id links the button to its dialog — it must be unique per page.

Props

Prop	Type	Default	Description
id	string	required	Unique ID linking trigger button to dialog
dialogTitle	string	required	Title shown in the dialog header
size	'sm' | 'md' | 'lg' | 'full'	undefined	Size variant — sets data-size on <dialog>
position	'center' | 'top' | 'bottom' | 'left' | 'right' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'	undefined	Position variant — sets data-position on <dialog>
btnLabel	string	'Open Dialog'	Trigger button label
btnClass	string	undefined	Extra CSS classes on the trigger button
headingLevel	'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'	'h2'	Heading element for the dialog title
confirmLabel	string	'Confirm'	Footer confirm button label
cancelLabel	string	'Cancel'	Footer cancel button label
hideFooter	boolean	false	Hides the footer action buttons

Size Variants

<DialogModal id="dialog-sm" dialogTitle="Small Dialog" btnLabel="Open Small" size="sm">
  <p>A compact dialog.</p>
</DialogModal>

<DialogModal id="dialog-lg" dialogTitle="Large Dialog" btnLabel="Open Large" size="lg">
  <p>A larger dialog.</p>
</DialogModal>

<DialogModal id="dialog-full" dialogTitle="Full Screen" btnLabel="Open Full" size="full">
  <p>Fills the viewport.</p>
</DialogModal>

Position Variants

<DialogModal id="dialog-top" dialogTitle="Top Sheet" btnLabel="Open Top" position="top">
  <p>Slides in from the top.</p>
</DialogModal>

<DialogModal id="dialog-right" dialogTitle="Side Panel" btnLabel="Open Panel" position="right">
  <p>Docked to the right edge.</p>
</DialogModal>

Hide Footer

Use hideFooter when the dialog is informational and no confirm/cancel action is needed.

<DialogModal
  id="dialog-info"
  dialogTitle="Information"
  btnLabel="Learn More"
  hideFooter={true}
>
  <p>This dialog has no action buttons.</p>
</DialogModal>

Confirm Event

The confirm button dispatches a dialog:confirm CustomEvent on the dialog element before closing. Listen to it by targeting the dialog’s id.

---
import DialogModal from '#components/astro/DialogModal.astro'
---

<DialogModal
  id="dialog-delete"
  dialogTitle="Delete Item"
  btnLabel="Delete"
  confirmLabel="Yes, delete"
  cancelLabel="Keep it"
>
  <p>Are you sure you want to delete this item?</p>
</DialogModal>

<p id="delete-result" aria-live="polite"></p>

<script>
  document.getElementById('dialog-delete')?.addEventListener('dialog:confirm', () => {
    const result = document.getElementById('delete-result')
    if (result) result.textContent = 'Item deleted.'
  })
</script>

Custom Heading Level

Match the dialog title to the document heading hierarchy to preserve accessibility.

<DialogModal
  id="dialog-nested"
  dialogTitle="Section Detail"
  headingLevel="h3"
>
  <p>Dialog used inside a section with an h2 heading.</p>
</DialogModal>

Multiple Instances

Multiple dialogs on the same page work independently — each is identified by its unique id.

<DialogModal id="dialog-a" dialogTitle="Dialog A" btnLabel="Open A">
  <p>Content for dialog A.</p>
</DialogModal>

<DialogModal id="dialog-b" dialogTitle="Dialog B" btnLabel="Open B">
  <p>Content for dialog B.</p>
</DialogModal>

Accessibility

• Uses native <dialog> with showModal() — the browser provides backdrop, Escape key, and focus trap automatically.
• aria-labelledby links the dialog to its title heading.
• aria-describedby links the dialog to its content section.
• The close button has aria-label="Close dialog" for screen readers.
• Focus is restored to the trigger button when the dialog closes.
• All buttons are explicitly type="button" to prevent accidental form submission.

CSS

No styles are included in this component. fpkit dialog CSS is globally included via Base.astro. The component uses standard fpkit class names and data-* attributes:

• .dialog-header, .dialog-title, .dialog-content, .dialog-footer
• data-size — size variant attribute read by fpkit CSS
• data-position — position variant attribute read by fpkit CSS
• data-btn="sm" — fpkit button attribute used on trigger and footer buttons