Shoji

Theming

No hardcoded colors or sizes anywhere in Shoji's CSS or JS — everything routes through --shoji-* custom properties. Dark is the default theme; add the shoji-light class to switch to light.

Important: the lightbox (.shoji-outer) is always appended directly to <body>, not nested inside your gallery container — CSS custom properties only inherit down real DOM ancestry, so applying shoji-light (or any --shoji-* override) to the gallery container itself has no effect on the lightbox. Apply it to <body>, <html>, or another real ancestor of both the gallery container and where Shoji mounts:

<body class="shoji-light">
  ...
  <div id="gallery">...</div>
</body>

Override any property the same way — globally on :root or body:

body {
  --shoji-color-accent: #ff6b4a;
  --shoji-duration: 200ms;
}

There is currently no general way to scope a theme to just one gallery instance on a page with multiple instances — <body>-level classes/overrides apply to all of them; that would need a new GalleryOptions field (e.g. a className option applied directly to .shoji-outer) that doesn't exist yet. backdropOpacity (Settings guide) is the one narrow exception — it sets --shoji-backdrop-opacity directly on that instance's own .shoji-outer, so it's already per-instance today.

Colors

Motion

Spacing & typography

--shoji-caption-max-height caps how tall a caption can grow before it scrolls internally — it grows naturally with its content, only capping (and only then scrolling) once it would reach up under the toolbar. It's set on .shoji-dialog rather than :root deliberately: a custom property's nested var() references resolve at the element where that property is declared, not wherever a descendant later uses it, so it has to live on the same element --shoji-toolbar-height (the toolbar's real, live-measured height, kept up to date by a ResizeObserver in Gallery.ts — correct even if a busy toolbar wraps to multiple rows on a narrow viewport) is actually set on for the substitution to see it. --shoji-caption-collapsed-max-height is the collapsed default applied on top of that cap — as tall as the caption can grow while staying clear of the vertically-centered nav arrows sharing its left edge, floored at roughly one line so a pathologically short dialog can't collapse it to zero. A caption tall enough to still clip past both gets .shoji-caption--truncated and its own modal (--shoji-z-caption-modal below) to read the rest. --shoji-caption-max-width caps how wide it can grow before wrapping — spans (almost) the full dialog width on a narrow/mobile viewport, unchanged from the original behavior, but narrows to roughly a quarter of the viewport above a 768px breakpoint (floored at 14rem so it stays legible in a smaller desktop window) — so a long caption on a wide screen reads as a caption, not a bar spanning the dialog. --shoji-provider-video-top-inset reserves space at the top of a provider embed (YouTube etc.) matching the toolbar's own height, so the embed's hover-revealed title bar never sits under it — also the caption height cap's own fallback, before the real measurement above has landed (normally one animation frame after mount). That one doesn't apply to HTML5 video, which has no top-of-player UI to protect against.

Loading spinner

Shown over a slide while its media is still loading; ring color is --shoji-color-disabled.

Z-index layers

No !important anywhere — a documented, layered scale instead:

Layout plugin properties

--shoji-layout-column-width, --shoji-layout-gutter, and --shoji-layout-tile-aspect are set internally by the plugin per relayout (its columnWidth/gutter JS options feed into these — see LayoutOptions in the API reference) — but overridable the same way as any custom property. The --shoji-layout-heading-* family styles section heading typography and is plain CSS, never JS-driven.

.shoji-layout-heading itself deliberately has no font-size custom property of its own — only its -title-/-subtitle- children do; a host targeting .shoji-layout-heading directly in CSS can already set a shared base size for both, so a redundant third property would only invite drift between the two ways of doing the same thing.

ActiveThumbnail plugin properties

--shoji-active-thumbnail-border-color drives the opt-in highlight: true styling (see Plugins) — set per-element by the plugin from its borderColor JS option (default 'blue'), and again to transparent if highlightDuration fades it out. Overridable with plain CSS like any other custom property; irrelevant when highlight is left at its default (false) — nothing reads it then.

--shoji-active-thumbnail-fade-duration controls how long that fade-to-transparent transition itself takes — set per-element from the highlightFadeDuration JS option (default 800ms), a dedicated property rather than reusing core's own --shoji-duration, since a deliberately slow, visible fade calls for a different default than an ordinary UI transition. Only meaningful alongside highlightDuration — nothing ever animates toward transparent without it.

Icons

Inline SVG sprites, stroke: currentColor — they inherit --shoji-color-fg automatically and are overridable per-button via each plugin's icon option (see Plugins).