A Stimulus controller to show modals with the native Dialog element.


  1. Install the package

    $ yarn add @stimulus-components/dialog
  2. Register the controller in your application

    import { Application } from '@hotwired/stimulus'
    import Dialog from '@stimulus-components/dialog'
    const application = Application.start()
    application.register('dialog', Dialog)

This component is based on the native <Dialog> Element. Check the documentation on MDN docs.


<div data-controller="dialog" data-action="click->dialog#backdropClose">
  <dialog data-dialog-target="dialog">
    <p>The modal's content here</p>

    <button type="button" data-action="dialog#close" autofocus>Cancel</button>

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

Optionally, you can customize the dialog style.

/* Prevent scrolling while dialog is open */
body:has(dialog[data-dialog-target='dialog'][open]) {
  overflow: hidden;

/* Customize the dialog backdrop */
dialog {
  box-shadow: 0 0 0 100vw rgb(0 0 0 / 0.5);

@keyframes fade-in {
  0% {
    opacity: 0;
  100% {
    opacity: 1;

@keyframes fade-out {
  0% {
    opacity: 1;
  100% {
    opacity: 0;

/* Add animations */
dialog[data-dialog-target='dialog'][open] {
  animation: fade-in 200ms forwards;

dialog[data-dialog-target='dialog'][closing] {
  animation: fade-out 200ms forwards;


data-dialog-open-valuefalseOpen the modal by default.❌

Extending Controller

You can use inheritance to extend the functionality of any Stimulus component:

import Dialog from '@stimulus-components/dialog'

export default class extends Dialog {
  connect() {
    console.log('Do what you want here.')

  // Function to override on open.
  open() {}

  // Function to override on close.
  close() {}

  // Function to override on backdropClose.
  backdropClose() {}

This controller will automatically have access to targets defined in the parent class.

If you override the connect, disconnect or any other methods from the parent, you'll want to call super.method() to make sure the parent functionality is executed.


Stimulus Component is an MIT licensed open source project and completely free to use. However, the amount of effort needed to maintain and develop new features for the project is not sustainable without proper financial backing. You can support Stimulus Components development on GitHub Sponsors. πŸ™


Do not hesitate to contribute to the project by adapting or adding features ! Bug reports or pull requests are welcome.

Don't forget to drop a 🌟 on GitHub to support the project.


This project is released under the MIT license.