craft-garnish

Garnish — Craft CMS Control Panel JavaScript Toolkit

Reference for Garnish, Craft CMS's built-in JavaScript UI framework. Covers the class system, UI widgets, drag interactions, form components, accessibility helpers, and integration with Craft's CP.

This skill is scoped to Garnish itself — the JavaScript library at src/web/assets/garnish/. For PHP-side plugin development (elements, controllers, services), see the craftcms skill. For CP template markup that Garnish widgets attach to, see the craftcms skill's cp.md reference.

Companion Skills — Load When Needed

• craftcms — Load when the task involves PHP asset bundle classes, plugin architecture, or CP template markup that Garnish widgets attach to. Skip for pure JavaScript refactoring, Garnish API questions, or JS-only tasks.
• craft-php-guidelines — Load only when editing PHP files (asset bundle classes, controllers that register JS). Skip for pure JS work.

Documentation

• Garnish source: src/web/assets/garnish/src/ in the Craft CMS repository
• No official external documentation exists — this skill IS the documentation.

Use WebFetch on Craft's class reference (https://docs.craftcms.com/api/v5/) when looking up PHP-side asset bundle registration.

Common Pitfalls (Cross-Cutting)

• Using jQuery .on() directly instead of this.addListener() — listeners added via jQuery won't auto-clean on destroy(), causing memory leaks.
• Forgetting this.base() when overriding destroy() — parent cleanup (listener removal, event teardown) gets skipped.
• Using click instead of activate event on non-<button> elements — activate handles both click and keyboard (Space/Enter), making the UI accessible.
• Fighting UiLayerManager by binding ESC directly — use Garnish.uiLayerManager.registerShortcut(Garnish.ESC_KEY, callback) so escape routes through the layer stack correctly.
• Magic key code numbers instead of Garnish.ESC_KEY, Garnish.RETURN_KEY, etc. — constants are self-documenting and consistent.
• Instantiating Garnish widgets before the DOM is ready — Garnish requires jQuery and all dependencies loaded first; in plugin assets, rely on CpAsset dependency chain.
• Not calling destroy() when removing widgets — orphaned listeners accumulate, especially in slideouts and live preview where DOM is repeatedly created/destroyed.
• Importing Garnish into webpack bundles instead of using the external — import Garnish from 'garnishjs' resolves to window.Garnish via webpack externals; bundling it duplicates 134KB.
• Giving name attributes to inputs in a panel injected into another form (an entry-edit sidebar panel, a CP template hook) — the host form serializes them on save and your plugin's values are silently swallowed. Inputs are id-only, your JS reads them by id and posts to your own endpoint, and an Enter-key guard keeps the host form from submitting. See integration.md (Panels Injected Into Another Form).
• Using deprecated Garnish.Menu instead of Garnish.CustomSelect — Menu is an alias kept for BC only.
• Using deprecated Garnish.escManager or Garnish.shortcutManager instead of Garnish.uiLayerManager — the newer manager provides layer-aware keyboard routing that respects the modal/menu stack.