WTE Docs

Appearance

Upgrade Guide ​

Migration from Theme Extensions v1 to v2 ​

mmenu-js v9 is optional

Theme Extensions v2 supports both mmenu-js v8 and v9 (peerDependencies: "^8.5.24 || ^9.3.0"). Projects can keep their existing mmenu-js v8 installation and upgrade to Theme Extensions v2 without pulling in v9. The mmenu-js v9 upgrade can be done separately, whenever it's convenient.

Pin your mmenu-js version

Because the peer dependency now allows both v8 and v9, make sure your project's own package.json still pins an explicit mmenu-js version (e.g. ^8.5.24). Without an explicit pin, npm install will resolve the peer dependency to the highest satisfying version, which is v9, and pull in the v9 breaking changes below unintentionally.

The Menu extension's own API changed in v2, independently of the mmenu-js version:

  1. Updated property names: Use options instead of args, and configurations instead of configs (legacy names still work as a fallback)
  2. Updated data attributes: Use data-mmenu-options instead of data-mmenu-args (legacy attribute still works as a fallback)
  3. New pageSelector option: Configure the off-canvas page wrapper via options.pageSelector (defaults to #root), instead of relying on a hardcoded selector

If you do upgrade mmenu-js from v8 to v9 as well:

  1. Import new SCSS: Use @import 'wly-statamic-theme-extensions/scss/mmenu.scss';. This stylesheet is only compatible with mmenu-js v9, do not import it while still on v8.
  2. Update offcanvas config: The offcanvas configuration structure has changed in v9
  3. Review CSS variables: mmenu-js v9 uses CSS variables for theming