Theme

A theme is a collection of settings that define the overall look and feel of your rice. Themes combine your palette, style, wallpaper, and more, and are the main way to switch between different desktop appearances.

Themes are stored in PIMP_CONFIG_DIR/themes/THEME_NAME/theme.json and can be easily created, edited, and shared.

Directory structure

Here's what a theme directory looks like:

themes/
└── my_theme/
    ├── theme.json
    └── wallpaper.png

You can edit the current theme with:

pimp theme edit

Or a specific theme:

pimp theme edit THEME_NAME

Theme structure

A theme is composed of:

Wallpaper
Modes (e.g. dark, light)
Style (optional)
Tags (optional)

All of this is configured in a theme.json file:

theme.json

{
    "wallpaper": {
        "path": "example.png"
    },
    "modes": {
        "dark": {
            "palette": {
                "term": { ... },
                "normal": { ... },
                "primary": { ... },
                "secondary": { ... }
            },
            "wallpaper": { ... },
            "style": { ... }
        },
        "light": { ... }
    },
    "style": {
        "bar": { "bg": "transparent" },
        "blur": { "enabled": false }
    },
    "tags": ["chill", "dim"],
    "$schema": "../../.json_schemas/theme.json"
}

Wallpaper

The wallpaper field sets the background image for your theme. You can specify a mode (e.g. fill, fit), which defaults to fill if omitted.

"wallpaper": {
    "path": "example.png",
    "mode": "fit" // optional
}

Modes

A theme can have multiple modes (e.g. dark, light). Each mode can have its own palette, wallpaper, and style.

A mode is composed of:

Palette
Wallpaper (optional)
Style (optional)

Example:

theme.json

"modes": {
    "dark": {
        "wallpaper": "dark_wp.jpg",
        "style": {
            "opacity": { "terminal": 0.93 }
        },
        "palette": { ... }
    },
    ...
}

You can reference a global palette using from_global:

"palette": {
    "from_global": "catppuccin_dark"
}

Or define a palette inline:

"palette": {
    "term": { ... },
    "normal": { ... },
    "primary": { ... },
    "secondary": { ... }
}

Style

The style field lets you override or extend the base style for the whole theme or for a specific mode. You can also inherit from a global style using from_global:

"style": {
    "from_global": "flat",
    "bar": { "bg": "transparent" }
}

Schema validation & autocomplete

Each theme.json includes a $schema field for JSON schema validation and editor autocomplete. This helps you write correct themes and get suggestions in supported editors.

Tips & Tricks

Use global palettes and global styles to keep your themes DRY and consistent.
You can override any field at the theme or mode level.
Use tags to organize your themes and make random selection more fun.
See the theme_dict page for how everything is merged and passed to modules.

On this page