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

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 (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. The resolveThemes() function in 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 (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 (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 (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 (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:

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:

/* 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 (lines 71-76):

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 (lines 56-66) downloads the latest release ZIP and extracts it into your local themes folder:

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

{
  "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
• Discovery: resolveThemes() in 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 handling DOM injection
• Persistence: Selected themes are stored in settings.theme per the schema in 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. 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}