BetterCurseForge/docs/guide/themes.md

Custom Themes & Theming Guide

BetterCurseForge features a native, live-reloading theming engine. Themes allow you to completely restyle the CurseForge Launcher using standard CSS and theme manifests, fully integrated into the official user interface.

---

In-App Theme Selector

BetterCurseForge embeds client themes directly into CurseForge's native Settings -> Themes menu.

How to Access Client Themes

1. Open CurseForge Launcher.
2. Click the Settings gear icon in the bottom-left corner.
3. Select Themes from the settings sidebar.
4. Scroll down past the Classic, Colorblind, and Premium categories to find the Client Themes section:

{width=48 style="display:block;margin:1rem auto;"}

Native Features in Settings -> Themes

• Live Hover Preview: Hovering your cursor over any theme card immediately previews the theme across the entire launcher in real time. Move your cursor away to revert, or click to apply.
• Mutual Exclusivity: Selecting a client theme seamlessly deselects native skins, and vice versa. Only one theme is active at a time.
• "Open Folder" Button: Directly opens your themes folder in Windows Explorer so you can drop in new stylesheets.
• "Refresh" Button: Reloads all installed custom themes from disk instantly without needing to restart CurseForge.
• Native Premium Themes Unlocked: All official CurseForge Premium themes (Pixelforge, Lifeforge, Fantasyforge, and Spookyforge) are permanently unlocked and free to use!

---

Theme Folder Location

Themes are stored in your user application data directory:

%APPDATA%\CurseForge\BetterCurseForge\themes\

Full path:

C:\Users\<YourUsername>\AppData\Roaming\CurseForge\BetterCurseForge\themes\

You can open this folder anytime by clicking the Open Folder button in Settings -> Themes.

---

Theme File Structure

BetterCurseForge supports two convenient formats:

1. Single-File Theme (Recommended)

Place a .css file in the themes/ directory, with an optional accompanying .json manifest:

themes/
├── purple-night.css
└── purple-night.json   (optional metadata & preview colors)

2. Folder-Based Theme

Create a folder inside themes/ with a theme.css and theme.json:

themes/
└── emerald-dark/
    ├── theme.json
    ├── theme.css
    └── background.webp  (optional custom assets)

---

Theme Manifest Format (theme.json)

A .json manifest provides metadata and defines the miniature preview card colors shown in the Settings -> Themes menu:

{
  "name": "Emerald Dark",
  "version": "1.0.0",
  "description": "Deep obsidian tones with vivid emerald green accents.",
  "author": "ModderDev",
  "primaryColor": "#10b981",
  "titleColor": "#064e3b",
  "bodyColor": "#022c22",
  "backgroundColor": "#051c14"
}

Manifest Fields

Field	Type	Description
name	string	Display name shown on the theme card and in settings.
version	string	Semantic version string (e.g. 1.0.0).
description	string	Short tooltip description displayed when hovering the title.
author	string	Author name or handle.
primaryColor	string	Hex color for the primary square icon in the thumbnail card.
titleColor	string	Hex color for the top bar in the thumbnail card.
bodyColor	string	Hex color for the lower text bar in the thumbnail card.
backgroundColor	string	Hex background color for the thumbnail card itself.

---

CurseForge CSS Variables Reference

CurseForge is styled using CSS Custom Properties (variables). Overriding these variables allows you to theme 95% of the application cleanly without touching individual class names.

Brand & Accents

Variable	Description
--surface-brand-brand	Primary brand accent (active tabs, primary buttons, indicators).
--surface-brand-brand-hover	Hover state for brand-colored elements.
--color-primary	Main accent color.
--color-accent	Secondary highlight color.
--selected-item-border	Border style for selected items and active inputs.

Surfaces & Backgrounds

Variable	Description
--color-background	Main application background (content views, modpack library).
--surface-base	Darkest background layer (scroll tracks, container bases).
--surface-primary	Elevated primary surface (sidebars, sub-panels).
--surface-secondary	Secondary surface layer (navigation menus, dialog panels).
--surface-tertiery	Tertiary surface layer (mod cards, list row containers).
--surface-on-surface	Subtle translucent overlay for buttons (rgba(...)).
--surface-on-surface-hover	Translucent hover overlay for buttons.

Modpack & Library Cards

Variable	Description
--surface-card	Modpack / project card base background.
--surface-card-hover	Background color when hovering over modpack cards.
--color-surface-card-active	Active or clicked state for card items.

Typography & Text

Variable	Description
--text-pure	Pure white text (#ffffff).
--text-primary	Primary readable text color.
--color-text-title	Headings, modpack titles, section names.
--color-text-body	Standard body and description text.
--color-text-secondary	Subtitles, authors, version numbers.

Title Bar & Navigation

Variable	Description
--title-bar-background	Background color or gradient for the top window title bar.
--btn-window-action	Minimize, maximize, and close button icons.
--color-scrollbar-thumb	Scrollbar thumb handle color.

---

Example Theme: Emerald Night

Here is a complete, working theme stylesheet you can save as emerald-night.css:

::: code-group

/* ==========================================================================
   BetterCurseForge Theme: Emerald Night
   ========================================================================== */

:root,
.cf-app,
.base-skin,
.dark-skin,
.cf-classic {
  /* ── Accent & Brand ── */
  --surface-brand-brand: #10b981 !important;
  --surface-brand-brand-hover: #34d399 !important;
  --color-primary: #10b981 !important;
  --color-primary-hover: #34d399 !important;
  --color-primary-active: #059669 !important;
  --color-accent: #6ee7b7 !important;
  --selected-item-border: 2px solid #10b981 !important;

  /* ── Backgrounds & Surfaces ── */
  --color-background: #06140f !important;
  --surface-base: #030b08 !important;
  --surface-primary: #091c16 !important;
  --surface-secondary: #0d271f !important;
  --surface-tertiery: #13352b !important;
  --surface-tertiery-hover: #194639 !important;

  /* ── Modpack & Library Cards ── */
  --surface-card: #0d271f !important;
  --surface-card-hover: #14382d !important;

  /* ── Typography & Text ── */
  --text-pure: #ffffff !important;
  --text-primary: #f0fdf4 !important;
  --color-text-title: #ffffff !important;
  --color-text-body: #d1fae5 !important;
  --color-text-secondary: #6ee7b7 !important;

  /* ── Title Bar ── */
  --title-bar-background: #091c16 !important;
  --btn-window-action: #6ee7b7 !important;

  /* ── Scrollbars ── */
  --color-scrollbar-thumb: #13352b !important;
}

/* Primary Action Buttons */
.btn-primary:not(.btn-secondary),
button[class*="primary"]:not([class*="secondary"]) {
  background: #10b981 !important;
  color: #030b08 !important;
  font-weight: 600 !important;
}

.btn-primary:not(.btn-secondary):hover,
button[class*="primary"]:not([class*="secondary"]):hover {
  background: #34d399 !important;
}

{
  "name": "Emerald Night",
  "version": "1.0.0",
  "description": "Deep emerald dark theme for CurseForge Launcher.",
  "author": "BetterCurseForge",
  "primaryColor": "#10b981",
  "titleColor": "#0d271f",
  "bodyColor": "#06140f",
  "backgroundColor": "#091c16"
}

:::

---

Tips for Inspecting Elements

Because CurseForge runs on Electron and React, you can inspect any UI element using Chromium DevTools:

1. Press Ctrl + Shift + I in CurseForge to open DevTools.
2. Press Ctrl + Shift + C to activate the element inspector.
3. Click on any button, banner, header, or list item to reveal its computed styles and classes in the Elements panel.
4. Test CSS changes live in the Styles tab before adding them to your theme file.
5. In Settings -> Themes, click Refresh to instantly apply your modified theme stylesheet!