Skip to main content
BetterDiscord themes allow you to customize Discord’s appearance using CSS. This guide will help you create your first theme.

​
Prerequisites

Before creating themes, you should have:
  • BetterDiscord installed and running
  • Basic knowledge of CSS
  • A text editor (VS Code, Sublime Text, etc.)

​
Creating your first theme

​
1. Locate the themes folder

Themes are stored in the BetterDiscord themes directory. You can access it through:
  • Settings → BetterDiscord → Themes → Open Themes Folder
  • Or navigate to the folder manually based on your OS:
    • Windows: %appdata%/BetterDiscord/themes/
    • macOS: ~/Library/Application Support/BetterDiscord/themes/
    • Linux: ~/.config/BetterDiscord/themes/

​
2. Create a theme file

Create a new file with the .theme.css extension. The extension is important - BetterDiscord only recognizes files ending with .theme.css. Example: MyTheme.theme.css

​
3. Add theme metadata

Every theme must start with a JSDoc comment block containing metadata: 
/**
 * @name My First Theme
 * @author Your Name
 * @version 1.0.0
 * @description A simple theme that changes Discord's appearance
 * @source https://github.com/yourusername/my-theme
 * @website https://yourwebsite.com
 */

​
4. Add your styles

After the metadata block, add your CSS: 
/**
 * @name My First Theme
 * @author Your Name
 * @version 1.0.0
 * @description A simple theme that changes Discord's appearance
 */

/* Change the background color */
.theme-dark {
  --background-primary: #1a1a1a;
  --background-secondary: #0f0f0f;
  --background-tertiary: #050505;
}

/* Style message bubbles */
[class*="message_"] {
  background: rgba(255, 255, 255, 0.02);
  border-radius: 8px;
  padding: 8px;
  margin: 4px 0;
}

​
5. Enable your theme

  1. Save your theme file
  2. Go to Settings → BetterDiscord → Themes
  3. Find your theme in the list and toggle it on
  4. Changes should apply immediately

​
Live reload

BetterDiscord automatically watches theme files for changes. When you save your file, the theme will reload automatically - no need to restart Discord.

​
Metadata fields

The metadata block supports these fields:
​
name
string
required
The display name of your theme
​
author
string
required
Your name or username
​
version
string
required
Version number (e.g., 1.0.0)
​
description
string
required
A brief description of what your theme does
​
source
string
URL to the source code repository
​
website
string
Your website or theme homepage
​
invite
string
Discord server invite code for support
​
donate
string
Donation link (Ko-fi, PayPal, etc.)
​
patreon
string
Patreon page URL
​
authorId
string
Your Discord user ID
​
authorLink
string
Link to your profile or portfolio

​
Next steps

Theme structure

Learn about theme file organization and advanced features

Styling guide

Discover Discord’s CSS variables and class structure

Best practices

Follow guidelines for creating high-quality themes

Custom CSS

Test CSS snippets before creating a full theme

Build docs developers (and LLMs) love

Get started for freeTalk to us