booru-viewer/themes

booru-viewer Theme Reference

Copy any .qss file from this folder to your data directory as custom.qss:

• Linux: ~/.local/share/booru-viewer/custom.qss
• Windows: %APPDATA%\booru-viewer\custom.qss

Restart the app after changing themes.

Recoloring a theme — @palette blocks and ${...} vars

Qt's QSS dialect has no native variables, so booru-viewer adds a small preprocessor that runs before the stylesheet is handed to Qt. Each bundled theme starts with an @palette header block listing the colors the rest of the file uses, and the body references them as ${name}:

/* @palette
   bg:             #1e1e2e
   accent:         #cba6f7
   text:           #cdd6f4
*/

QWidget {
    background-color: ${bg};
    color: ${text};
    selection-background-color: ${accent};
}

To recolor a theme, edit the @palette block at the top — that's the only place hex literals appear. The body picks up the new values automatically. Save and restart the app.

The preprocessor is opt-in: a custom.qss without an @palette block loads as plain Qt-standard QSS, so existing hand-written themes still work unchanged. Unknown ${name} references are left in place verbatim and a warning is logged so typos are visible.

Available palette slots

The bundled themes define 17 standard color slots. You can add more in your own @palette block (or remove ones you don't reference) — only slots that the body actually uses need to be defined.

Slot	Used for
bg	Window background, scroll area, menu bar
bg_alt	Alternate row stripes in lists/trees, disabled inputs
bg_subtle	Buttons and inputs at rest, dropdown panels, tooltips
bg_hover	Surfaces under cursor hover, scrollbar handles
bg_active	Surfaces while pressed, scrollbar handles on hover
text	Primary foreground text
text_dim	Secondary text — status bar, group titles, placeholders
text_disabled	Disabled control text
border	Subtle dividers between adjacent surfaces
border_strong	More visible borders, default focus rings
accent	Selection background, focused borders, checked buttons
accent_text	Foreground used on top of accent backgrounds
accent_dim	Softer accent variant for hover-on-accent surfaces
link	Hyperlinks (info panel source URL)
danger	Destructive action color (Clear All button etc.)
success	Positive action color (also Character tag default)
warning	Warning color (also Artist tag default)
overlay_bg	Translucent background for the popout's floating top toolbar and bottom transport controls. Should be rgba(...) so video shows through.

Included Themes

Each theme ships in two corner-radius variants:

• *-rounded.qss — 4px radius on buttons, inputs, dropdowns, scrollbar handles, group boxes, tabs etc. The "default" Fusion-style look.
• *-square.qss — every border-radius: declaration stripped except the one on QRadioButton::indicator, so radio buttons stay circular while everything else (buttons, inputs, scrollbars, tabs, group boxes, tooltips, progress bars, checkbox indicators) renders square.

Pick whichever matches your overall desktop aesthetic. Both variants share the same @palette block, so you can swap one for the other and your colors carry over.

Theme	Rounded	Square
Nord	nord-rounded.qss	nord-square.qss
Catppuccin Mocha	catppuccin-mocha-rounded.qss	catppuccin-mocha-square.qss
Gruvbox	gruvbox-rounded.qss	gruvbox-square.qss
Solarized Dark	solarized-dark-rounded.qss	solarized-dark-square.qss
Tokyo Night	tokyo-night-rounded.qss	tokyo-night-square.qss
Everforest	everforest-rounded.qss	everforest-square.qss

Widget Targets

Global

QWidget {
    background-color: ${bg};
    color: ${text};
    font-size: 13px;
    font-family: monospace;
    selection-background-color: ${accent};  /* grid selection border + hover highlight */
    selection-color: ${accent_text};
}

Buttons

QPushButton {
    background-color: ${bg_subtle};
    color: ${text};
    border: 1px solid ${border};
    border-radius: 4px;
    padding: 5px 14px;
}
QPushButton:hover { background-color: ${bg_hover}; }
QPushButton:pressed { background-color: ${bg_active}; }
QPushButton:checked { background-color: ${accent}; }  /* Active tab (Browse/Bookmarks/Library), Autoplay, Loop toggles */

Note: Qt's QSS does not support the CSS content property, so you cannot replace button text (e.g. swap icon symbols) via stylesheet alone. The toolbar icon buttons use hardcoded Unicode symbols — to change which symbols appear, modify the Python source directly (see preview_pane.py and popout/window.py).

Text Inputs

QLineEdit, QTextEdit {
    background-color: ${bg};
    color: ${text};
    border: 1px solid ${border};
    border-radius: 4px;
    padding: 4px 8px;
}
QLineEdit:focus, QTextEdit:focus {
    border-color: ${accent};
}

Dropdowns

QComboBox {
    background-color: ${bg_subtle};
    color: ${text};
    border: 1px solid ${border};
    border-radius: 4px;
    padding: 3px 6px;
}
QComboBox::drop-down {
    border: none;
    width: 20px;
}
QComboBox QAbstractItemView {
    background-color: ${bg_subtle};
    color: ${text};
    border: 1px solid ${border};
    selection-background-color: ${bg_hover};
}

Spin Box (Score Filter)

QSpinBox {
    background-color: ${bg_subtle};
    color: ${text};
    border: 1px solid ${border};
    border-radius: 2px;
}

Scrollbars

QScrollBar:vertical {
    background: ${bg};
    width: 10px;
    border: none;
}
QScrollBar::handle:vertical {
    background: ${bg_hover};
    border-radius: 4px;
    min-height: 20px;
}
QScrollBar::handle:vertical:hover { background: ${bg_active}; }
QScrollBar::add-line:vertical, QScrollBar::sub-line:vertical { height: 0; }

QScrollBar:horizontal {
    background: ${bg};
    height: 10px;
}
QScrollBar::handle:horizontal {
    background: ${bg_hover};
    border-radius: 4px;
}
QScrollBar::add-line:horizontal, QScrollBar::sub-line:horizontal { width: 0; }

Menu Bar & Context Menus

QMenuBar {
    background-color: ${bg};
    color: ${text};
}
QMenuBar::item:selected { background-color: ${bg_subtle}; }

QMenu {
    background-color: ${bg};
    color: ${text};
    border: 1px solid ${border};
}
QMenu::item:selected { background-color: ${bg_subtle}; }

Status Bar

QStatusBar {
    background-color: ${bg};
    color: ${text_dim};
}

Splitter Handle

QSplitter::handle {
    background: ${border};
    width: 2px;
}

Tab Bar (Settings Dialog)

QTabBar::tab {
    background: ${bg_subtle};
    color: ${text};
    border: 1px solid ${border};
    padding: 6px 16px;
}
QTabBar::tab:selected {
    background: ${bg_hover};
    color: ${accent};
}

Video Player Controls

The preview panel's video controls bar uses a translucent overlay style by default (rgba(0,0,0,160) background, white text). This is styled internally and overrides QSS for the controls bar. The seek/volume sliders and buttons inside the controls bar use a built-in dark overlay theme.

To override the preview controls bar background in QSS:

QWidget#_preview_controls {
    background: ${overlay_bg};
}

Standard slider styling still applies outside the controls bar:

QSlider::groove:horizontal {
    background: ${bg_subtle};
    height: 4px;
    border-radius: 2px;
}
QSlider::handle:horizontal {
    background: ${accent};
    width: 12px;
    margin: -4px 0;
    border-radius: 6px;
}

Popout Overlay

The popout (fullscreen preview) toolbar and video controls float over the media with a translucent background and auto-hide after 2 seconds of no mouse activity. Mouse movement or Ctrl+H toggles them.

These overlays use internal styling that overrides QSS. To customize:

/* Popout top toolbar */
QWidget#_slideshow_toolbar {
    background: ${overlay_bg};
}

/* Popout bottom video controls */
QWidget#_slideshow_controls {
    background: ${overlay_bg};
}

Buttons and labels inside both overlays inherit a white-on-transparent style. To override:

QWidget#_slideshow_toolbar QPushButton {
    border: 1px solid ${border};
    color: ${text_dim};
}
QWidget#_slideshow_controls QPushButton {
    border: 1px solid ${border};
    color: ${text_dim};
}

Preview & Popout Toolbar Icon Buttons

The preview and popout toolbars use 24x24 icon buttons with Unicode symbols. Each button has an object name for QSS targeting:

Object Name	Symbol	Action
#_tb_bookmark	☆ / ★	Bookmark / Unbookmark
#_tb_save	⤓ / ✕	Save / Unsave
#_tb_bl_tag	⊘	Blacklist a tag
#_tb_bl_post	⊗	Blacklist this post
#_tb_popout	⧉	Open popout (preview only)

/* Style all toolbar icon buttons */
QPushButton#_tb_bookmark,
QPushButton#_tb_save,
QPushButton#_tb_bl_tag,
QPushButton#_tb_bl_post,
QPushButton#_tb_popout {
    background: transparent;
    border: 1px solid ${border};
    color: ${text};
    padding: 0px;
}

The same object names are used in both the preview pane and the popout overlay, so one rule targets both. The symbols themselves are hardcoded in Python — QSS can style the buttons but cannot change which symbol is displayed.

Progress Bar (Download)

QProgressBar {
    background-color: ${bg_subtle};
    border: none;
}
QProgressBar::chunk {
    background-color: ${accent};
}

Tooltips

QToolTip {
    background-color: ${bg_subtle};
    color: ${text};
    border: 1px solid ${border};
    padding: 4px;
}

Labels

QLabel {
    background: transparent;  /* important: prevents opaque label backgrounds */
}

Rubber Band Selection

Click and drag on empty grid space to select multiple thumbnails. The rubber band uses the system's default QRubberBand style, which can be customized:

QRubberBand {
    background: ${accent};  /* use rgba(...) variant for translucency */
    border: 1px solid ${accent};
}

Library Count Label States

The library tab's count label switches between three visual states depending on what refresh() finds. The state is exposed as a Qt dynamic property libraryCountState so themes target it via attribute selectors:

QLabel[libraryCountState="empty"] {
    color: ${text_dim};        /* dim text — search miss or empty folder */
}
QLabel[libraryCountState="error"] {
    color: ${danger};          /* danger color — directory unreachable */
    font-weight: bold;
}

The normal state (N files) inherits the panel's default text color — no rule needed.

Thumbnail Indicators and Selection Colors

ThumbnailWidget {
    qproperty-savedColor: #22cc22;        /* green dot: saved to library */
    qproperty-bookmarkedColor: #ffcc00;   /* yellow star: bookmarked */
    qproperty-selectionColor: #cba6f7;    /* selected cell border (3px) */
    qproperty-multiSelectColor: #b4befe;  /* multi-select fill + border */
    qproperty-hoverColor: #cba6f7;        /* hover border (1px) */
    qproperty-idleColor: #45475a;         /* idle 1px border */
}

All four selection colors default to your system palette (Highlight + a derived idle color from Mid) so a custom.qss without these qproperties still picks up the theme. Override any of them to retint individual cell states without touching the global palette.

Info Panel Tag Categories

The tag list in the info panel groups tags by category and colors each category. Defaults follow the booru convention (Danbooru, Gelbooru, etc.) so the panel reads naturally to anyone coming from a booru site. Override any of them via qproperty-tag<Category>Color on InfoPanel:

InfoPanel {
    qproperty-tagArtistColor: #f2ac08;     /* default: orange */
    qproperty-tagCharacterColor: #00aa00;  /* default: green (booru convention) */
    qproperty-tagCopyrightColor: #cc00ff;  /* default: magenta */
    qproperty-tagSpeciesColor: #ee4444;    /* default: red */
    qproperty-tagMetaColor: #888888;       /* default: gray */
    qproperty-tagLoreColor: #888888;       /* default: gray */
}

The General category has no color override — its tags use the panel's default text color so they fall in line with the rest of the theme.

States

State	Description
:hover	Mouse over
:pressed	Mouse down
:focus	Keyboard focus
:checked	Toggle buttons (Browse/Favorites)
:selected	Selected menu item or tab
:disabled	Grayed out

Notes

• selection-background-color on QWidget controls the grid thumbnail selection border and hover highlight (lighter version auto-derived)
• Setting a custom QSS automatically switches to the Fusion Qt style for consistent rendering
• Tag category colors (Artist, Character, Copyright, Species, Meta, Lore) are QSS-controllable via qproperty-tag<Category>Color on InfoPanel — see the Info Panel Tag Categories section above
• Saved dot (green) and bookmark star (yellow) are QSS-controllable via qproperty-savedColor and qproperty-bookmarkedColor on ThumbnailWidget
• Use QLabel { background: transparent; } to prevent labels from getting opaque backgrounds