BetterCurseForge/docs/guide/themes.md

Themes

BetterCurseForge can load custom themes and reload them live. A theme is a CSS file, optionally with a JSON manifest, and it appears in CurseForge's own theme settings.

---

Picking a theme

Client themes are added to CurseForge's own Settings -> Themes page.

Finding client themes

1. Open CurseForge.
2. Click the Settings gear icon in the bottom-left corner.
3. Choose Themes in the settings sidebar.
4. Scroll past the Classic, Colorblind and Premium categories to reach Client Themes:

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

What the theme page does

• Hover preview: Hover over a theme card to preview it across the whole launcher. Move the cursor away to revert, or click to apply it.
• One theme at a time: Picking a client theme deselects any native skin, and the other way around.
• Open Folder button: Opens your themes folder in Explorer so you can drop in new stylesheets.
• Refresh button: Reloads your custom themes from disk, no restart needed.
• Premium themes unlocked: The official Premium themes (Pixelforge, Lifeforge, Fantasyforge and Spookyforge) are unlocked and free to use.

---

Theme folder

Themes live in your user application data directory:

%APPDATA%\CurseForge\BetterCurseForge\themes\

Full path:

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

The Open Folder button in Settings -> Themes opens it for you.

---

Theme layout

There are two ways to lay out a theme:

1. Single file (recommended)

Put a .css file in themes/, with an optional .json manifest next to it:

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

2. Folder

Make a folder inside themes/ containing theme.css and theme.json:

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

---

Manifest (theme.json)

The manifest holds the theme's metadata and the colors of the small preview card shown in Settings -> Themes:

{
  "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"
}

Fields

Field	Type	Description
name	string	Name shown on the theme card and in settings.
version	string	Semantic version (e.g. 1.0.0).
description	string	Short description, shown as a tooltip when you hover the title.
author	string	Author name or handle.
primaryColor	string	Hex color of the square icon on the preview card.
titleColor	string	Hex color of the top bar on the preview card.
bodyColor	string	Hex color of the lower text bar on the preview card.
backgroundColor	string	Hex background color of the preview card.

---

CSS variables

CurseForge is styled with CSS custom properties. Overriding them lets you theme most of the app without touching individual class names.

Brand & accents

Variable	Description
--surface-brand-brand	Main 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 app background (content views, modpack library).
--surface-base	Darkest background layer (scroll tracks, container bases).
--surface-primary	Raised surface (sidebars, sub-panels).
--surface-secondary	Second surface layer (navigation menus, dialog panels).
--surface-tertiery	Third surface layer (mod cards, list row containers).
--surface-on-surface	Faint translucent overlay for buttons (rgba(...)).
--surface-on-surface-hover	Translucent hover overlay for buttons.

Modpack & library cards

Variable	Description
--surface-card	Base background of modpack and project cards.
--surface-card-hover	Background when hovering over a modpack card.
--color-surface-card-active	Active or clicked state of a card.

Typography & text

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

Title bar & navigation

Variable	Description
--title-bar-background	Background color or gradient of the window title bar.
--btn-window-action	Icons on the minimize, maximize and close buttons.
--color-scrollbar-thumb	Scrollbar thumb color.

---

Example: Emerald Night

A full working theme. Save the stylesheet as emerald-night.css and the manifest as emerald-night.json:

::: 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"
}

:::

---

Inspecting elements

CurseForge is an Electron and React app, so you can inspect its UI with Chromium DevTools:

1. Press Ctrl + Shift + I in CurseForge to open DevTools.
2. Press Ctrl + Shift + C to turn on the element inspector.
3. Click a button, banner, header or list item to see its computed styles and classes in the Elements panel.
4. Try CSS changes in the Styles tab before adding them to your theme.
5. In Settings -> Themes, click Refresh to load your updated stylesheet.