Dropdown menu

Action menu anchored to a button. It flips sides when it doesn't fit, closes on an outside click, on Escape and when focus leaves, and moves with the arrow keys. The items can be written in the template, which is the way to go when the server is the one that knows what the person is allowed to do.

Examples

The same component, with different positions and content.

The positions are the same as the tooltip's: side top, bottom, left or right, and alignment start, center or end. The default is bottom-start. When the requested side doesn't fit and the opposite one fits better, the menu flips; and it never spills off the screen, it slides back inside.

How to use

A button with data-tuc-dropdown pointing to the panel, and the panel right below it, with hidden. It initializes on its own, including whatever arrives later through HTMX.

<button type="button" class="tuc-btn is-outline" data-tuc-dropdown="#actions">Actions</button>

<div class="tuc-dropdown" id="actions" hidden>
  <div class="tuc-dropdown__label">Contract</div>
  <button type="button" class="tuc-dropdown__item">
    <span class="tuc-dropdown__text">Edit</span>
    <span class="tuc-dropdown__shortcut">⌘E</span>
  </button>
  <a class="tuc-dropdown__item" href="/contracts/12/">
    <span class="tuc-dropdown__text">Open</span>
  </a>
  <hr class="tuc-dropdown__separator">
  <button type="button" class="tuc-dropdown__item is-danger">
    <span class="tuc-dropdown__text">Delete</span>
  </button>
</div>

Panel parts

An item with href is a real <a>. Middle-click still opens it in another tab, and the menu doesn't steal the browser's context menu. Clicking any item closes the menu.

In a Django template

Actions that depend on permissions are left out on the server, not hidden in the browser. In a list, the panel's id carries the row's key so each menu points to its own.

{% for contract in contracts %}
  <button type="button" class="tuc-btn is-outline is-icon is-sm" aria-label="Actions"
          data-tuc-dropdown="#actions-{{ contract.pk }}" data-placement="bottom-end">...</button>

  <div class="tuc-dropdown" id="actions-{{ contract.pk }}" hidden>
    <a class="tuc-dropdown__item" href="{% url 'contract-edit' contract.pk %}">
      <span class="tuc-dropdown__text">Edit</span>
    </a>
    {% if perms.contracts.delete_contract %}
      <hr class="tuc-dropdown__separator">
      <a class="tuc-dropdown__item is-danger" href="{% url 'contract-delete' contract.pk %}">
        <span class="tuc-dropdown__text">Delete</span>
      </a>
    {% endif %}
  </div>
{% endfor %}

In JavaScript

For when the items are computed on the fly. The component builds the panel, and each item gets what to do when it's picked.

const menu = new Tucano.Dropdown('#actions', {
  placement: 'bottom-end',
  items: [
    { label: 'Contract' },
    { text: 'Edit', icon: 'M12 20h9M16.5 3.5a2.12 2.12 0 013 3L7 19l-4 1 1-4z', shortcut: '⌘E', onClick: () => editContract() },
    { text: 'Duplicate', icon: Tucano.ICON_COPY, onClick: (dropdown) => duplicateContract() },
    { text: 'Open', href: '/contracts/12/' },
    { text: 'Archive', disabled: true },
    { separator: true },
    { text: 'Delete', variant: 'danger', onClick: () => deleteContract() },
  ],
});

menu.open();
menu.close();
menu.toggle();
menu.destroy();   // closes and removes the listeners

closeOnPick: false keeps the menu open after a pick, for items that toggle something on and off.

Keyboard and accessibility

The trigger gets aria-haspopup="menu" and aria-expanded, the panel is a menu and each item a menuitem. Opening moves focus inside, and closing returns it to the trigger.

Besides Escape, the menu closes on an outside click, when focus moves elsewhere and when the trigger scrolls off screen. The item highlight follows focus, not just the pointer: the arrows are what move focus, and without that keyboard users wouldn't see where they are.

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.