# How to Customize PicList's Appearance with Themes: Complete Guide

> Customize PicList appearance with themes. This guide shows how to add, import, or download CSS themes for a personalized UI. Enhance your PicList experience today.

- Repository: [Kuingsmile/piclist](https://github.com/kuingsmile/piclist)
- Tags: how-to-guide
- Published: 2026-03-05

---

**Yes, PicList supports full UI customization through CSS theme files that you can add manually, import from local files, or download from the community theme hub.**

PicList is an open-source image hosting tool that allows you to personalize its interface using standard CSS files. According to the kuingsmile/piclist source code, the application implements a file-based theming system where custom styles are stored in a dedicated themes directory and applied across all renderer windows through IPC messaging.

## How PicList Theme Storage Works

### Theme Directory Location

All theme files are plain `.css` files stored in the themes directory. The location is resolved at runtime by the `themesDir()` function in **[`src/main/apis/core/datastore/dirs.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/apis/core/datastore/dirs.ts)** (lines 99-101). This ensures themes persist across application updates and remain accessible for discovery and loading.

### Default Theme Fallback

If no custom theme is selected, PicList automatically falls back to [`default.css`](https://github.com/kuingsmile/piclist/blob/main/default.css). The `resolveThemes()` function in **[`src/main/apis/app/theme/index.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/apis/app/theme/index.ts)** (lines 14-52) handles this resolution by scanning the themes folder and ensuring the default entry always exists in the available themes list.

## Theme Discovery and Selection

### Scanning CSS Files for Theme Names

When PicList builds the theme list for the Settings UI, it reads the first comment line of each CSS file to determine the display name. The comment format follows the pattern `/* Theme Name */`. The `resolveThemes()` function in **[`src/main/apis/app/theme/index.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/apis/app/theme/index.ts)** (lines 14-41) extracts these labels and returns an array of `{key, label}` objects used to populate the dropdown menu.

### Persisting Theme Settings

Your selected theme is stored in the application's configuration object under `settings.theme`. The configuration schema is defined in **[`src/renderer/utils/configPaths.ts`](https://github.com/kuingsmile/piclist/blob/main/src/renderer/utils/configPaths.ts)** (lines 88-90), ensuring your preference persists between sessions and syncs across application restarts.

## Applying Themes Across Windows

When you select a theme, the `applyTheme()` function in **[`src/main/apis/app/theme/index.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/apis/app/theme/index.ts)** (lines 84-90) executes three critical steps:

1. **Reading the CSS**: The `readTheme()` function loads the selected file content
2. **IPC Broadcasting**: A `THEME_UPDATE` message is sent to all renderer windows (settings, tray, and update windows)
3. **DOM Injection**: The preload script in **[`src/preload/index.ts`](https://github.com/kuingsmile/piclist/blob/main/src/preload/index.ts)** (lines 10-38) injects the CSS into the document and toggles the `data-theme` attribute for scoped styling

This architecture ensures consistent theming across PicList's multi-window interface.

## Adding Custom Themes to PicList

### Manual Installation

You can add themes by placing CSS files directly into the themes directory:

```typescript
import { themesDir } from '@core/datastore/dirs'
import fs from 'fs-extra'
import path from 'node:path'

// Copy your CSS file to the themes folder
const source = '/path/to/my-theme.css'
const dest = path.join(themesDir(), 'my-theme.css')
await fs.copyFile(source, dest)

```

Add a theme name comment as the first line of your CSS file:

```css
/* My Custom Theme */
body {
  background-color: #1a1a1a;
  color: #ffffff;
}

```

After placing the file, `resolveThemes()` will automatically detect it and display "My Custom Theme" in the Settings UI.

### Importing Local CSS Files

For programmatic imports, use the `importThemes()` function in **[`src/main/apis/app/theme/index.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/apis/app/theme/index.ts)** (lines 71-76):

```typescript
import { importThemes } from '~/apis/app/theme'

// Import user-selected files
await importThemes(['/path/to/theme1.css', '/path/to/theme2.css'])

```

The function copies files into the themes directory with an `imp-<random>-` prefix to prevent naming conflicts.

### Fetching Community Themes

PicList can download pre-built theme packs from the `piclist-themeHub` repository. The `fetchThemes()` function in **[`src/main/apis/app/theme/index.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/apis/app/theme/index.ts)** (lines 56-66) downloads the latest release ZIP and extracts it into your local themes folder:

```typescript
import { fetchThemes, resolveThemes } from '~/apis/app/theme'

// Download community themes
if (await fetchThemes()) {
  const availableThemes = await resolveThemes()
  console.log('Available themes:', availableThemes)
}

```

## Advanced Customization: Background Images

Beyond CSS theming, PicList supports overlaying custom background images through configuration settings. When `settings.enableCustomBgImg` is set to `true`, the preload script in **[`src/preload/index.ts`](https://github.com/kuingsmile/piclist/blob/main/src/preload/index.ts)** (lines 30-38) injects additional CSS variables on top of your selected theme:

- `--background-image`: Path to your image file
- `--background-image-opacity`: Opacity level (0.0 to 1.0)
- `--background-blur`: Blur radius in pixels

Enable this feature in your configuration:

```json
{
  "settings": {
    "theme": "my-theme.css",
    "enableCustomBgImg": true,
    "customBgImgPath": "file:///absolute/path/to/background.jpg",
    "customBgImgOpacity": "0.5",
    "customBgImgBlur": 8
  }
}

```

These variables overlay the background image while preserving your theme's color scheme and typography.

## Summary

- **Theme Location**: CSS files reside in the directory returned by `themesDir()` in [`src/main/apis/core/datastore/dirs.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/apis/core/datastore/dirs.ts)
- **Discovery**: `resolveThemes()` in [`src/main/apis/app/theme/index.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/apis/app/theme/index.ts) scans files and extracts display names from CSS comments
- **Application**: `applyTheme()` broadcasts `THEME_UPDATE` IPC messages, with [`src/preload/index.ts`](https://github.com/kuingsmile/piclist/blob/main/src/preload/index.ts) handling DOM injection
- **Persistence**: Selected themes are stored in `settings.theme` per the schema in [`src/renderer/utils/configPaths.ts`](https://github.com/kuingsmile/piclist/blob/main/src/renderer/utils/configPaths.ts)
- **Community Support**: `fetchThemes()` downloads packs from `piclist-themeHub`, while `importThemes()` handles local file imports
- **Background Images**: Enable via `settings.enableCustomBgImg` to inject overlay CSS variables

## Frequently Asked Questions

### Where are PicList themes stored?

Themes are stored as `.css` files in the themes directory, whose path is determined by the `themesDir()` function in [`src/main/apis/core/datastore/dirs.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/apis/core/datastore/dirs.ts). This location is typically within PicList's default data directory and persists across application updates.

### Can I use custom background images with themes?

Yes. Enable `settings.enableCustomBgImg` and configure `customBgImgPath`, `customBgImgOpacity`, and `customBgImgBlur`. The preload script in [`src/preload/index.ts`](https://github.com/kuingsmile/piclist/blob/main/src/preload/index.ts) injects CSS variables (`--background-image`, etc.) that overlay your image on top of the active theme CSS.

### How do I create a custom theme for PicList?

Create a standard CSS file and place it in the themes directory (or import it via the UI). Add `/* Your Theme Name */` as the first comment line—this is parsed by `resolveThemes()` for the display label. The CSS supports all standard web styling including colors, fonts, and layout modifications.

### Does PicList support community themes?

Yes. The `fetchThemes()` function in [`src/main/apis/app/theme/index.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/apis/app/theme/index.ts) downloads the latest theme pack from the `piclist-themeHub` GitHub release, extracts it into your local themes folder, and makes community-created themes available immediately in the Settings UI.