The <hyperkit-modal /> element allows you to create modals that display content in an overlay. It supports dismissing through buttons, backdrops, and custom transitions. You can control visibility via JavaScript, and the modal is easily styled for various use cases.

The modal can be dismiss by pressing the Escape key when it is visible.

Usage

Import the JS:

import "@hyperkitxyz/elements/modal";

Tags:

<hyperkit-modal-summoner summons="modal-id"><button>Open Modal</button></hyperkit-modal-summoner>
<hyperkit-modal id="modal-id" hidden>
  <hyperkit-modal-dismisser><button>Close Modal</button></hyperkit-modal-dismisser>
  <hyperkit-modal-backdrop />
</hyperkit-modal>

<hyperkit-modal /> Options

<hyperkit-modal-summoner /> Options

Children

<hyperkit-modal-summoner summons="modal-id"><button>Open Modal</button></hyperkit-modal-summoner>
<hyperkit-modal id="modal-id" hidden>
  <hyperkit-modal-dismisser><button>Close Modal</button></hyperkit-modal-dismisser>
  <hyperkit-modal-backdrop />
</hyperkit-modal>

<hyperkit-modal-summoner />

• Associates with a <hyperkit-modal> by matching the summons attribute to the modal's id attribute.
• Must contain a <button /> for accessibility.

<hyperkit-modal-dismisser />

• A button used to dismiss the modal.
• Must contain a <button /> for accessibility.

<hyperkit-modal-backdrop />

• A backdrop that dismisses the modal when clicked.
• Can be nested inside the modal and will trigger dismissal when clicked.

JavaScript API

The hyperkit-modal element provides a simple JavaScript API to interact with the modal and programmatically control its visibility.

Showing or Hiding the Modal

You can use the summon() and dismiss() methods on the hyperkit-modal to control its visibility.

Example Usage

const modal = document.querySelector("hyperkit-modal");

// Show the modal
modal.summon();

// Hide the modal
modal.dismiss();

Listening for Visibility Changes

The hyperkit-modal emits summon and dismiss events that you can listen for using the on method. This is triggered when the visibility of the modal changes.

modal.on("summon", () => {
  console.log("Modal is now open");
});

modal.on("dismiss", () => {
  console.log("Modal is now closed");
});

Examples

Styling the Modal

You can apply custom styles to the modal, backdrop, and buttons. The modal is hidden by default with the hidden attribute and can be made visible using JavaScript or CSS.

Example of a Styled Modal

<hyperkit-modal-summoner summons="styledModal">
  <button
    class="px-2.5 py-2 text-sm shadow-sm rounded border-none bg-zinc-900 text-zinc-200 data-[active]:bg-zinc-800 flex items-center justify-center font-medium w-min whitespace-nowrap"
  >
    Open Modal
  </button>
</hyperkit-modal-summoner>
<hyperkit-modal id="styledModal" hidden>
  <hyperkit-modal-dismisser>
    <button class="text-xs">Close</button>
  </hyperkit-modal-dismisser>
  <hyperkit-modal-backdrop />
  <div class="relative z-50 w-64 bg-white rounded-lg shadow-lg p-4">
    <div class="flex justify-between items-center mb-2 text-zinc-800">
      <div class="font-bold">Styled Modal Title</div>
    </div>
    <div class="text-xs text-zinc-600">
      This is some example content for the modal.
    </div>
  </div>
</hyperkit-modal>

Default Hidden with the hidden Attribute

To ensure the modal is hidden by default, add the hidden attribute. The modal will remain hidden until programmatically shown.

<hyperkit-modal id="hiddenModal" hidden />

Using a Backdrop to Dismiss the Modal

To dismiss the modal by clicking on the backdrop, use the <hyperkit-modal-backdrop /> element. When clicked, it will hide the modal.

<hyperkit-modal id="backdropModal" hidden>
  <hyperkit-modal-backdrop />
  <div>
    …
  </div>
</hyperkit-modal>

Adding a Transition

You can animate the modal visibility using the <hyperkit-transition /> element for smooth show/hide effects.

<hyperkit-modal id="transitionModal" hidden>
  <hyperkit-transition
    class="block"
    enter-class="transition-opacity duration-500 ease-in"
    enter-from-class="opacity-0"
    enter-to-class="opacity-100"
    exit-class="transition-opacity duration-300 ease-out"
    exit-from-class="opacity-100"
    exit-to-class="opacity-0"
  >
    …
  </hyperkit-transition>
  <hyperkit-modal-dismisser><button>Close</button></hyperkit-modal-dismisser>
  <hyperkit-modal-backdrop />
</hyperkit-modal>