Tangerine UI is a vibrant custom theme for Mastodon's Web UI, available in four variants: 🍊 Tangerine, 🪻 Purple, 🍒 Cherry, and 🐠 Lagoon.

🕹️ Live demo @ nileane.fr • 👋 Follow Tangerine UI on Mastodon • 📝 Release notes

1. Table of contents

1. Table of contents
2. Overview
   2.a Variants
   2.b Features
   2.c List of instances that use Tangerine UI
3. Compatibility
4. Installation for Mastodon instance admins
   4.a Install as an optional theme on your instance [Recommended]
   4.b Install as the only theme on your instance
5. Installation for regular users
6. Accessibility
7. Credits
8. Support this project <3

2. Overview

2.a Variants

🍊 Tangerine
Default variant for Tangerine UI, featuring a soft orange palette.

 

🪻 Purple
For those of you who like Tangerine UI but want to stick to Mastodon's purple hue.

 

🍒 Cherry
I won't be held responsible if you end up licking your screen because of this one.

 

🐠 Lagoon
Soft turquoise palette that gives neon vibes at night.

 

2.b Features

🧑‍🔬 Support for the advanced web interface
All variants of Tangerine UI support Mastodon's multi-column layout.

🚀 Playful animations
The rocket flies!

🌚 Dark mode
Tangerine UI automatically switches from light to dark mode based on your system or browser preference.¹

💬 Distinct look for DMs
It can be easy to mistake a DM for a regular post on Mastodon. Tangerine UI gives DMs a specific look, so they stand out in your timeline, and you don't make any embarrassing mistakes.

👁️ Compact timeline
Avatars are aligned on the side, margins are properly reduced, and threads are easier to read.

✴️ Phosphor icons
Tangerine UI uses a selection of icons from the beautiful Phosphor icon family

🔍 Zoom on emojis
Custom emojis are great, but they may be difficult to distinguish when they are overly detailed. Tangerine UI allows you to hover and pause over an emoji to enlarge it.

✳️ and more
Tangerine UI was designed with care and great attention to detail. Feel free to explore all the changes it brings to Mastodon's UI, and feel free to message me if you ever have any feedback to share or bugs to report. :)

2.c List of instances that use Tangerine UI

This is a list of known Mastodon instances on which Tangerine UI has been installed, either as the only theme or as an optional theme.²

Instance	User count	Installed as...	Default theme?
hachyderm.io	8.5K+	an optional theme	No
piaille.fr	8.5K+	an optional theme	No
social.vivaldi.net	7K+	an optional theme	No
norden.social	3K+	an optional theme	No
wxw.moe	3K+	an optional theme	No
c.im	2K+	an optional theme	No
ani.work	2K+	an optional theme	Yes (Cherry variant)
masto.es	1.5K+	an optional theme	No
eldritch.cafe	1K+	an optional theme	No
framapiaf.org	1K+	an optional theme	No
social.lol	850+	an optional theme	Yes (Tangerine variant)
tool.wales	650+	an optional theme	Yes (Tangerine variant)
shelter.moe	300+	an optional theme	Yes (Tangerine variant)
vmst.io	250+	an optional theme	No
mountains.social	150+	an optional theme	No
tooter.social	150+	an optional theme	No
c7.io	100+	an optional theme	Yes (Tangerine variant)
convo.casa	100+	an optional theme	No
dmv.community	100+	an optional theme	No
mastodon.com.pl	100+	an optional theme	No
town.voyager.blue	100+	an optional theme	Yes (Custom variant)
pipou.academy	80+	an optional theme	No
duk.space	80+	an optional theme	No
pointless.chat	70+	an optional theme	Yes (Tangerine variant)
toki.social	70+	an optional theme	No
bolha.one	60+	an optional theme	Yes (Tangerine variant)
indiepocalypse.social	50+	an optional theme	No
acg.mn	30+	an optional theme	No
yttrx.com	30+	an optional theme	Yes (Lagoon variant)
asso.lgbt	20+	the only theme	Yes (Cherry variant)
zeppelin.flights	20+	the only theme	Yes (Tangerine variant)
fedinerds.social	10+	an optional theme	No
i1.no	10+	the only theme	Yes (Lagoon variant)
ngmx.com	10+	an optional theme	No
varese.social	10+	an optional theme	No
catharsis.cafe	5+	an optional theme	Yes (Tangerine variant)
erica.moe	5+	an optional theme	Yes (Purple variant)
nileane.fr	5+	the only theme	Yes (Tangerine variant)
social.nah.re	5+	an optional theme	No
m.somincola.org	5+	an optional theme	Yes (Purple variant)
fedi.cyberwitches.club	1+	the only theme	Yes (Cherry variant)
e5n.cc	1+	an optional theme	No
isfeeling.social	1+	the only theme	Yes (Purple variant)
mastodon.projetretro.io	1+	an optional theme	No

3. Compatibility

✅ Tangerine UI is compatible with instances running the latest stable release of Mastodon (currently Mastodon 4.5.3)³⁴

⚠️ The following versions of Mastodon are not supported and may only be compatible with Tangerine UI Legacy (v1.9)⁵⁶:

• 4.2.x
• 4.1.x

🚫 The following versions of Mastodon are not supported:

• 4.4.x
• 4.3.x
• 4.0.x and older

4. Installation for Mastodon admins

There are two ways to install Tangerine UI on your Mastodon instance:

• as an optional theme [Recommended]
• as the only theme

4.a Install Tangerine UI as an optional theme on your instance [Recommended]:

Follow these instructions to install Tangerine UI as an optional theme on your Mastodon instance.
Your users will be able to select Tangerine UI in their Appearance settings on the web.
You will also be able to set Tangerine UI as the default theme for everyone on your instance, including logged out visitors.

⚙️ Install (using the included script)

A basic installation script is included in this repository.
It can be used to install Tangerine UI on your Mastodon instance for the first time, and to automate the process of updating Tangerine UI.

Run the following commands as the mastodon user to install Tangerine UI using the included script:

1. Clone the Tangerine UI repository

git clone https://github.com/nileane/TangerineUI-for-Mastodon.git ./TangerineUI
cd TangerineUI

2. Copy the sample install script.

cp install.sh.sample install.sh

Make sure the Mastodon and Tangerine UI directory paths at the top of install.sh are correct:

• Edit the line beginning with TANGERINEUI= to adjust the path to the Tangerine UI directory.
• Edit the line beginning with MASTODON= to adjust the path to your Mastodon installation directory.

3. Run the install script.

./install.sh

Alternatively:

• Run with --skip-confirm to bypass all confirmation prompts:

./install.sh --skip-confirm

• Run with --main if you wish to install by pulling from the latest commits on the main branch.
  (By default, the script will install the latest stable release of Tangerine UI.)

./install.sh --main

4. Restart your Mastodon instance for the changes to take effect.

Your users should now be able to choose 'Tangerine UI', 'Tangerine UI (Purple)', 'Tangerine UI (Cherry)', or 'Tangerine UI (Lagoon)' as their site theme:

As an admin, you should also now be able to set Tangerine UI as the default theme for your instance (navigate to https://domain/admin/settings/appearance):

⚙️ Install manually

1. Clone the Tangerine UI repository, and fetch the latest stable release of Tangerine UI:

git clone https://github.com/nileane/TangerineUI-for-Mastodon.git ./TangerineUI
cd TangerineUI
git checkout $(git describe --tags $(git rev-list --tags --max-count=1))

2. Copy the files from mastodon/app/javascript/styles/ in the Tangerine UI repository to your Mastodon themes directory app/javascript/styles/:

# Replace $LIVE with the path to your Mastodon installation.
cp -r ./mastodon/app/javascript/styles/* $LIVE/app/javascript/styles

3. Add localized names. Copy the provided file located under mastodon/config/locales/tangerineui.yml in the Tangerine UI repository to your Mastodon locales directory. This will add localized names in a selection of languages for each variant of Tangerine UI.⁷

# Replace $LIVE with the path to your Mastodon installation.
cp -r ./mastodon/config/locales/tangerineui.yml $LIVE/config/locales

4. Add Tangerine UI to themes.yml. So that Tangerine UI can be selected as an available option in your users' settings, you need to edit the themes.yml file located in your Mastodon installation under config/themes.yml. In this file, add 4 new lines, one for each variant of Tangerine UI, as follows:

default: styles/application.scss
contrast: styles/contrast.scss
mastodon-light: styles/mastodon-light.scss
tangerineui: styles/tangerineui.scss
tangerineui-purple: styles/tangerineui-purple.scss
tangerineui-cherry: styles/tangerineui-cherry.scss
tangerineui-lagoon: styles/tangerineui-lagoon.scss

5. Compile assets:

# Replace $LIVE with the path to your Mastodon installation.
cd $LIVE
RAILS_ENV=production bundle exec rails assets:precompile

6. Restart your Mastodon instance for the changes to take effect.

Your users should now be able to choose 'Tangerine UI', 'Tangerine UI (Purple)', 'Tangerine UI (Cherry)', or 'Tangerine UI (Lagoon)' as their site theme:

As an admin, you should also now be able to set Tangerine UI as the default theme for your instance (navigate to https://domain/admin/settings/appearance):

⚙️ Install on a Glitch-soc instance

Tangerine UI does not yet support Glitch-soc's features and layout, but it can still be installed as a vanilla skin on your Glitch-soc instance:

1. Clone the Tangerine UI repository, and fetch the latest stable release of Tangerine UI:

git clone https://github.com/nileane/TangerineUI-for-Mastodon.git ./TangerineUI
cd TangerineUI
git checkout $(git describe --tags $(git rev-list --tags --max-count=1))

1. Copy the files from mastodon/app/javascript/styles/ in this repository to your Mastodon themes directory app/javascript/styles/:

# Replace $LIVE with the path to your Mastodon Glitch-soc installation.
cp -r ./mastodon/app/javascript/styles/* $LIVE/app/javascript/styles

2. Copy the files from mastodon/app/javascript/skins/vanilla/ in this repository to your Glitch-soc skins directory app/javascript/skins/vanilla/:

# Replace $LIVE with the path to your Mastodon Glitch-soc installation.
cp -r ./mastodon/app/javascript/skins/vanilla/* $LIVE/app/javascript/skins/vanilla

3. Compile assets:

RAILS_ENV=production bundle exec rails assets:precompile

5. Restart your instance for the changes to take effect.

Your users should now be able to select Tangerine UI as a theme in their settings, under Flavours → Vanilla Mastodon → Skin

4.b Install Tangerine UI as the only theme on your instance:

1. Check your Mastodon version. For Tangerine UI to work properly, you need to make sure Tangerine UI is compatible with your Mastodon instance. Please refer to the Compatibility section in this document before you proceed.

2. Copy & paste the contents of 🍊 TangerineUI.css to the 'Custom CSS' field in the administration panel on your Mastodon instance (Navigate to https://domain/admin/settings/appearance).

   • 🪻 For the Purple variant, copy the contents of TangerineUI-purple.css instead.
   • 🍒 For the Cherry variant, copy the contents of TangerineUI-cherry.css instead.
   • 🐠 For the Lagoon variant, copy the contents of TangerineUI-lagoon.css instead.

Warning

Using the 'Custom CSS' field to apply Tangerine UI will prevent all users on your instance from being able to choose another theme in their Appearance settings (see Accessibility).
Please make sure there is a consensus among your users for doing so. If not, scroll back to the previous section (4.a) on how to install Tangerine UI as an optional theme for your users.

5. Installation for regular users

Even if you are not an admin on your instance, you can still use Tangerine UI with a browser extension:

1. Check your Mastodon version. For Tangerine UI to work properly, you need to make sure Tangerine UI is compatible with your Mastodon instance. Please refer to the Compatibility section in this document before you proceed.
2. Install a browser extension that allows you to inject CSS on a webpage, such as Stylus, or Live CSS Editor
3. Copy & paste the contents of 🍊 TangerineUI.css to the extension's editor
   • 🪻 For the Purple variant, copy the contents of TangerineUI-purple.css instead.
   • 🍒 For the Cherry variant, copy the contents of TangerineUI-cherry.css instead.
   • 🐠 For the Lagoon variant, copy the contents of TangerineUI-lagoon.css instead.

Important

If you are a user on a Glitch-soc instance, you must switch to the Vanilla Mastodon flavour for Tangerine UI to work properly: in your instance settings, navigate to Flavours → Vanilla Mastodon → select the 'Default' skin.

Note

Alternatively, if you wish to use a JavaScript browser extension, @Write has written a ready-to-use UserScript to load Tangerine UI on any Mastodon instance. Check out the TangerineUI-Userscript repository for instructions.

6. Accessibility

Please consider that some of your users may depend on Mastodon's High Contrast theme before setting Tangerine UI as the only theme on your instance. For this reason, unless you're running a single-user instance, I strongly recommend installing Tangerine UI as an optional/revertable theme instead.

7. Credits

The logo for Tangerine UI was originally designed by Younis @younishd. 🍊

8. Support this project <3

If you enjoy Tangerine UI, I would really appreciate a tip 💛!

Footnotes

1. Tangerine UI uses the prefers-color-scheme CSS media feature to detect if you have requested a light or dark theme through an operating system setting or a user agent setting. ↩

2. If you're an admin and have installed Tangerine UI on your instance, feel free to add yours to this list. (Make a Pull Request, or just DM me) ↩

3. Tangerine UI (v2.x) is also compatible with instances running a version of Glitch-soc based on the current stable release of Mastodon, as long as it is installed as a vanilla theme on these instances. ↩

4. As a result, instances running on nightly/alpha/beta builds of Mastodon are not supported. If you do use Tangerine UI with an unstable version of Mastodon, feel free to report UI issues as they appear. ↩

5. The advanced web interface (multi-column layout) is not supported by Tangerine UI Legacy (v1.9) and will fall back to Mastodon's default appearance if enabled. ↩

6. The Cherry variant is not available with Tangerine UI Legacy (v1.9). ↩

7. Mastodon will fallback to the English names for non-included locales. ↩