A live theme editor for Matomo. Control colours, typography, background image, and UI roundness — no code required.
Warning
This plugin is experimental and was coded using Claude Code. It is provided without any warranty regarding quality, stability, or performance. This is a community project and is not officially supported by Matomo.
CustomTheme gives Matomo super-administrators a complete visual editor built directly into the administration panel. Adjust your Matomo instance's look and feel to match your organisation's brand in minutes — without editing any files or writing any CSS.
All changes are applied live across the entire Matomo interface: reports, menus, widgets, dialogs, and data tables.
- 34 colour controls — brand colour, header, text, backgrounds, menus, widgets, focus rings, code blocks, links, and more
- Automatic palette generation — pick one primary colour and instantly generate a full harmonious colour palette using HSL colour theory
- Background image — upload a PNG, JPG, GIF, or WebP image; control display mode (cover / contain / repeat), overlay opacity, and blur intensity
- Typography — choose from 11 curated font stacks or upload your own custom font (WOFF2, WOFF, TTF, or OTF)
- Shape roundness — five presets from sharp corners (0 px) to pill-shaped (999 px), applied consistently to all UI elements
- Live preview — colour changes are reflected immediately in the admin interface before saving
- One-click reset — restore all Matomo defaults at any time
- All theme editor endpoints require super-administrator access
- Colour values are validated against a strict hex colour pattern before saving
- File uploads are validated by MIME type and magic bytes; SVG is intentionally blocked to prevent stored XSS
- Uploaded assets are served through an authenticated PHP proxy — files are never directly accessible from the webroot
- CSRF protection via Matomo nonce on all mutating actions
- Font-family input blocks remote loading patterns (
url(),@import,https://)
- Matomo >= 5.0
- PHP >= 8.1
- Go to Administration → Marketplace.
- Search for CustomTheme.
- Click Install and then Activate.
- Download the latest release archive from the GitHub repository.
- Extract it into your
matomo/plugins/directory so that the pathmatomo/plugins/CustomTheme/plugin.jsonexists. - Go to Administration → Plugins and activate CustomTheme.
After activation, go to Administration → System → Custom Theme.
The editor is organised into four tabs:
| Tab | What you can control |
|---|---|
| Colours | All 34 colour variables, plus one-click palette generation from a primary colour |
| Background | Upload an image, set display mode, overlay opacity, and blur |
| Typography | Font stack selection or custom font upload |
| Shape | UI roundness preset (Sharp / Slightly rounded / Medium / Rounded / Pill) |
Click Save on any tab to apply changes. Use Reset to defaults to restore the original Matomo theme.
Does this affect all users? Yes — CustomTheme applies a global theme to the entire Matomo instance. All users see the same theme. Individual users cannot override it.
Will this conflict with other theme plugins?
CustomTheme uses Matomo's Theme.configureThemeVariables event and injects a small <style> block in the page header. It should coexist with other themes, but the last plugin to apply a variable wins.
What happens if I deactivate the plugin? Matomo immediately returns to its default theme. Settings are preserved in the database — reactivating the plugin restores your custom theme.
What happens if I uninstall the plugin? All saved settings are removed along with any uploaded font or background image files.
Is the uploaded background image or font file accessible without authentication?
No. Files are stored outside the webroot in the plugin's data/ directory, which is protected by an .htaccess rule. All file serving goes through an authenticated PHP proxy action.
See CHANGELOG.md for the full version history.
GPL v3+. See LICENSE for details.
