HystModal

HystModal relies on specific CSS classes and data attributes to function correctly:

• .hystmodal: The main modal container. Must have a unique id. It uses visibility:hidden when closed to prevent focus issues and automatically toggles the aria-hidden attribute.
• .hystmodal__wrap: The scrollable area/overlay behind the modal. This element can trigger closing if closeOnOverlay is enabled.
• .hystmodal__window: The actual modal content block. It is recommended to add aria-labelledby for accessibility.
• [data-hystclose]: Any element inside .hystmodal__window with this attribute will close the modal when clicked (if closeOnButton is enabled).
• .hystmodal__shadow: A shadow element that dims the background. This is automatically inserted by the script before the closing </body> tag.

HystModal relies on specific class names and attributes to manage UX and accessibility:

• .hystmodal: The main container. It must have a unique id. It uses visibility:hidden via CSS to ensure it doesn't receive focus when closed. The aria-hidden attribute is toggled automatically.
• .hystmodal__wrap: The overlay/scrolled area. It can be configured to close the modal on click/tap. It does not have a background by default.
• .hystmodal__window: The actual modal box. For better accessibility, it is recommended to add an aria-labelledby attribute pointing to a title inside the window.
• [data-hystclose]: Any element inside .hystmodal__window with this attribute will close the modal when clicked (if closeOnButton is true).

To use HystModal, instantiate the HystModal class with a configuration object. Upon instantiation, the library automatically attaches event listeners to the document to handle modal triggers via data attributes, keyboard events (Esc, Tab), and overlay clicks.

By default, HystModal looks for elements with the data-hystmodal attribute to trigger opening. You can customize this attribute using the linkAttributeName option.

import HystModal from 'hystmodal';

const modal = new HystModal({
  linkAttributeName: 'data-hystmodal',
  closeOnEsc: true,
  closeOnOverlay: true,
  // ... other config options
});

Use the close() method to close modals.

Arguments:

• modalElem (HTMLElement, optional): The specific modal element to close. If not provided, closeAll() is called instead, closing all currently open modals.

Returns:

• A Promise resolving to the HystModalInstance that was closed, or null if no modal was found.

// Close a specific modal element
const modalEl = document.querySelector('#my-modal');
await modal.close(modalEl as HTMLElement);

// Close all open modals
await modal.close();

The closeAll() method closes every currently open modal in the stack. It returns a Promise that resolves to an array of all HystModalInstance objects that were closed.

const closedModals = await modal.closeAll();
console.log(`Closed ${closedModals.length} modals`);

Use the open() method to trigger a modal manually.

Arguments:

• selectorName (string): The CSS selector for the modal element (ID is recommended).
• isStack (boolean, optional): If true, the new modal opens on top of the current one without closing it. Defaults to the instance's isStacked config.
• starter (HTMLElement, optional): The element that triggered the modal (useful for returning focus on close).

// Open a modal with ID 'my-modal'
await modal.open('#my-modal');

// Open a modal as a stack (on top of current)
await modal.open('#secondary-modal', true);

When a modal is opened, HystModal manages it as a HystModalInstance. This object contains metadata about the active modal.