A userscript to load TangerineUI Redesign for Mastodon's Web UI by @nileane — and its community fork Tangerine-Neue for Mastodon by @mattbirchler — on whichever instance you'd like!
TangerineUI by @nileane reached its end of life at version v2.5.4-EOL, supporting Mastodon up to 4.5.x. The project is no longer maintained, and the repository has been archived.
For Mastodon 4.6.x and above, @mattbirchler maintains Tangerine-Neue, a community fork that keeps the theme compatible with modern Mastodon versions and adds a new Granite theme (monochrome black-and-white, for those who prefer a neutral palette).
"Its aspirations are modest. This fork exists primarily to keep the theme working on Mastodon 4.6 and 4.7. There has been some work on adopting Mastodon's new design tokens, which should make future maintenance easier." — @mattbirchler
This userscript automatically detects your Mastodon instance version and loads the correct CSS from the appropriate repository — no manual switching needed. Just install, add your instances, pick a theme, and you're good.
Full credit for the original design and the vast majority of the work belongs to @nileane. The Tangerine-Neue fork builds on that foundation to keep things running on newer releases. This userscript merely ties it all together.
- Install a userscript manager — either ViolentMonkey or Tampermonkey
- Install a userscript manager — Userscripts (GitHub)
- Once the userscript manager is installed, click this link. Your userscript manager should offer you to install the script. On Safari, the Userscripts extension doesn't offer this automatically — you'll need to tap the extension icon to be prompted.
- After the userscript is installed, edit the script to add a
@matchrule (at the top of the file) for each Mastodon instance you want the theme enabled on. Follow the same format as the pre-configured examples. - Choose your theme by changing the
defaultThemessettings in the script:- For instances below 4.3.0 (legacy): set
legacy— onlytangerineandpurpleare available. - For instances 4.3.x to 4.5.x: set
modern—tangerine,purple,cherry, andlagoonare available. - For instances 4.6.x and above (Tangerine-Neue): set
neue—tangerine,purple,cherry,lagoon, andgraniteare available.
- For instances below 4.3.0 (legacy): set
- You can also set per-host themes in the
perHostThemesobject for more granular control per instance. - The tag variables at the top of the script point to the appropriate releases in each repository. To find available tags, check the releases page of the corresponding repo:
- ✨ Support Tangerine-Neue fork for Mastodon >= 4.6.0 ✨
- Added Granite theme support (Tangerine-Neue only)
- Updated last TangerineUI tag to v2.5.4-EOL
- Script now loads from the right repo depending on instance version:
- < 4.6.0 → nileane/TangerineUI-for-Mastodon
-
= 4.6.0 → mattbirchler/Tangerine-Neue-for-Mastodon
- Per-host config now supports three version tiers:
legacy,modern,neue - Better comments in the code to explain what does what
- Last release supporting only the original TangerineUI
- Per Host Theme support
- Handles 2.4 / 2.3 / 1.9.5 versions of TangerineUI correctly to match instance current version.
- set default TangerineUI tag to latest release: v2.3
- set default TangerineUI tag to latest release: v2.1
- fix a race condition that injected the theme before mastodon version could be detected
- "temporarily" remove the workaround that was made to avoid 'flash issues' while loading.
- Bump default tag for v2.0 of TangerineUI.
- Add support for lagoon color scheme.
- Add support for the new Cherry color scheme, only supported for versions above 4.3.0
- Since older (<= 4.3.0) instances can't have the Cherry color scheme, I had to create a new variable, hence why there's now legacyColorScheme and newColorScheme var, so you can choose which color scheme to use for the "legacy" and "new" mastodon version.
- ✨ Support Mastodon >= 4.3.0 ✨
- Dynamically loads the right CSS based on your instance version
- Loaded CSS is now minified thanks to jsdelivr
- ✨ Full support for Mastodon >= 4.1.6 ✨
- Mastodon's enhanced their CSP restriction which made the userscript not working on instance above or equals >= 4.1.6
- I was kinda scared I couldn't find a workaround that, but thankfully mastodon expose a meta header of the name "style-nonce", that you can fetch and use to inject the styling url with. This, of course, add a penalty delay before theme's injection. I'd hapilly takes PR if you find a way around that.
- Disable the script on pages not stylized by TangerineUI anyway
- Forcefully disconnect MutationObserver after 3 seconds if MutationObserver wasn't disconnect already This fix a performance issue where MutationObserver would be running indefinitely if it never detected the element
- Apply background && background-color to <body> tag yet again
- Add a configurable timeout after how much time the css applied <html> and <body> should be reverted, default to 1 second
- Now apply background color pre-emptively on either light or dark mode This fix a flashing issue on load, if the instance main's theme was set as dark mode, but the system was in light mode
- The pre-emptively color set to <html> is now dynamic, based selected theme (for light mode only, as dark mode as same color for both variants)
- Correctly set background color in dark mode to TangerineUI Color instead of pure black
- "Production ready" code
- <html> tag now injected instantly, as it doesn't require to wait for it.
- Moved from requestAnimationFrame to MutationObserver which should inject theme even faster.
- Hugely improved code's readability
- Compatible with both Firefox and Chrome
- Support Safari, even though injection is slow, limited to requestAnimationFrame API as MutationObserver doesn't work most of the time (except when cache is cleared with CMD + SHIFT + R), certainly a limitation from how Safari handle extensions. Safari extension is: https://apps.apple.com/us/app/userscripts/id1463298887 -- Mac & iOS support. It support UserStyles too, so you could just create one instead.