Modal

A dialog that sits on top of everything, with a blurred backdrop and a glow in the tone's color. Built on the native <dialog>: that is where the layer above any z-index, the trapped focus, the Esc key and focus returning to whoever opened it come from — the component only draws the box and animates it.

Examples

Every example below is the same Tucano.modal() with different options.

How to use

There are two ways. From JavaScript, the modal is built on the spot, goes into <body> when it opens and leaves when it closes. From the template, the <dialog> is already on the page and the component only opens, closes and animates it.

In JavaScript

Tucano.modal({
  title: 'Delete contract',
  text: 'This action cannot be undone.',
  tone: 'danger',     // default | danger | success | warning
  size: 'md',         // sm | md | lg | full
  sheet: true,        // slides up from the bottom on mobile
  actions: [
    { text: 'Cancel', variant: 'outline' },
    { text: 'Delete', variant: 'danger', onClick: () => deleteContract() },
  ],
  onClose: (reason, modal) => console.log(reason),
});

// Text only: the shortcut accepts a string
Tucano.modal('File uploaded.');

The Tucano.modal() shortcut creates and opens in one step, and returns the instance. To build it first and open it later, use the class:

const m = new Tucano.Modal({ title: 'New contact', size: 'lg' });
m.content(form);         // any node, or an array of nodes
m.open();
m.close();               // animates out and calls onClose(reason)

Confirmation

The most common use of a modal in a CRUD app is asking before deleting. Tucano.confirm() returns a promise, and the code keeps reading top to bottom:

if (await Tucano.confirm({ title: 'Delete contract?', text: 'This action cannot be undone.', confirm: 'Delete' })) {
  deleteContract();
}

The other modal options work here too, except actions, which confirm() builds on its own. An onClose you pass is still called.

Actions

Each item in actions becomes a .tuc-btn in the footer, in the order it was written.

Written in the template

When the content is rendered by the server — a Django form, with errors and csrf_token —, the <dialog> lives in the template. Every dialog.tuc-modal is adopted on load and on every htmx:afterSwap; opening doesn't insert it and closing doesn't remove it, because the node belongs to whoever wrote the HTML.

<dialog class="tuc-modal is-md" id="delete" aria-labelledby="delete-title">
  <form class="tuc-modal__panel" method="post" action="{% url 'contract-delete' contract.pk %}">
    {% csrf_token %}
    <div class="tuc-modal__top">
      <div class="tuc-modal__header">
        <h2 class="tuc-modal__title" id="delete-title">Delete contract?</h2>
        <p class="tuc-modal__text">This action cannot be undone.</p>
      </div>
      <button type="button" class="tuc-btn is-ghost is-icon is-sm tuc-modal__close" aria-label="Close" data-tuc-modal-close>…</button>
    </div>
    <div class="tuc-modal__footer">
      <button type="button" class="tuc-btn is-outline" data-tuc-modal-close>Cancel</button>
      <button class="tuc-btn is-danger">Delete</button>
    </div>
  </form>
</dialog>

<button class="tuc-btn is-outline" data-tuc-modal="#delete">Delete</button>

The classes are the same ones JavaScript builds: __panel is the box, __top holds the __header (with __title and __text) and the __close, __body is the scrolling body and __footer aligns the actions to the right. Size and tone go as classes on the <dialog> itself: is-lg, is-danger, is-sheet.

Confirm before submitting a form

For a delete form that is already on the page, confirm() intercepts the submit and lets it through only on a yes:

document.querySelector('#delete-contract').addEventListener('submit', async (e) => {
  e.preventDefault();
  const ok = await Tucano.confirm({ title: 'Delete contract?', confirm: 'Delete' });
  if (ok) e.target.submit();
});

Tones and glow

The backdrop isn't just dark: a radial glow behind the box separates the dialog from what is underneath, and the blur takes the page out of focus. The tone changes the color of that glow and of the aura around the box — not the color of the buttons, which is still each action's choice.

Sizes

The box takes the available width up to the size's limit, and the body scrolls when the content gets taller than the screen.

Below 40rem the footer buttons take the full row, so the touch target grows. With sheet, the box loses its bottom corners, sits against the bottom edge and respects the iPhone safe area. It is optional because not every modal wants to become a drawer on mobile.

Keyboard and accessibility

showModal() puts the dialog in the top layer and makes the rest of the page inert: focus can't escape behind it, and on close it goes back to whoever opened it. None of that is our JavaScript — it is the native element.

With title, the dialog gets aria-labelledby pointing to it, and the screen reader announces the title when it opens. The X is a .tuc-btn with aria-label="Fechar". With prefers-reduced-motion, the entrance lasts 100 ms and doesn't grow.

The modal and the drawer share this mechanism: a fix made in one of them applies to the other.

API

Generated from the code on every build — if something is not here, it does not exist.

Options

The notes in this table come from comments in the source code, which are written in Portuguese.