XDS — Design System

XDSDialogHeader@xds/core · Dialog

Preview coming soon

Usage

Dialog displays a modal overlay that blocks interaction with the page until the user responds. Use it for delete confirmations, edit forms, terms acceptance, or any decision that should not be skipped. For cases where you want to show a dialog without managing open state, use the `useXDSImperativeDialog` hook — call `dialog.show(content)` and render `dialog.element` in your tree.

Best practices

Guidance	Practices
Do	Choose the right purpose: info for dismissable content, form to prevent accidental backdrop dismissal, required when the user must respond.
Do	Include a clear title in the header so users immediately understand what the dialog is asking.
Do	Use purpose="form" for dialogs with inputs so the user can't accidentally lose data by clicking the backdrop.
Do	Keep dialogs focused on a single task — if the content grows beyond what fits, consider a full page instead.
Don't	Use a dialog for simple messages that could be shown inline or as a toast notification.
Don't	Nest dialogs inside other dialogs — restructure the flow into steps within a single dialog instead.
Don't	Use the fullscreen variant for simple confirmations — it is meant for complex content like editors or long forms.

Anatomy

Element		Description
Header	required	Title, optional subtitle, and close button. The title receives focus on open for accessibility.
Body	required	The main content area — text, forms, lists, or any layout.
Footer		Action buttons like Save/Cancel or Accept/Decline, aligned to the end.
Backdrop	required	Semi-transparent overlay behind the dialog that blocks page interaction.

Import

ts
import {XDSDialogHeader} from '@xds/core/Dialog'

Props

Prop	Type	Description
title	string	Dialog title (receives focus on open).
subtitle	string	Subtitle below the title.
onOpenChange	(isOpen: boolean) => unknown	Close button callback (no button if omitted).
startContent	ReactNode	Content before the title (e.g., a back button).
endContent	ReactNode	Content after the title, before close button.
hasDivider	boolean (default: true)	Adds border at the bottom edge.

Showcase source

tsx
'use client';
import {XDSDialog, XDSDialogHeader} from '@xds/core/Dialog';
import {XDSLayout, XDSLayoutContent, XDSCard} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
export default function DialogHeaderShowcase() {
  return (
    <XDSDialog isOpen isInline onOpenChange={() => {}}>
      <XDSLayout
        header={
          <XDSDialogHeader
            title="Edit Profile"
            subtitle="Update your personal information"
            onOpenChange={() => {}}
          />
        }
        content={
          <XDSLayoutContent>
            <XDSCard variant="muted">
              <XDSText type="body" color="secondary">
                Dialog body content goes here.
              </XDSText>
            </XDSCard>
          </XDSLayoutContent>
        }
      />
    </XDSDialog>
  );
}