Modal

A component for changing the mode of a page to complete a critical task. This is usually used in conjunction with the dialog component to make modal dialogs.

npm version

npm install @vrembem/modal
@import "vrembem/modal/index";
import { Modal } from "@vrembem/modal"

modal

Modals are composed using classes for styling and data attributes for JavaScript functionality. To open a modal using a trigger, use a unique identifier as the values for both of their respective data attributes. Close buttons are left value-less and should be placed inside the modal element they’re meant to close.

  • data-modal="[unique-id]"
  • data-modal-open="[unique-id]"
  • data-modal-close
<button data-modal-open="[unique-id]">Modal</button>
<div class="modal" data-modal="[unique-id]">
  <div class="modal__dialog">
    <button data-modal-close>Close</button>
    ...
  </div>
</div>

The dialog component is a great fit for composing a modal’s content.

<div class="modal" data-modal="[unique-id]">
  <div class="modal__dialog dialog">
    <div class="dialog__header">
      ...
    </div>
    <div class="dialog__body">
      ...
    </div>
    <div class="dialog__footer">
      ...
    </div>
  </div>
</div>

modal_size_[key]

<div class="modal modal_size_sm" data-modal="[unique-id]">...</div>
<div class="modal modal_size_lg" data-modal="[unique-id]">...</div>

modal_full

<div class="modal modal_full" data-modal="[unique-id]">...</div>

modal_pos_[key]

<div class="modal modal_pos_top" data-modal="[unique-id]">...</div>
<div class="modal modal_pos_bottom" data-modal="[unique-id]">...</div>
<div class="modal modal_pos_left" data-modal="[unique-id]">...</div>
<div class="modal modal_pos_right" data-modal="[unique-id]">...</div>

data-modal-focus

If a modal has the attribute tabindex="-1", it will be given focus when it’s opened. If focus on a specific element inside a drawer is prefered, give it the data-modal-focus attribute. The focus in either case is returned to the trigger element once the modal is closed. Focus handling can be disabled using the { focus: false } setting.

<!-- Focus is returned when modal is closed -->
<button class="link" data-modal-open="[unique-id]">
  Open modal
</button>

<!-- Sets focus to self when opened -->
<div class="modal" data-modal="[unique-id]" tabindex="-1">
  <div class="modal__dialog">
    <button data-modal-close>Close</button>
  </div>
</div>

<!-- Sets focus to input element when opened -->
<div class="modal" data-modal="[unique-id]">
  <div class="modal__dialog">
    <input class="input" data-modal-focus />
  </div>
</div>

data-modal-required

Required modals can not be closed without an explicit action. That means clicking on the background or pressing the escape key to close is disabled. Add the data-modal-required data attribute to a modal to enable this behavior.

<div class="modal" data-modal="[unique-id]" data-modal-required>
  <div class="modal__dialog">
    ...
  </div>
</div>

Modal settings

Key Default Description
autoInit false Automatically instantiates the instance
dataModal "modal" Data attribute for a modal
dataOpen "modal-open" Data attribute for a modal open trigger
dataClose "modal-close" Data attribute for a modal close trigger
dataFocus "modal-focus" Data attribute for setting a modal's focus element
dataRequired "modal-required" Data attribute for making a modal required
stateOpen "is-open" Class used for open state
stateOpening "is-opening" Class used for transitioning to open state
stateClosing "is-closing" Class used for transitioning to closed state
stateClosed "is-closed" Class used for closed state (is ommitted in application)
focus true Toggles the focus handling feature

Modal API

Name Description
modal.init() Initializes the modal instance
modal.destroy() Destroys and cleans up the modal instantiation
modal.open(modalKey, callback) Opens a modal provided the modal key and optional callback
modal.close(returnFocus, callback) Closes a modal and returns focus to trigger element with optional callback