Shoji

Plugins

Everything beyond the minimal lightbox is a plugin, including features you might expect to be built in (zoom, fullscreen, rotate/flip). Core stays small; plugins are opt-in, one at a time, via the plugins array.

Loading a plugin

new Shoji('#gallery', {
  plugins: [Shoji.Zoom, Shoji.Fullscreen],
});

Every official plugin's defaults are chosen so that just appearing in plugins is a complete, working config — no per-plugin options object required. Add one only to override something:

new Shoji('#gallery', {
  plugins: [Shoji.Zoom],
  zoom: { maxScale: 8 },
});

The options[plugin.name] convention

Each plugin's options nest under a top-level key matching its name — zoom: {...} for the plugin named 'zoom', layout: {...} for 'layout', and so on. This applies the same way to custom plugins you write yourself.

Official plugins

.shoji-thumb-active img {
  outline: 3px solid #4da3ff;
  outline-offset: -2px;
}

Writing a custom plugin

A plugin is a plain object — no base class. The full shape:

const MyPlugin = {
  name: 'myPlugin',
  version: '1.0.0',   // optional — yours to track; core never reads it
  requires: [],        // optional — other plugin names that must also be in `plugins`
  defaults: { message: 'Hello from a plugin' },

  init(ctx) {
    const message = String(ctx.options.message);
    const unsubscribe = ctx.ui.toolbar('right', {
      label: message,
      onClick: () => alert(message),
    });

    return () => unsubscribe(); // cleanup, run on destroy()/reinit()
  },
};

new Shoji('#gallery', { plugins: [MyPlugin], myPlugin: { message: 'Hi!' } });

The one easy way to get requires wrong — it fails silently (logged to the console, not thrown), which is exactly what makes it easy to miss: the dependent plugin's init() just never runs, so whatever it registers (a toolbar button, in this example) simply never appears, with no error visible unless you're looking at the console.

// Wrong — plugin objects, not their name strings:
requires: [Shoji.Zoom, MyOtherPlugin]

// Right — name strings. Position in `plugins` doesn't matter either way —
// MyOtherPlugin can be listed before *or* after ThisPlugin, both work:
requires: ['zoom', 'myOtherPlugin']

requires is checked against the whole declared plugins array, not registration order — a dependency only needs to be somewhere in the list, not listed earlier than whatever needs it. It even resolves chains correctly: if myOtherPlugin itself had an unmet requires, ThisPlugin would be skipped too, not just left silently assuming a broken dependency was fine. What never changes regardless: every plugin's init() still runs — and every ctx.ui.toolbar() button still lands — in exactly the order the plugins array itself declares.

Why declare requires at all?

requires doesn't hand you a reference to the other plugin, and it doesn't wire anything up — a plugin can call ctx.on(...) for an event another plugin emits whether or not it's listed in requires, and it works exactly the same either way once that other plugin is actually loaded. What requires buys you is a fail-fast guard for the case where it isn't loaded: instead of your plugin quietly initializing anyway and sitting there doing nothing (a subscription that never fires, a button that never updates — no error, no obvious symptom), it gets skipped up front with a clear console error naming exactly what's missing.

For example, a toolbar readout that shows the current zoom level only makes sense once Shoji.Zoom is also loaded — it works purely by listening for Zoom's own zoomChange event:

const ZoomIndicator = {
  name: 'zoomIndicator',
  requires: ['zoom'], // reads Zoom's own zoomChange event — pointless without it

  init(ctx) {
    const unsubscribe = ctx.ui.toolbar('left', { label: '100%', onClick: () => {} });
    const off = ctx.on('zoomChange', ({ scale }) => {
      // update the toolbar label to `${Math.round(scale * 100)}%`
    });

    return () => {
      unsubscribe();
      off();
    };
  },
};

Leave out requires: ['zoom'] and the code above still behaves identically whenever Shoji.Zoom is in plugins. The difference only shows up when it isn't: without requires, ZoomIndicator still initializes, its button still renders, and it just sits stuck at 100% forever — zoomChange never fires, with nothing telling you why. With requires: ['zoom'], that same misconfiguration gets skipped entirely, logged as an unmet dependency instead of a silently dead button.

What ctx gives you:

• ctx.gallery — the full public Gallery API (navigation, events, updateSlides, etc.).
• ctx.options — this plugin's own merged options (defaults + whatever the host passed under options[name]).
• ctx.on(event, fn) / ctx.emit(event, detail) — the same typed event bus gallery.on() reads from. Works in both directions: listen for another plugin's state (zoomChange above), or command one to act — ctx.emit('requestZoomIn', {}) zooms in without importing Zoom at all. See the Events guide's "Plugin commands" table for the full list.
• ctx.ui.toolbar(slot, el) — add a button/element to the 'left', 'center', or 'right' toolbar slot. 'right' is where every official plugin puts its controls (inserted immediately before the close button). If too many buttons end up sharing a row for the viewport to fit, core collapses the extra ones (latest-registered first) into a small popover behind a caret automatically — nothing a plugin needs to handle itself. How many stay pinned before that kicks in is the host's own maxPinnedToolbarButtons setting (default 2) — see the Settings guide.
• ctx.ui.overlay(el, layer?) — mount an element into the dialog, absolutely positioned by you.
• ctx.ui.outer() — the whole lightbox element (backdrop + dialog + controls), for something like Fullscreen that needs to act on the entire lightbox.
• ctx.ui.registerShortcut(key, fn) — a keyboard shortcut, scoped to while the lightbox is open.
• ctx.ui.registerVideoProvider(name, renderFn) — supplies the embed for a non-'html5' video.provider value (e.g. 'youtube'). renderFn(container, item, onReady, signal) builds into container and calls onReady() once it should show; signal fires 'abort' once the slide is no longer wanted — release everything there, since setup is often async and may resolve after eviction.
• ctx.storage — per-gallery scratch storage, cleared on destroy().

Rules worth knowing: plugins talk to each other only through events, never direct imports — requires: ['otherPlugin'] declares a hard dependency (checked against the whole declared plugins array, not registration order; a missing or failed dependency logs an error and skips that plugin, without taking down the rest). Everything registered through ctx is disposed automatically on destroy()/reinit() — the function your init() returns is for anything else you set up by hand.

Plugins init eagerly, at construction time — not lazily on first open() — so ctx.ui.* always has real DOM to act on synchronously inside init().

Checking what's loaded

gallery.getActivePlugins() returns the names of plugins that actually initialized on that instance — string[], deduplicated, excluding an invalid plugins[] entry (e.g. a stale dist build referencing a plugin static that doesn't exist) or one skipped for an unmet requires. There's no separate "official vs. custom" distinction anywhere in the API — an official plugin like Shoji.Zoom and one you write yourself go through the exact same plugins array and the exact same loading path, so this list can't and doesn't tell them apart either.

new Shoji('#gallery', { plugins: [Shoji.Zoom, Shoji.RotateFlip] });
gallery.getActivePlugins(); // ['zoom', 'rotateFlip']