Theme structure

Understanding theme file structure and advanced features

BetterDiscord themes follow a specific structure to ensure proper loading and functionality.

Basic structure

A theme file consists of two main parts:

1. Metadata block - JSDoc comment with theme information
2. CSS content - Your actual styles

/**
 * @name Example Theme
 * @author YourName
 * @version 1.0.0
 * @description A beautiful theme for Discord
 */

/* Your CSS styles go here */
:root {
  --custom-variable: #ff0000;
}

.theme-dark {
  --background-primary: var(--custom-variable);
}

File naming

Themes must use the .theme.css extension:

• ✅ MyTheme.theme.css
• ✅ dark-mode.theme.css
• ❌ MyTheme.css - Will not be recognized
• ❌ MyTheme.theme.txt - Wrong extension

BetterDiscord automatically handles duplicate file names by renaming them (e.g., MyTheme (1).theme.css).

Metadata format

The metadata block uses JSDoc syntax and must appear at the very beginning of the file:

/**
 * @name Theme Name
 * @author Author Name
 * @version 1.0.0
 * @description Theme description here
 * @source https://github.com/user/repo
 * @website https://example.com
 * @donate https://ko-fi.com/username
 * @patreon https://patreon.com/username
 * @invite abc123
 * @authorId 123456789012345678
 * @authorLink https://example.com/profile
 */

Required fields

These fields are required for a valid theme:

• @name - Theme display name
• @author - Your name or username
• @version - Semantic version number
• @description - Brief description of the theme

Optional fields

These fields provide additional information:

• @source - GitHub or GitLab repository URL
• @website - Theme homepage or documentation
• @invite - Discord server invite for support
• @donate - Donation link (Ko-fi, PayPal, etc.)
• @patreon - Patreon page
• @authorId - Your Discord user ID
• @authorLink - Personal website or portfolio

Custom properties

Themes can define custom CSS properties that BetterDiscord recognizes for advanced configuration:

/**
 * @name Advanced Theme
 * @author YourName
 * @version 1.0.0
 * @description Theme with custom properties
 */

@property --accent-color {
  syntax: "<color>";
  inherits: true;
  initial-value: #7289da;
}

@property --background-blur {
  syntax: "<length>";
  inherits: false;
  initial-value: 10px;
}

:root {
  --accent-color: #ff6b6b;
  --background-blur: 15px;
}

These properties are automatically extracted and can be used for theme configuration in future BetterDiscord versions.

File organization

For complex themes, consider organizing your code:

/**
 * Theme metadata
 */

/* ==================== Variables ==================== */
:root {
  /* Colors */
  --accent-primary: #7289da;
  --accent-secondary: #5865f2;
  
  /* Spacing */
  --spacing-small: 4px;
  --spacing-medium: 8px;
  --spacing-large: 16px;
}

/* ==================== Base Styles ==================== */
.theme-dark {
  --background-primary: #1a1a1a;
  --background-secondary: #0f0f0f;
}

/* ==================== Components ==================== */

/* Messages */
[class*="message_"] {
  /* styles */
}

/* Channels */
[class*="channel_"] {
  /* styles */
}

/* Modals */
[class*="modal_"] {
  /* styles */
}

/* ==================== Animations ==================== */
@keyframes fadeIn {
  from { opacity: 0; }
  to { opacity: 1; }
}

Theme imports

You can import external stylesheets, but use caution as they may fail if the external source is unavailable:

/**
 * @name Theme with Imports
 * @author YourName
 * @version 1.0.0
 * @description Theme using external resources
 */

@import url("https://fonts.googleapis.com/css2?family=Roboto&display=swap");

:root {
  font-family: 'Roboto', sans-serif;
}

External imports can slow down theme loading and may break if the external resource is unavailable. Consider embedding critical styles directly in your theme.

Theme loading process

Understanding how BetterDiscord loads themes helps you debug issues:

1. File detection - BetterDiscord scans the themes folder for .theme.css files
2. Metadata parsing - Extracts the JSDoc metadata block
3. Validation - Ensures required fields (name, author, version, description) are present
4. CSS extraction - Reads the CSS content after the metadata
5. Property extraction - Identifies @property declarations for future use
6. Injection - Injects the CSS into a <style> element in the <head>

The theme is injected into an element with ID {slug}-theme-container, where slug is the filename without the extension and spaces replaced with hyphens.

Error handling

If your theme fails to load, check for:

• Missing or incomplete metadata block
• Invalid JSDoc syntax
• Missing required fields
• UTF-8 BOM (Byte Order Mark) at file start - BetterDiscord strips this automatically

Hot reload

BetterDiscord watches theme files for changes:

// When a file changes:
// 1. Reads the new content
// 2. Re-parses metadata and CSS
// 3. Updates the injected style element
// 4. No restart required

This allows real-time theme development - save your file and see changes instantly.

Next steps

Styling guide

Learn about Discord’s CSS variables and selectors

Best practices

Follow guidelines for high-quality themes