Modals with HTML dialog element, TailwindCSS and StimulusJS

Safari has finally adopted the <dialog> HTML element, and now it is supported by all browsers!

HTML <dialog> is basically a “modal”:

• centered on page by default
• disables background clicks when open
• can be closed with native HTML (without extra JS)
• includes CSS to blur/dim background by default
• can be closed with Escape key

Example:

Display basic dialog:

<dialog open>
  <span>You can see me</span>
</dialog>

Dialog with “Close” button (without submitting form):

method="dialog" on form

<dialog open>
  <span>You can see me</span>
  <form method="dialog">
    <button type="submit" autofocus>Cancel</button>
  </form>
</dialog>

Dialog with both “Close” button and regular “Submit” button on form:

formmethod="dialog" on button

<dialog open>
  <span>You can see me</span>
  <form>
    abc
    <button formmethod="dialog" type="submit">Cancel</button>
    <button>Submit</button>
  </form>
</dialog>

With button to open modal:

<div data-controller="dialog">
  <button data-action="dialog#open">
    Open modal
  </button>

  <dialog data-dialog-target="modal">
    <span>You can see me</span>
    <form method="dialog">
      <button type="submit" autofocus>Cancel</button>
    </form>
  </dialog>
</div>

// app/javascript/controllers/dialog_controller.js
static targets = ["modal"]

open() {
  this.modalTarget.showModal()
  // this.modalTarget.show()
}

• .show() - background is clickable, can be used like a regular dropdown
• .showModal() - background is not clickable, you can apply css styles like blur. You can use “Esc” key close it!

Most likely you want to use exclusively .showModal().

Background blur, color, opacity

dialog::backdrop {
  backdrop-filter: blur(8px);
  background-color: hsl(250, 100%, 50%, 0.25);
}

Close on click outside

  clickOutside(event) {
    if (event.target === this.dialogTarget) {
      this.close()
    }
  }

-<div data-controller="dialog">
+<div data-controller="dialog" data-action="click->dialog#clickOutside">

Disable background scrolling when dialog is open

  open() {
    this.dialogTarget.showModal()
    document.body.classList.add("overflow-hidden");
  }

  close() {
    this.dialogTarget.close()
    document.body.classList.remove("overflow-hidden");
  }

Important: It will not work with the default behaviour of closing by clicking Escape or by method="dialog".

To make it actually work you need to listen to the close event on <dialog>:

  connect() {
    this.modalTarget.addEventListener("close", this.enableBodyScroll.bind(this))
  }

  enableBodyScroll() {
    document.body.classList.remove('overflow-hidden')
  }

Blur background

/* app/assets/stylesheets/application.css */
dialog::backdrop {
  backdrop-filter: blur(8px);
  /* background-color: hsl(250, 100%, 50%, 0.25); */
}

Final result

• ✅ Styled modal
• ✅ Blur background
• ✅ Close on Escape
• ✅ Close on click outside
• ✅ Close on clicking button

<div data-controller="dialog" data-action="click->dialog#clickOutside">
  <button data-action="click->dialog#open">Open dialog</button>
  <dialog data-dialog-target="modal"
          class="backdrop:bg-gray-400 backdrop:bg-opacity-90 z-10 rounded-md border-4 bg-sky-900 w-full md:w-2/3 mt-24">
    <div class="p-8">
      <button class="bg-slate-400" data-action="dialog#close">Cancel</button>
      <p>Greetings, one and all!</p>
      <form>
        <button formmethod="dialog">Cancel</button>
        <button>OK</button>
      </form>
    </div>
  </dialog>
</div>

// app/javascript/controllers/dialog_controller.js
import { Controller } from "@hotwired/stimulus"

// Connects to data-controller="dialog"
export default class extends Controller {
  static targets = ["modal"]

  connect() {
    this.modalTarget.addEventListener("close", this.enableBodyScroll.bind(this))
  }

  disconnect() {
    this.modalTarget.removeEventListener("close", this.enableBodyScroll.bind(this))
  }

  open() {
    // this.modalTarget.show()
    this.modalTarget.showModal()
    document.body.classList.add('overflow-hidden')
  }

  close() {
    this.modalTarget.close()
    // document.body.classList.remove('overflow-hidden')
  }

  enableBodyScroll() {
    document.body.classList.remove('overflow-hidden')
  }

  clickOutside(event) {
    if (event.target === this.modalTarget) {
      this.close()
    }
  }
}

Inspired by:

• https://blog.webdevsimplified.com/2023-04/html-dialog/
• https://dev.to/thomasvanholder/create-a-modal-with-the-html-dialog-element-tailwind-and-stimulus-573b

To explore in the future:

• submitting a form with errors
• submitting a form with format.html, format.turbo_stream

That’s it for now! 🤠