Themes

Themes

Moonbase includes a theme editor and lets admins host custom themes on the server so every Moonfin client can use them.

Picking a theme as a user

You don't need the editor to change how Moonfin looks. In any Moonfin app open Settings > Personalization > General Style:

• App Theme switches between the built-in looks (Moonfin, Neon Pulse, Glass, 8-Bit Hero) and any custom theme your server admin has uploaded.
• Theme Store lists community themes you can save and apply.
• OLED Mode turns backgrounds true black on top of whichever theme is active.

Your choice syncs to your other devices through Moonbase.

The theme editor

The editor is served at:

https://your-server-host/Moonfin/Web/theme/

It gives you a visual way to edit theme colors and tokens, preview them, and validate the result. There is also a random theme generator that builds a complete, coherent palette from a random base and accent color while keeping your theme id, name, and description. When you are happy, export the theme to a JSON file.

Making a theme, start to finish:

1. Open the editor address above in a desktop browser and sign in with your server account when asked.
2. Start from a built-in theme, or press the random generator until you like the base.
3. Give it an id, a name and a description. The id is what the apps store, so pick it once and keep it.
4. Adjust colors. The preview updates as you go.
5. Press Validate and fix anything it points out.
6. Press Export to download the JSON file, then hand it to your server admin (or upload it yourself if that's you).

Uploading a custom theme

1. Open the Moonbase plugin page on your server dashboard (Jellyfin: Dashboard > Plugins > My Plugins > Moonbase. Emby: Dashboard > Plugins > Moonbase) and open the Themes tab.
2. Under Uploaded Themes, upload your exported theme JSON.
3. The server validates it against the theme schema and stores it with metadata (display name, checksum, uploader, and upload time).

Uploaded themes are validated server-side, so a malformed theme is rejected rather than shipped to clients. Optional fields are checked too. A theme can leave one out, but if it's there with the wrong kind of value, for example text in isGlass instead of true or false, or something other than a color in colors.card, the upload is refused with an error naming that field.

Using a custom theme

Once a theme is uploaded, clients can pick it from the Settings menu in any Moonfin client. The selection is stored per user as the customThemeId setting and syncs across your devices like any other setting. See Settings Sync.

How themes reach clients

Clients connected to the live events stream get a themesChanged event whenever a theme is uploaded or removed, so new themes appear without a restart. The relevant endpoints are listed under API Reference.