/craft-garnish

UI Widgets — Modal, HUD, DisclosureMenu, MenuBtn, Select, CustomSelect

Source

• src/web/assets/garnish/src/Modal.js
• src/web/assets/garnish/src/HUD.js
• src/web/assets/garnish/src/DisclosureMenu.js
• src/web/assets/garnish/src/MenuBtn.js
• src/web/assets/garnish/src/CustomSelect.js
• src/web/assets/garnish/src/SelectMenu.js
• src/web/assets/garnish/src/Select.js
• src/web/assets/garnish/src/ContextMenu.js

Common Pitfalls

• Creating a Modal without a container element — pass null for container and set it later with setContainer(), or pass settings only.
• Not setting triggerElement on Modal — after hiding, focus has nowhere to return; the console warns about it.
• HUD $body is a <form> — calling show() on an HUD that contains form inputs will submit on Enter unless you handle submit event.
• Double-instantiating widgets — all widgets warn and destroy the previous instance, but it's wasteful. Check $el.data('modal') first.
• DisclosureMenu requires aria-controls on the trigger pointing to the container's ID — instantiation throws if the container isn't found.
• MenuBtn expects .menu as the next sibling by default — if your markup differs, pass the menu element explicitly.

Table of Contents

• Modal
• HUD (Heads-Up Display)
• DisclosureMenu
• MenuBtn
• CustomSelect
• SelectMenu
• Select
• ContextMenu

Modal

Full-screen dialog with shade overlay, focus trapping, and optional drag/resize.

Constructor

// With container
var modal = new Garnish.Modal($container, {
  autoShow: true,
  draggable: true,
  dragHandleSelector: '.header',
  resizable: false,
  hideOnEsc: true,
  hideOnShadeClick: true,
  shadeClass: 'modal-shade',
  triggerElement: this.$btn,
  onShow: function () { },
  onHide: function () { },
});

// Without container (set later)
var modal = new Garnish.Modal({ autoShow: false });
modal.setContainer($container);
modal.show();

Settings (defaults)

Key Methods

Events

Statics

Accessibility

• Sets aria-modal="true" and role="dialog" on container
• Traps focus within the modal via Garnish.trapFocusWithin()
• Hides background content from screen readers via Garnish.hideModalBackgroundLayers()
• Adds no-scroll class to <body> while visible
• Restores focus to triggerElement on close (with visibility check)
• Live region (role="status") appended to container for announcements

Building a custom overlay/slideout on Garnish.Base

When you roll your own overlay instead of using Modal/HUD/Slideout, replicate the full lifecycle — the failure modes are easy to hit:

1. Don't disable the instance to "pause" it. If the same Garnish.Base instance owns both the trigger and the overlay, this.disable() silences the trigger too (it works once, then dies). Guard re-entry with state flags or split the overlay into its own instance. See class-system.md (Enable / Disable section).
2. On open: Garnish.setFocusWithin($overlay) (honors .prevent-autofocus), then Garnish.trapFocusWithin($overlay) for the Tab cycle.
3. On close: move focus back to the trigger before setting aria-hidden/inert, then Garnish.releaseFocusWithin($overlay) (the trap is never auto-released). See utilities.md (ARIA & Focus Management section).
4. On destroy: call this.base() so addListener handlers are removed.

HUD (Heads-Up Display)

Floating popover anchored to a trigger element, with a pointer tip. The body is a <form>.

Constructor

var hud = new Garnish.HUD(this.$trigger, bodyHtml, {
  orientations: ['bottom', 'top', 'right', 'left'],
  triggerSpacing: 10,
  windowSpacing: 10,
  onShow: function () { },
  onHide: function () { },
  onSubmit: function () { },
});

Settings (defaults)

Key Methods

Events

Structure

The HUD creates this DOM structure:

<div class="hud">
  <div class="tip tip-top"></div>  <!-- pointer, class varies by orientation -->
  <form class="body">
    <div class="hud-header">...</div>       <!-- auto-detected from body content -->
    <div class="main-container">
      <div class="main">...body content...</div>
    </div>
    <div class="hud-footer">...</div>       <!-- auto-detected from body content -->
  </form>
</div>

Elements with class hud-header or hud-footer inside body content are automatically extracted and placed outside the scrollable main area.

Smart Positioning

HUD evaluates viewport clearance in all four directions and picks the first orientation from the orientations array that has enough room. Falls back to the direction with the most clearance.

DisclosureMenu

Accessible popover menu triggered by a button. Used extensively in Craft's CP for action menus.

Constructor

// Trigger must have aria-controls pointing to the menu container ID
var menu = new Garnish.DisclosureMenu(this.$trigger, {
  position: null,       // 'below' to force below, null for auto
  windowSpacing: 5,
  withSearchInput: false,
});

Required Markup

<button aria-controls="my-menu-id" aria-expanded="false" data-disclosure-trigger>
  Actions
</button>
<div id="my-menu-id" class="menu menu--disclosure">
  <ul class="padded">
    <li><button class="menu-item" type="button">Edit</button></li>
    <li><a class="menu-item" href="/delete">Delete</a></li>
  </ul>
</div>

Settings (defaults)

Key Methods

Item Config Object

menu.addItem({
  label: 'Edit Entry',          // Text label
  // OR: html: '<em>Bold</em>', // HTML label
  icon: 'pencil',               // data-icon value, or Element/Function
  iconColor: 'blue',            // CSS class for icon color
  url: '/admin/entries/123',    // Makes it a link (type: 'link')
  type: 'button',               // 'button' (default) or 'link'
  selected: false,              // Add .sel class
  destructive: false,           // Add .error class + data-destructive
  disabled: false,              // Add .disabled class
  hidden: false,                // Start hidden
  description: 'Edit this',    // Small description text below label
  status: 'live',              // Status indicator dot
  action: 'entries/save',      // Craft action for formsubmit
  params: { entryId: 123 },    // Action params
  confirm: 'Are you sure?',    // Confirmation dialog
  redirect: 'entries',         // Redirect after action
  attributes: { 'data-x': 1 },// Additional HTML attributes
  onActivate: function (el) {}, // Click/activate handler
  callback: function (el) {},   // Alias for onActivate
});

Events

Keyboard Navigation

• Arrow Up/Down: Move focus between items
• Arrow Left/Right: Same as Up/Down
• Tab/Shift+Tab: Move focus in/out of menu, back to trigger
• Escape: Close menu, return focus to trigger
• Type-ahead: Typing characters focuses the first matching item (auto-clears after 1s)
• Search input (when enabled): Filters items by text match

Accessibility & focus

DisclosureMenu signals open/closed state with aria-expanded on the trigger ('true'/'false') and shows/hides the menu by toggling the .visible class plus display — it does not set aria-hidden on the menu container. hide() checks focusIsInMenu() and, if focus is inside, returns it to this.$trigger first, so a closing menu never strands focus on a soon-to-be-display:none item.

When you drive a menu imperatively (or build your own), keep that invariant: return focus to a stable, visible trigger when the menu closes, and move focus off a menu item before acting on it — never leave or restore focus on an item that's about to be hidden. (The same focus-before-hide rule for aria-hidden/inert overlays is in utilities.md.)

Search Input

When withSearchInput: true (or data-with-search-input attribute on container), a search field is prepended. Typing filters <li> items by text content and updates group/hr visibility.

MenuBtn

Button that opens a CustomSelect dropdown menu. Used for Craft's select-style dropdowns.

Constructor

var menuBtn = new Garnish.MenuBtn(this.$btn, this.menu, {
  menuAnchor: null,
  onOptionSelect: function (option) { },
});

// Or auto-detect menu (next .menu sibling)
var menuBtn = new Garnish.MenuBtn(this.$btn);

Settings (defaults)

Key Methods

Events

ARIA

Sets on the button: role="combobox", aria-controls, aria-haspopup="listbox", aria-expanded.

Keyboard

• Space/Enter/Down: Open menu, focus selected option
• Up/Home: Open menu, focus first option
• End: Open menu, focus last option
• When open: Up/Down/PageUp/PageDown navigate, Enter/Space select, Tab selects and moves focus
• Type-ahead search: Characters match option text

CustomSelect

Dropdown listbox menu positioned relative to an anchor element. The underlying component for MenuBtn.

Constructor

var menu = new Garnish.CustomSelect($container, {
  anchor: this.$btn,
  windowSpacing: 5,
  onOptionSelect: function (option) { },
});

Settings (defaults)

Key Methods

Events

ARIA

Container gets role="listbox". Each <li> wrapper gets role="option" and aria-selected. MutationObservers sync aria-selected with the .sel and .hover CSS classes.

Note: Garnish.Menu is a deprecated alias for CustomSelect.

SelectMenu

Extends CustomSelect. When an option is selected, the button text updates to match.

var selectMenu = new Garnish.SelectMenu($container, {
  anchor: this.$btn,
});

Inherits all CustomSelect settings and methods. Adds automatic button label sync on optionselect.

Select

Selection interface for lists of items. Handles single/multi selection, keyboard navigation, shift-click ranges, and Ctrl+A.

Constructor

var select = new Garnish.Select($container, $items, {
  selectedClass: 'sel',
  multi: true,
  allowEmpty: true,
  vertical: true,
  handle: '.item-handle',
  checkboxMode: false,
  checkboxClass: 'checkbox',
  makeFocusable: false,
  onSelectionChange: function () { },
});

Settings (defaults)

Key Methods

Events

Keyboard Navigation

• Arrow keys: Navigate items (respects vertical/horizontal/grid layout)
• Space: Toggle selection on focused item
• Shift+Arrow: Select range
• Ctrl+A: Select all
• Ctrl+Arrow: Jump to furthest item in direction

ContextMenu

Right-click context menu built from option arrays.

Constructor

var contextMenu = new Garnish.ContextMenu(this.$element, [
  { label: 'Edit', onClick: function (ev) { /* ev.currentTarget = right-clicked element */ } },
  '-',  // separator — creates a new <ul> group with <hr>
  { label: 'Delete', onClick: function (ev) { } },
], {
  menuClass: 'menu',
});

Settings (defaults)

Key Methods

Behavior

• Listens for contextmenu and mousedown (right-click) events on the target
• Positions at cursor location (ev.pageX, ev.pageY)
• onClick callback is called with this set to the right-clicked element and ev.currentTarget also set to it
• Uses UiLayerManager for ESC key handling
• Use '-' in the options array to create a separator between option groups

See Also

• class-system.md — Garnish.Base (all widgets extend this), event system, addListener, destroy lifecycle
• utilities.md — UiLayerManager (layer stack for modals/menus), ARIA helpers, focus trapping, key constants
• drag-system.md — DragSort and DragDrop (often used alongside Select for reorderable element lists)
• integration.md — How to register asset bundles, Twig markup for DisclosureMenu/MenuBtn, Craft.initUiElements
• Craft.Slideout — Craft's slideout editor extends Garnish.Base and independently implements modal-like behavior — it manages its own shade element, registers itself with Garnish.uiLayerManager (layer stack), calls Craft.trapFocusWithin() for focus trapping, and registers its own ESC shortcut. Not part of Garnish itself, and not a subclass of Garnish.Modal. Source: src/web/assets/cp/src/js/Slideout.js. When building custom slideout panels, extend Craft.Slideout to get the slide animation, header/footer chrome, and element editor integration.