Theme Packs

Theme Packs

🌐 English · Deutsch

Theme packs reskin the entire MediaForge WebUI — fonts, colors, animations, checkbox and input styles, number steppers, the calendar layout, background images and more. They are installed from the same Module Store as modules (see Modules), but unlike modules they are CSS + assets only: no JavaScript, no Python. A theme can change how MediaForge looks, never what it does.

Installing a theme

1. Open the Module Manager (/extensions, admin only) → Module Store.
2. Use the type filter (All / Modules / Themes) — theme entries carry a Theme badge.
3. Click Install. Themes always install live: no restart, ever — the theme is selectable immediately.

After an install the Module Manager shows a banner reminding you that a theme does nothing until it is selected, with a direct link to Settings → Design.

Installed themes appear as cards in the Module Manager's installed view, under Theme Packs, with the same version/trust badges as modules, a preview image (if the theme ships one), a Set as default button and Uninstall (also live, no restart).

Manual install: drop a theme folder (containing a theme.json) into the theme folder shown in the store settings (~/.mediaforge/themes/ by default). It shows up on the next page load.

Choosing a theme

Selection is two-layered, under Settings → Design → Theme Packs:

Setting	Who	Scope
Instance default	Admin	Every user, every device — including the login page
Your theme	Every user	Stored on your account — it follows you to every browser and device you log in from

Your theme, the dark/light mode and the accent colour are saved to your account (/api/user/preferences) and rendered server-side into every page, so the correct look is there on the very first paint — no flash of the wrong theme, and nothing lost when a browser cache is cleared. The browser keeps a mirror copy, which is what the login page and an offline PWA start fall back to.

A user's choice wins over the instance default. If a chosen theme is uninstalled later, that choice silently falls back to the instance default. The dark/light switch keeps working inside a theme — themes provide overrides for both modes, and anything a theme does not override falls back to MediaForge's built-in look.

Trust & safety

Theme packages go through the same pipeline as modules: checksum verification, Ed25519 signature verification against the keys compiled into the build, and the Official / Verified / Unverified tiers (see Modules for the tier table). Unverified themes require the same "Allow unverified" opt-in.

On top of that, themes are validated for content: only CSS, fonts, images and text files are allowed. A package containing .js, .html or .py files refuses to install, and a hand-copied folder containing them is listed as Invalid and never served.

Making your own

A complete, commented example lives in the repository under .examples/themes/example_theme/ — manifest format, the token layer (overriding variables.css custom properties per [data-theme]), component restyling (.chb-main checkboxes, inputs, calendar, buttons), custom @keyframes animations, bundled fonts and preview images, plus how to publish to a store ("type": "template" in the index entry; "theme" is accepted as an alias).