# Dialog

<Preview>
<button type="button" onclick="document.getElementById('demo-dialog-edit-profile').showModal()" class="btn" data-variant="outline">Open Dialog</button>
<dialog id="demo-dialog-edit-profile" class="dialog" aria-labelledby="demo-dialog-edit-profile-title" aria-describedby="demo-dialog-edit-profile-description" onpointerdown="this.dataset.backdropPress = event.target === this" onclick="if (event.target === this && this.dataset.backdropPress === 'true') this.close()">
  <div class="sm:max-w-sm">
    <header>
      <h2 id="demo-dialog-edit-profile-title">Edit profile</h2>
      <p id="demo-dialog-edit-profile-description">Make changes to your profile here. Click save when you're done.</p>
    </header>
    <section>
      <form class="grid gap-4">
        <div class="grid gap-3">
          <label class="label" for="demo-dialog-edit-profile-name">Name</label>
          <input class="input" type="text" value="Pedro Duarte" id="demo-dialog-edit-profile-name" autofocus />
        </div>
        <div class="grid gap-3">
          <label class="label" for="demo-dialog-edit-profile-username">Username</label>
          <input class="input" type="text" value="@peduarte" id="demo-dialog-edit-profile-username" />
        </div>
      </form>
    </section>
    <footer>
      <button class="btn" data-variant="outline" onclick="this.closest('dialog').close()">Cancel</button>
      <button class="btn" onclick="this.closest('dialog').close()">Save changes</button>
    </footer>
    <button type="button" class="btn" data-variant="ghost" data-size="icon-sm" aria-label="Close dialog" onclick="this.closest('dialog').close()"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-x-icon lucide-x"><path d="M18 6 6 18" /><path d="m6 6 12 12" /></svg></button>
  </div>
</dialog>
</Preview>

## Usage

<Callout title="Template macros available" icon="code" action={{ label: "More", href: "/templates#dialog" }}>
  This component ships a `dialog()` macro for Jinja and Nunjucks.
</Callout>

<Steps>
  <Step title="Include CSS">

Import Tailwind and one full Basecoat style bundle.

```css
@import "tailwindcss";
@import "basecoat-css/vega.css";
```

Or import only the base CSS, Dialog component CSS, and one style pack.

```css
@import "tailwindcss";
@import "basecoat-css/base.css";
@import "basecoat-css/components/dialog.css";
@import "basecoat-css/styles/vega.css";
```

Using CDN or bundler imports? See the [Installation page](/installation).

  </Step>
  <Step title="Add your dialog HTML">

Basecoat uses the native `<dialog>` element and `showModal()`. This differs from shadcn/ui's portalled Base UI implementation, but preserves native modality, focus handling, and inert page content without component JavaScript.

```html
<button type="button" onclick="document.getElementById('demo-dialog-edit-profile').showModal()" class="btn" data-variant="outline">Open Dialog</button>
<dialog id="demo-dialog-edit-profile" class="dialog" aria-labelledby="demo-dialog-edit-profile-title" aria-describedby="demo-dialog-edit-profile-description" onpointerdown="this.dataset.backdropPress = event.target === this" onclick="if (event.target === this && this.dataset.backdropPress === 'true') this.close()">
  <div class="sm:max-w-sm">
    <header>
      <h2 id="demo-dialog-edit-profile-title">Edit profile</h2>
      <p id="demo-dialog-edit-profile-description">Make changes to your profile here. Click save when you're done.</p>
    </header>
    <section>
      <form class="grid gap-4">
        <div class="grid gap-3">
          <label class="label" for="demo-dialog-edit-profile-name">Name</label>
          <input class="input" type="text" value="Pedro Duarte" id="demo-dialog-edit-profile-name" autofocus />
        </div>
        <div class="grid gap-3">
          <label class="label" for="demo-dialog-edit-profile-username">Username</label>
          <input class="input" type="text" value="@peduarte" id="demo-dialog-edit-profile-username" />
        </div>
      </form>
    </section>
    <footer>
      <button class="btn" data-variant="outline" onclick="this.closest('dialog').close()">Cancel</button>
      <button class="btn" onclick="this.closest('dialog').close()">Save changes</button>
    </footer>
    <button type="button" class="btn" data-variant="ghost" data-size="icon-sm" aria-label="Close dialog" onclick="this.closest('dialog').close()"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-x-icon lucide-x"><path d="M18 6 6 18" /><path d="m6 6 12 12" /></svg></button>
  </div>
</dialog>
```

  </Step>
</Steps>

### HTML structure

<dl>
  <dt><code>&lt;button type="button" onclick="dialog.showModal()"&gt;</code> <span class="badge" data-variant="secondary">Optional</span></dt>
  <dd>Trigger button. Basecoat intentionally uses the native <code>HTMLDialogElement.showModal()</code> method.</dd>
  <dt><code>&lt;dialog class="dialog" id="&#123; DIALOG_ID &#125;"&gt;</code></dt>
  <dd>
    Native modal dialog. Add <code>aria-labelledby="&#123; TITLE_ID &#125;"</code> and <code>aria-describedby="&#123; DESCRIPTION_ID &#125;"</code> when title and description are present. Add width utilities to the inner <code>&lt;div&gt;</code> when a dialog needs a custom size. The macro also adds backdrop-click close handling.
    <dl>
      <dt><code>&lt;div&gt;</code></dt>
      <dd>
        Dialog content surface.
        <dl>
          <dt><code>&lt;header&gt;</code> <span class="badge" data-variant="secondary">Optional</span></dt>
          <dd>
            Dialog header.
            <dl>
              <dt><code>&lt;h2 id="&#123; TITLE_ID &#125;"&gt;</code></dt>
              <dd>Dialog title. Reference it from <code>aria-labelledby</code>.</dd>
              <dt><code>&lt;p id="&#123; DESCRIPTION_ID &#125;"&gt;</code> <span class="badge" data-variant="secondary">Optional</span></dt>
              <dd>Dialog description. Reference it from <code>aria-describedby</code>.</dd>
            </dl>
          </dd>
          <dt><code>&lt;section&gt;</code> <span class="badge" data-variant="secondary">Optional</span></dt>
          <dd>Dialog body/content area. Add overflow utilities when the body should scroll.</dd>
          <dt><code>&lt;footer&gt;</code> <span class="badge" data-variant="secondary">Optional</span></dt>
          <dd>Action area. It stacks actions on small screens and aligns them to the end on larger screens.</dd>
          <dt><code>&lt;button type="button" onclick="this.closest('dialog').close()"&gt;</code> <span class="badge" data-variant="secondary">Optional</span></dt>
          <dd>Close button. You can also wrap a button in <code>&lt;form method="dialog"&gt;</code>.</dd>
        </dl>
      </dd>
    </dl>
  </dd>
</dl>

## Examples

### Custom close button

<Preview>
<button type="button" onclick="document.getElementById('dialog-custom-close').showModal()" class="btn" data-variant="outline">Share</button>
<dialog id="dialog-custom-close" class="dialog" aria-labelledby="dialog-custom-close-title" aria-describedby="dialog-custom-close-description" onpointerdown="this.dataset.backdropPress = event.target === this" onclick="if (event.target === this && this.dataset.backdropPress === 'true') this.close()">
  <div class="sm:max-w-md">
    <header>
      <h2 id="dialog-custom-close-title">Share link</h2>
      <p id="dialog-custom-close-description">Anyone who has this link will be able to view this.</p>
    </header>
    <section class="flex items-center gap-2">
      <div class="grid flex-1 gap-2">
        <label class="label sr-only" for="dialog-custom-close-link">Link</label>
        <input class="input" id="dialog-custom-close-link" value="https://basecoatui.com/installation/" readonly />
      </div>
    </section>
    <footer class="sm:justify-start">
      <button class="btn" onclick="this.closest('dialog').close()">Close</button>
    </footer>
  </div>
</dialog>
</Preview>

### No close button

<Preview>
<button type="button" onclick="document.getElementById('dialog-no-close').showModal()" class="btn" data-variant="outline">No Close Button</button>
<dialog id="dialog-no-close" class="dialog" aria-labelledby="dialog-no-close-title" aria-describedby="dialog-no-close-description" onpointerdown="this.dataset.backdropPress = event.target === this" onclick="if (event.target === this && this.dataset.backdropPress === 'true') this.close()">
  <div>
    <header>
      <h2 id="dialog-no-close-title">No Close Button</h2>
      <p id="dialog-no-close-description">This dialog doesn't have a close button in the top-right corner.</p>
    </header>
  </div>
</dialog>
</Preview>

### Sticky footer

<Preview>
<button type="button" onclick="document.getElementById('dialog-sticky-footer').showModal()" class="btn" data-variant="outline">Sticky Footer</button>
<dialog id="dialog-sticky-footer" class="dialog" aria-labelledby="dialog-sticky-footer-title" aria-describedby="dialog-sticky-footer-description" onpointerdown="this.dataset.backdropPress = event.target === this" onclick="if (event.target === this && this.dataset.backdropPress === 'true') this.close()">
  <div>
    <header>
      <h2 id="dialog-sticky-footer-title">Sticky Footer</h2>
      <p id="dialog-sticky-footer-description">This dialog has a sticky footer that stays visible while the content scrolls.</p>
    </header>
    <section class="-mx-4 max-h-[50vh] overflow-y-auto px-4 scrollbar">
      <p class="mb-4 leading-normal">Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.</p>
      <p class="mb-4 leading-normal">Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>
      <p class="mb-4 leading-normal">Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>
      <p class="mb-4 leading-normal">Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.</p>
      <p class="mb-4 leading-normal">Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.</p>
      <p class="mb-4 leading-normal">Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>
      <p class="mb-4 leading-normal">Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>
      <p class="mb-4 leading-normal">Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.</p>
    </section>
    <footer>
      <button class="btn" data-variant="outline" onclick="this.closest('dialog').close()">Close</button>
    </footer>
    <button type="button" class="btn" data-variant="ghost" data-size="icon-sm" aria-label="Close dialog" onclick="this.closest('dialog').close()"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-x-icon lucide-x"><path d="M18 6 6 18" /><path d="m6 6 12 12" /></svg></button>
  </div>
</dialog>
</Preview>

### Scrollable content

<Preview>
<button type="button" onclick="document.getElementById('dialog-scrollable').showModal()" class="btn" data-variant="outline">Scrollable Content</button>
<dialog id="dialog-scrollable" class="dialog" aria-labelledby="dialog-scrollable-title" aria-describedby="dialog-scrollable-description" onpointerdown="this.dataset.backdropPress = event.target === this" onclick="if (event.target === this && this.dataset.backdropPress === 'true') this.close()">
  <div>
    <header>
      <h2 id="dialog-scrollable-title">Scrollable Content</h2>
      <p id="dialog-scrollable-description">This is a dialog with scrollable content.</p>
    </header>
    <section class="-mx-4 max-h-[50vh] overflow-y-auto px-4 scrollbar">
      <p class="mb-4 leading-normal">Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>
      <p class="mb-4 leading-normal">Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.</p>
      <p class="mb-4 leading-normal">Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.</p>
      <p class="mb-4 leading-normal">Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>
      <p class="mb-4 leading-normal">Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>
      <p class="mb-4 leading-normal">Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.</p>
      <p class="mb-4 leading-normal">Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.</p>
      <p class="mb-4 leading-normal">Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>
      <p class="mb-4 leading-normal">Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>
      <p class="mb-4 leading-normal">Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.</p>
    </section>
    <button type="button" class="btn" data-variant="ghost" data-size="icon-sm" aria-label="Close dialog" onclick="this.closest('dialog').close()"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-x-icon lucide-x"><path d="M18 6 6 18" /><path d="m6 6 12 12" /></svg></button>
  </div>
</dialog>
</Preview>

### RTL

Dialog positioning and close button placement use logical properties. Set `dir="rtl"` on the dialog or a parent element.

<Preview>
<div dir="rtl">
  <button type="button" onclick="document.getElementById('dialog-rtl').showModal()" class="btn" data-variant="outline">فتح الحوار</button>
  <dialog id="dialog-rtl" class="dialog" aria-labelledby="dialog-rtl-title" aria-describedby="dialog-rtl-description" onpointerdown="this.dataset.backdropPress = event.target === this" onclick="if (event.target === this && this.dataset.backdropPress === 'true') this.close()">
    <div class="sm:max-w-sm">
      <header>
        <h2 id="dialog-rtl-title">تعديل الملف الشخصي</h2>
        <p id="dialog-rtl-description">قم بإجراء تغييرات على ملفك الشخصي هنا. انقر فوق حفظ عند الانتهاء.</p>
      </header>
      <section>
        <form class="grid gap-4">
          <div class="grid gap-3">
            <label class="label" for="dialog-rtl-name">الاسم</label>
            <input class="input" id="dialog-rtl-name" name="name" value="Pedro Duarte" />
          </div>
          <div class="grid gap-3">
            <label class="label" for="dialog-rtl-username">اسم المستخدم</label>
            <input class="input" id="dialog-rtl-username" name="username" value="@peduarte" />
          </div>
        </form>
      </section>
      <footer>
        <button class="btn" data-variant="outline" onclick="this.closest('dialog').close()">إلغاء</button>
        <button class="btn" onclick="this.closest('dialog').close()">حفظ التغييرات</button>
      </footer>
      <button type="button" class="btn" data-variant="ghost" data-size="icon-sm" aria-label="Close dialog" onclick="this.closest('dialog').close()"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-x-icon lucide-x"><path d="M18 6 6 18" /><path d="m6 6 12 12" /></svg></button>
    </div>
  </dialog>
</div>
</Preview>