Skip to main content

Components

Modal

Dialogs for lightboxes, notifications and confirmations — opened by a button, no script required.

How it works

The modal is a <dialog class="modal" popover>. A button with popovertarget pointing at its id opens it in the top layer with a backdrop, light-dismiss and Escape handling. Close buttons use popovertargetaction="hide".

  • Baseline: Popover API (Chrome 114, Safari 17, Firefox 125).
  • Enhancement: add commandfor + command="show-modal" to the trigger for a true modal — the rest of the page becomes inert and focus is trapped. Engines without invoker commands ignore those attributes and use popovertarget.
  • Enhancement: .fade animates in and out with @starting-style.
  • Fallback: a plain <div class="modal" id="…"> opened by <a href="#…"> via :target. Works everywhere; no light-dismiss.
Unlike stock Bootstrap, .modal is the box, not a full-screen container. The backdrop is ::backdrop. That is what makes a click outside the dialog land on the backdrop and dismiss it.

Live demo

HTML
<button type="button" class="btn btn-primary" popovertarget="modal-demo">Launch demo modal</button>

<dialog class="modal fade" popover id="modal-demo" aria-labelledby="modal-demo-title">
  <div class="modal-dialog">
    <div class="modal-content">
      <div class="modal-header">
        <h2 class="modal-title h5" id="modal-demo-title">Modal title</h2>
        <button type="button" class="btn-close" popovertarget="modal-demo" popovertargetaction="hide" aria-label="Close"></button>
      </div>
      <div class="modal-body">
        <p>Woo-hoo, you're reading this text in a modal!</p>
      </div>
      <div class="modal-footer">
        <button type="button" class="btn btn-secondary" popovertarget="modal-demo" popovertargetaction="hide">Close</button>
        <button type="button" class="btn btn-primary" autofocus>Save changes</button>
      </div>
    </div>
  </div>
</dialog>

True modal with invoker commands

Put both attribute sets on the trigger. Where command is understood, the dialog opens with showModal() semantics (inert page, focus trap, Escape). Elsewhere, the popover path runs. Close buttons likewise carry both command="close" and popovertargetaction="hide".

HTML
<button type="button" class="btn btn-primary" commandfor="modal-cmd" command="show-modal" popovertarget="modal-cmd">Open true modal</button>

<dialog class="modal fade" popover id="modal-cmd" aria-labelledby="modal-cmd-title">
  <div class="modal-dialog modal-dialog-centered">
    <div class="modal-content">
      <div class="modal-header">
        <h2 class="modal-title h5" id="modal-cmd-title">Inert background</h2>
        <button type="button" class="btn-close" commandfor="modal-cmd" command="close" popovertarget="modal-cmd" popovertargetaction="hide" aria-label="Close"></button>
      </div>
      <div class="modal-body">Try tabbing — focus stays inside when the engine supports <code>command</code>.</div>
      <div class="modal-footer">
        <form method="dialog" class="d-contents">
          <button type="submit" class="btn btn-primary">Done</button>
        </form>
      </div>
    </div>
  </div>
</dialog>
<form method="dialog"> only closes a dialog that has the open attribute, i.e. one opened by command="show-modal". For the popover path, keep a popovertargetaction="hide" button too.

:target fallback

For environments that cannot rely on the Popover API at all. Close with href="#!".

Open :target modal
HTML
<a class="btn btn-outline-primary" href="#modal-target" role="button">Open :target modal</a>

<div class="modal fade" id="modal-target" role="dialog" aria-labelledby="modal-target-title">
  <div class="modal-dialog">
    <div class="modal-content">
      <div class="modal-header">
        <h2 class="modal-title h5" id="modal-target-title">Fragment-driven</h2>
        <a class="btn-close" href="#!" aria-label="Close"></a>
      </div>
      <div class="modal-body">Opened by the URL fragment. Universal, but no light-dismiss and no Escape.</div>
      <div class="modal-footer"><a class="btn btn-primary" href="#!">Close</a></div>
    </div>
  </div>
</div>

Static backdrop

Use popover="manual" to disable light-dismiss and Escape; the modal then closes only through its buttons.

HTML
<button type="button" class="btn btn-primary" popovertarget="modal-static">Launch static backdrop modal</button>
<dialog class="modal fade" popover="manual" id="modal-static" aria-labelledby="modal-static-title">
  <div class="modal-dialog">
    <div class="modal-content">
      <div class="modal-header">
        <h2 class="modal-title h5" id="modal-static-title">Decide</h2>
        <button type="button" class="btn-close" popovertarget="modal-static" popovertargetaction="hide" aria-label="Close"></button>
      </div>
      <div class="modal-body">Clicking outside does nothing. Use a button.</div>
      <div class="modal-footer">
        <button type="button" class="btn btn-secondary" popovertarget="modal-static" popovertargetaction="hide">Close</button>
        <button type="button" class="btn btn-primary" popovertarget="modal-static" popovertargetaction="hide">Understood</button>
      </div>
    </div>
  </div>
</dialog>

Scrolling long content

By default the whole modal box scrolls. Add .modal-dialog-scrollable to scroll only the body.

HTML
<button type="button" class="btn btn-primary" popovertarget="modal-scroll">Scrollable body</button>
<dialog class="modal fade" popover id="modal-scroll" aria-labelledby="modal-scroll-title">
  <div class="modal-dialog modal-dialog-scrollable">
    <div class="modal-content">
      <div class="modal-header">
        <h2 class="modal-title h5" id="modal-scroll-title">Card of matches</h2>
        <button type="button" class="btn-close" popovertarget="modal-scroll" popovertargetaction="hide" aria-label="Close"></button>
      </div>
      <div class="modal-body">
        <p>Match 1 · Match 2 · Match 3 · Match 4 · Match 5 · Match 6 · Match 7 · Match 8 · Match 9 · Match 10.</p>
        <p>Match 11 · Match 12 · Match 13 · Match 14 · Match 15 · Match 16 · Match 17 · Match 18.</p>
        <p>Match 19 · Match 20 · Match 21 · Match 22 · Match 23 · Match 24 · Match 25 · Match 26.</p>
        <p>Match 27 · Match 28 · Match 29 · Match 30 · Match 31 · Match 32 · Match 33 · Match 34.</p>
        <p>Match 35 · Match 36 · Match 37 · Match 38 · Match 39 · Match 40 · Match 41 · Match 42.</p>
        <p>Match 43 · Match 44 · Match 45 · Match 46 · Match 47 · Match 48 · Match 49 · Match 50.</p>
        <p>Match 51 · Match 52 · Match 53 · Match 54 · Match 55 · Match 56 · Match 57 · Match 58.</p>
        <p>Match 59 · Match 60 · Match 61 · Match 62 · Match 63 · Match 64 · Match 65 · Match 66.</p>
      </div>
      <div class="modal-footer">
        <button type="button" class="btn btn-primary" popovertarget="modal-scroll" popovertargetaction="hide">Close</button>
      </div>
    </div>
  </div>
</dialog>

Vertically centered

Add .modal-dialog-centered to .modal-dialog.

HTML
<button type="button" class="btn btn-primary" popovertarget="modal-center">Vertically centered</button>
<dialog class="modal fade" popover id="modal-center" aria-labelledby="modal-center-title">
  <div class="modal-dialog modal-dialog-centered">
    <div class="modal-content">
      <div class="modal-header">
        <h2 class="modal-title h5" id="modal-center-title">Centered</h2>
        <button type="button" class="btn-close" popovertarget="modal-center" popovertargetaction="hide" aria-label="Close"></button>
      </div>
      <div class="modal-body">Right in the middle of the ring.</div>
    </div>
  </div>
</dialog>

Optional sizes

.modal-sm, .modal-lg and .modal-xl on .modal-dialog. The box width follows automatically.

HTML
<button type="button" class="btn btn-outline-primary" popovertarget="modal-xl">Extra large</button>
<button type="button" class="btn btn-outline-primary" popovertarget="modal-lg">Large</button>
<button type="button" class="btn btn-outline-primary" popovertarget="modal-sm">Small</button>

<dialog class="modal fade" popover id="modal-xl"><div class="modal-dialog modal-xl"><div class="modal-content"><div class="modal-header"><h2 class="modal-title h5">Extra large modal</h2><button type="button" class="btn-close" popovertarget="modal-xl" popovertargetaction="hide" aria-label="Close"></button></div><div class="modal-body">…</div></div></div></dialog>
<dialog class="modal fade" popover id="modal-lg"><div class="modal-dialog modal-lg"><div class="modal-content"><div class="modal-header"><h2 class="modal-title h5">Large modal</h2><button type="button" class="btn-close" popovertarget="modal-lg" popovertargetaction="hide" aria-label="Close"></button></div><div class="modal-body">…</div></div></div></dialog>
<dialog class="modal fade" popover id="modal-sm"><div class="modal-dialog modal-sm"><div class="modal-content"><div class="modal-header"><h2 class="modal-title h5">Small modal</h2><button type="button" class="btn-close" popovertarget="modal-sm" popovertargetaction="hide" aria-label="Close"></button></div><div class="modal-body">…</div></div></div></dialog>

Fullscreen

.modal-fullscreen and the responsive .modal-fullscreen-{sm|md|lg|xl|xxl}-down variants.

HTML
<button type="button" class="btn btn-outline-primary" popovertarget="modal-full">Fullscreen</button>
<button type="button" class="btn btn-outline-primary" popovertarget="modal-full-md">Fullscreen below md</button>

<dialog class="modal fade" popover id="modal-full"><div class="modal-dialog modal-fullscreen"><div class="modal-content"><div class="modal-header"><h2 class="modal-title h5">Full screen</h2><button type="button" class="btn-close" popovertarget="modal-full" popovertargetaction="hide" aria-label="Close"></button></div><div class="modal-body">…</div><div class="modal-footer"><button type="button" class="btn btn-primary" popovertarget="modal-full" popovertargetaction="hide">Close</button></div></div></div></dialog>
<dialog class="modal fade" popover id="modal-full-md"><div class="modal-dialog modal-fullscreen-md-down"><div class="modal-content"><div class="modal-header"><h2 class="modal-title h5">Full screen below md</h2><button type="button" class="btn-close" popovertarget="modal-full-md" popovertargetaction="hide" aria-label="Close"></button></div><div class="modal-body">…</div><div class="modal-footer"><button type="button" class="btn btn-primary" popovertarget="modal-full-md" popovertargetaction="hide">Close</button></div></div></div></dialog>

Accessibility

  • Use <dialog> so the role is native. Add aria-labelledby pointing at the title.
  • Put autofocus on the primary control; the Popover API honours it on open.
  • Prefer the command="show-modal" enhancement when the dialog demands a decision — it makes the page inert.
  • Dark mode: the modal inherits data-bs-theme from its ancestor, and the backdrop is always 50 % black.

CSS

All of Bootstrap's --bs-modal-* variables apply. Additional behaviour:

.modal                 // the box: fixed, centered horizontally, fit-content tall
.modal:popover-open    // shown by popovertarget
.modal[open]           // shown by command="show-modal"
.modal:target          // shown by URL fragment (backdrop via box-shadow)
.modal::backdrop       // dimmer
body:has(.modal:popover-open) { overflow: hidden }   // scroll lock