# 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:

![Settings Themes View](/logo.svg){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:

```text
%APPDATA%\CurseForge\BetterCurseForge\themes\
```

Full path:
```text
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:

```text
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`:

```text
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:

```json
{
  "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

```css [emerald-night.css]
/* ==========================================================================
   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;
}
```

```json [emerald-night.json]
{
  "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 <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>I</kbd> in CurseForge to open DevTools.
2. Press <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>C</kbd> 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!