Modal

Modals are used to prompt the user for input or to display important information that requires the user’s attention.

For example, a modal might be used to open a larger form, ask the user to confirm something they initiated, or display a message that requires the user to take some kind of high-focus action.

Modal basics

The only requirements for creating a modal are a button or other element with an onclick handler to trigger the modal, and then a <dialog> element with class .hc-modal.

The <dialog> should contain 3 content sections that will be positioned automatically: .hc-modal-header for the title and close button, .hc-modal-content for the modal’s content, and .hc-modal-footer for any bottom actions. The <dialog> should have a unique id as well.

If you don’t need a title or footer actions, like for informational modals, it’s possible to exclude one of them. One must be present to contain the close button.

HTML

Expand Edit in Playground Copy


<button class="hc-button hc-button--primary" onclick="modal_full.showModal()">Open 3-part modal</button>
<button class="hc-button hc-button--primary" onclick="modal_simple.showModal()">Open simple modal</button>
<dialog id="modal_full" class="hc-modal">
  <div class="hc-modal-box">
    <header class="hc-modal-header">
      <i class="hc-icon hc-icon--document-text"></i>
      <h3 class="hc-h3 hc-modal-header-title">
        Additional details
      </h3>
      <form method="dialog">
        <button class="hc-button hc-button--icon hc-button--secondary" autofocus>
          <i class="hc-icon hc-icon--close"></i>
        </button>
      </form>
    </header>
    <section class="hc-modal-content">
      <p>
        This is a modal with the default width of 32rem and some content inside. Add content or components like form elements just as you normally would.
      </p>
      <p>
        You can either press the ESC key or click the button abiove to close this modal.
      </p>
    </section>
    <footer class="hc-modal-footer hc-modal-footer--end">
      <form method="dialog">
        <button class="hc-button hc-button--primary hc-button--success">
          Save settings
        </button>
      </form>
    </footer>
  </div>
</dialog>
<dialog id="modal_simple" class="hc-modal">
  <div class="hc-modal-box">
    <section class="hc-modal-content">
      <p>
        This is a modal that just presents the user with some information or perhaps a confirmation.
      </p>
    </section>
    <footer class="hc-modal-footer hc-modal-footer--end">
      <form method="dialog">
        <button class="hc-button hc-button--secondary">
          Cancel
        </button>
      </form>
      <form method="dialog">
        <button class="hc-button hc-button--primary hc-button--danger">
          Yes, delete this item
        </button>
      </form>
    </footer>
</dialog>

The default modal has a width of 32rem. The title should include an icon next to it whenever possible, and the footer should always have a primary action button.

Open and close

To open the modal, use a button or some other interactive element. It should have use the native showModal() method, like this using the click handler: onclick="{id}.showModal()".


<button class="hc-button" onclick="activity-modal.showModal()">
  Open modal
</button>

Closing the modal can be done similarly with another button using the .close() method. Alternatively, you can place a <button> inside of a <form method="dialog"> inside the modal itself. This is an HTML-based way to do this and is done in the example/boilerplate modal above.


<!-- javascript close -->
<button class="hc-button" onclick="activity-modal.close()">
  Close modal via JS
</button>

<!-- HTML close -->
<form method="dialog">
  <button class="hc-button">
    Close modal via HTML
  </button>
</form>

All of these interactions are native to the HTMLDialogElement interface and do not require any additional JavaScript modules or includes!

Sizes

There are 3 general sizes available. The default is 32rem. Add class .hc-modal--sm for a narrow 24rem modal, or class .hc-modal--lg for a wider 48rem modal.

If you need the modal to take the entire screen, add the class .hc-modal--full and it will fill nearly the entire window.

HTML

Expand Edit in Playground Copy


<button class="hc-button hc-button--primary" onclick="modal_sm.showModal()">Open small modal</button>
<button class="hc-button hc-button--primary" onclick="modal_lg.showModal()">Open large modal</button>
<button class="hc-button hc-button--primary" onclick="modal_fs.showModal()">Open fullscreen modal</button>
<dialog id="modal_sm" class="hc-modal hc-modal--sm" autofocus>
  <div class="hc-modal-box">
    <header class="hc-modal-header">
      <i class="hc-icon hc-icon--document-text"></i>
      <h3 class="hc-h3 hc-modal-header-title">
        Small modal
      </h3>
      <form method="dialog">
        <button class="hc-button hc-button--icon hc-button--secondary" autofocus>
          <i class="hc-icon hc-icon--close"></i>
        </button>
      </form>
    </header>
    <section class="hc-modal-content">
      <p>
        This is a small modal with a width of 24rem.
      </p>
      <p>
        It's pretty skinny and should be used for narrow content or simple confirmations or disclosures.
      </p>
    </section>
    <footer class="hc-modal-footer hc-modal-footer--end">
      <form method="dialog">
        <button class="hc-button hc-button--primary hc-button--success">
          Save
        </button>
      </form>
    </footer>
  </div>
</dialog>
<dialog id="modal_lg" class="hc-modal hc-modal--lg">
  <div class="hc-modal-box">
    <header class="hc-modal-header">
      <i class="hc-icon hc-icon--document-text"></i>
      <h3 class="hc-h3 hc-modal-header-title">
        Large modal
      </h3>
      <form method="dialog">
        <button class="hc-button hc-button--icon hc-button--secondary" autofocus>
          <i class="hc-icon hc-icon--close"></i>
        </button>
      </form>
    </header>
    <section class="hc-modal-content">
      <p>
        This is a large modal with a width of 48rem.
      </p>
      <p>
        Use this for larger forms, tables, or things that require large amounts of information to display to the user.
      </p>
    </section>
    <footer class="hc-modal-footer hc-modal-footer--end">
      <form method="dialog">
        <button class="hc-button hc-button--primary hc-button--success">
          Save
        </button>
      </form>
    </footer>
  </div>
</dialog>
<dialog id="modal_fs" class="hc-modal hc-modal--full">
  <div class="hc-modal-box">
    <header class="hc-modal-header">
      <i class="hc-icon hc-icon--document-text"></i>
      <h3 class="hc-h3 hc-modal-header-title">
        Full screen modal
      </h3>
      <form method="dialog">
        <button class="hc-button hc-button--icon hc-button--secondary" autofocus>
          <i class="hc-icon hc-icon--close"></i>
        </button>
      </form>
    </header>
    <section class="hc-modal-content">
      <p>
        This is a full screen modal with a width and height of 100% of the browser window, less a 4rem margin on all sides.
      </p>
      <p>
        Use this for entire application screens that for some reason need to be displayed on the same page as a modal.
      </p>
    </section>
    <footer class="hc-modal-footer hc-modal-footer--end">
      <form method="dialog">
        <button class="hc-button hc-button--primary hc-button--success">
          Save
        </button>
      </form>
    </footer>
  </div>
</dialog>

Complex example

The following example shows a more complex form embedded within a modal, replete with how we recommend arranging information text, button groups in the footer, and other types of components.

Note that some of the formatting here make use of Tailwind’s utility classes. If you have access to these you may copy this verbatim, otherwise compare it to the CSS framework in your app instead.

HTML

Expand Edit in Playground Copy


<button class="hc-button hc-button--primary hc-button--boost" onclick="modal_form.showModal()">
  <i class="hc-icon hc-icon--plus"></i>
  Create a new activity
</button>
<dialog id="modal_form" class="hc-modal hc-modal--lg">
  <div class="hc-modal-box">
    <header class="hc-modal-header">
      <i class="hc-icon hc-icon--page"></i>
      <h3 class="hc-h3 hc-modal-header-title">
        Add a new activity
      </h3>
      <form method="dialog">
        <button class="hc-button hc-button--icon hc-button--secondary">
          <i class="hc-icon hc-icon--close"></i>
        </button>
      </form>
    </header>
    <section class="hc-modal-content">
      <label class="hc-form-control">
        <span class="hc-label">
          <span class="hc-label-text">What would you like to do?</span>
        </span>
        <select class="hc-select" autofocus>
          <option value="1">Teacher interactions</option>
        </select>
      </label>
      <div class="hc-form-control">
        <span class="hc-label">
          <span class="hc-label-text">Assigned to <span class="hc-required">(required)</span></span>
        </span>
        <div class="flex flex-row items-center justify-start gap-2">
          <span class="hc-badge hc-badge--avatar hc-badge--lg hc-badge--primary">
            <img src="https://ui-avatars.com/api/?name=Falco+Lombardi&background=random" alt="Falco Lombardi" title="Falco Lombardi avatar">
            <span>Falco Lombardi</span>
            <i class="hc-icon hc-icon--close hc-icon--12 mt-px"></i>
          </span>
          <button class="hc-button hc-button--tertiary hc-button--sm">
            <i class="hc-icon hc-icon--plus"></i>
            Assign a staff member
          </button>
        </div>
      </div>
      <label class="hc-form-control">
        <span class="hc-label">
          <span class="hc-label-text">Date</span>
        </span>
        <input type="date" class="hc-input" value="2024-08-20">
      </label>
      <div class="hc-input-cols hc-input-cols--2">
        <label class="hc-form-control">
          <span class="hc-label">
            <span class="hc-label-text">Start time <span class="hc-required">(required)</span></span>
          </span>
          <input type="time" class="hc-input" value="10:00">
        </label>
        <label class="hc-form-control">
          <span class="hc-label">
            <span class="hc-label-text">End time <span class="hc-required">(required)</span></span>
          </span>
          <input type="time" class="hc-input" value="11:00">
        </label>
      </div>
      <div class="hc-input-cols hc-input-cols--2">
        <label class="hc-form-control">
          <span class="hc-label">
            <span class="hc-label-text">Activity type</span>
          </span>
          <select class="hc-select">
            <option value="">Choose one...</option>
            <option value="1">Meeting</option>
            <option value="2">Classroom visit</option>
          </select>
        </label>
        <label class="hc-form-control">
          <span class="hc-label">
            <span class="hc-label-text">Focus areas</span>
          </span>
          <select class="hc-select">
            <option value="">Choose one...</option>
            <option value="1">Classroom engagement</option>
            <option value="2" selected>Questioning techniques</option>
          </select>
        </label>
      </div>
      <label class="hc-form-control">
        <span class="hc-label">
          <span class="hc-label-text">Do you want to add notes?</span>
        </span>
        <select class="hc-select">
          <option value="">Choose one...</option>
          <option value="1">Yes</option>
          <option value="2">No</option>
        </select>
      </label>
      <label class="hc-form-control">
        <input id="check1" type="checkbox" class="hc-checkbox">
        <span class="hc-label">
          <span class="hc-label-text">Send an email notification to Falco Lombardi</span>
        </span>
      </label>
    </section>
    <footer class="hc-modal-footer hc-modal-footer--end">
      <form method="dialog">
        <button class="hc-button hc-button--secondary">
        Cancel
        </button>
      </form>
      <button class="hc-button hc-button--primary hc-button--success" onclick="modal5.close()">
        Create activity
      </button>
    </footer>
  </div>
</dialog>

Design guidelines

Technical guidelines

The autofocus attribute should be added to the element the user is expected to interact with immediately upon opening a modal.

If no other element involves more immediate interaction, add autofocus to the close button inside the modal, or the modal itself if the user is expected to click/activate it to dismiss.
Do not add the tabindex property to the <dialog> element as it is not interactive and does not receive focus. The modal’s contents, including the close button contained in the modal header, can receive focus and be interactive.

Design considerations

Modals are not meant to be used to show error, wait, or success states. Use the Toast component or the Alert component for this.
The footer should contain at least one and no more than three actions. These actions should be grouped with appropriate distinction between primary and secondary action and the tertiary action.
The yes/confirm/success action should be the primary button. The primary action should be furthest to the right.
The secondary button should be placed directly to the left of primary button and both should be positioned to the right. If these are the only buttons, add .hc-modal-footer--end to the footer element. If there are 3 buttons, group these 2 actions inside of a wrapper element.
If there is a clear requirement of having an extra button, that should be grouped separately and placed on the left of the footer.
When user acknowledgment is required to proceed, a single action button may be presented.