How to Apply Custom CSS Themes to a Mastodon Instance

Many Mastodon instance administrators want to give their community a unique look that stands out from the default interface. The stock Mastodon theme uses a clean blue-and-white design, but it may not match your brand or personal preference. Custom CSS themes let you change colors, fonts, spacing, and layout elements across the entire web interface. This article explains how to apply custom CSS themes to a Mastodon instance using the built-in theme system and the Admin dashboard.

Overview of Mastodon Theme Customization Options

Mastodon uses a CSS framework built on top of the application styles. The default theme is called “mastodon-light” and lives in the app/javascript/styles/mastodon directory. You can modify the look of your instance in two ways: by adding custom CSS through the Admin interface, or by creating a new theme file directly in the source code.

The Admin interface method is the simplest because it does not require server file access or rebuilding assets. You paste CSS rules into a text box, and Mastodon injects them into every page. The source-code method is more powerful because you can define entirely new color palettes and layout variables. Both methods require you to understand CSS selectors used by Mastodon.

Before you start, make sure you have administrator access to your Mastodon instance. You also need a basic understanding of CSS syntax. If you plan to modify source files, you need SSH access to the server and familiarity with the command line.

Steps to Apply Custom CSS Through the Admin Dashboard

This method works for any Mastodon instance running version 3.0 or later. No file editing or server restart is required.

1. Log in as an administrator
   Use an account that has the Admin role. If you control the instance, your account is likely the first one created and has full permissions.
2. Open the Administration menu
   Click the hamburger icon in the top-left corner of the Mastodon web interface. Select Preferences from the menu. In the Preferences screen, click Administration in the left sidebar.
3. Go to Server Settings > Appearance
   Under Administration, click Server Settings. Then click the Appearance tab. This page contains fields for the site title, description, logo, and custom CSS.
4. Paste your custom CSS code
   Find the text area labeled Custom CSS. Paste your CSS rules here. For example, to change the background color of the main column, you can use:
   body { background-color: #f0f0f0; }
   You can add as many rules as you want, but keep the total size under 100 KB.
5. Save the changes
   Click the Save changes button at the bottom of the Appearance page. The new CSS takes effect immediately for all users. Refresh your browser to see the changes.

Steps to Create a New Theme in the Source Code

This method is for administrators who want to offer multiple themes to their users. It requires direct access to the Mastodon installation directory on the server.

1. SSH into your Mastodon server
   Open a terminal and connect to your server: ssh user@your-server-ip. Navigate to the Mastodon directory, typically /home/mastodon/live.
2. Create a new theme file
   Go to app/javascript/styles/mastodon. Copy the existing theme file mastodon-light.scss and rename it, for example, my-custom-theme.scss. Open the new file in a text editor like nano or vim.
3. Edit the color variables
   At the top of the SCSS file, you will find variables such as $ui-base-color, $primary-color, and $secondary-color. Change these values to your preferred colors. For example:
   $primary-color: #ff6600;
   Save the file after making changes.
4. Register the theme in the application
   Open app/lib/theme.rb or config/themes.yml depending on your Mastodon version. Add a new entry for your theme. For example:
   my_custom_theme: My Custom Theme
   Save the file.
5. Rebuild the assets
   Run the following command in the Mastodon directory:
   RAILS_ENV=production bundle exec rails assets:precompile
   This compiles the SCSS files into CSS. The process may take a few minutes.
6. Restart the Mastodon services
   Run systemctl restart mastodon-web and systemctl restart mastodon-sidekiq to apply the new theme. Users can now select your theme from Preferences > Appearance > Theme.

Common Mistakes and Things to Avoid

CSS rules not applying after saving in Admin dashboard

The most common cause is a CSS syntax error. Missing semicolons, unclosed brackets, or invalid property values can break the entire block. Use a CSS validator tool before pasting. Also, check that your selectors match Mastodon’s HTML structure. Use your browser’s developer tools (F12) to inspect elements and find the correct class or ID names.

Theme not appearing in user preferences after source-code changes

This usually happens when the theme is not properly registered in the configuration file. Verify that the key in theme.rb or themes.yml matches the filename exactly, without the .scss extension. Also, ensure you rebuilt the assets and restarted the web service. Check the server logs for compilation errors.

Custom CSS affecting only the admin view

Some CSS selectors are specific to the administration interface. To style public pages, use selectors that target the public layout, such as .public-layout or .landing-page. Test your CSS while logged out or using an incognito window to see the public experience.

Admin Dashboard CSS vs Source-Code Theme: Comparison

Item	Admin Dashboard CSS	Source-Code Theme
Setup difficulty	Low: paste and save	High: file editing and asset rebuild
Changes take effect	Immediately after save	After asset rebuild and service restart
User-selectable	No: applies to all users globally	Yes: users choose from Preferences
Requires server access	No	Yes: SSH and file permissions
CSS scope	Overrides only; limited by specificity	Full control of variables and layout

Use the Admin dashboard method for quick tweaks and branding. Use the source-code method when you need to offer multiple themes or deeply customize the design.