248 lines
8.6 KiB
Markdown
248 lines
8.6 KiB
Markdown
# 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:
|
|
|
|
```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!
|