QSS Themes

QSS (Qt Style Sheet) themes use raw CSS-like syntax for full control over every widget's appearance. You can use gradients, custom borders, pseudo-states, and more.

← Back to Theme Documentation overview · JSON Themes →

Quick Start

1. Copy custom_theme.qss.demo from the themes folder to a new file (e.g., ocean.qss, midnight.qss)
2. Edit the file with your colors, borders, and styles using the syntax below
3. Save in the themes folder. The theme appears in View → Theme
4. Use View → Reload themes to pick up new or edited QSS files

Theme Folder Location

Theme files are stored in the themes folder:

• Exe installation: %LOCALAPPDATA%\LYTE\themes\
• Portable installation: themes\ (relative to application directory)

Note: %LOCALAPPDATA% typically expands to C:\Users\<YourUsername>\AppData\Local\ on Windows.

File Naming

• Theme files must end with .qss (e.g., my_theme.qss)
• The filename (without .qss) becomes the theme identifier and display name
• Example: ocean.qss appears as "Ocean", aurora_theme.qss as "Aurora Theme"
• Template: custom_theme.qss.demo (copy and rename to .qss to use)
• Showcase: aurora_theme.qss demonstrates gradients, rounded corners, and a purple/cyan palette—select "Aurora Theme" from View → Theme

Basic Structure & Syntax

QSS is similar to CSS. Use widget class names as selectors and pseudo-states for hover, pressed, disabled:

QPushButton {
    background-color: #3c463c;
    color: #dcdcdc;
    border: 1px solid #465a46;
    border-radius: 8px;
    padding: 8px 16px;
}

QPushButton:hover {
    background-color: #507850;
}

QPushButton:pressed {
    background-color: #649664;
}

QPushButton:disabled {
    background-color: #232323;
    color: gray;
}

Qt supports qlineargradient and rgba() for gradients and transparency:

QPushButton {
    background: qlineargradient(x1:0, y1:0, x2:0, y2:1,
        stop:0 #2d1b4e, stop:1 #1a1225);
    border: 2px solid #00d4aa;
}

QMenuBar::item:selected {
    background-color: rgba(0, 212, 170, 0.25);
    color: #00ffcc;
}

Widget Selectors

Use these Qt widget class names and sub-controls to target specific UI elements:

Common QSS Properties

These CSS-like properties work in QSS. See Qt documentation for the full list.

Tips

• Use custom_theme.qss.demo as a starting point—it styles all LYTE widgets
• Test :hover, :pressed, and :disabled for interactive feedback
• qlineargradient creates smooth gradients—use stop:0 and stop:1 for top-to-bottom
• rgba(r, g, b, 0.5) for semi-transparent overlays
• Keep contrast high for accessibility
• Use View → Reload themes after editing

Example QSS (Template)

The custom_theme.qss.demo template provides a complete base. Key sections:

QWidget {
    background-color: #191919;
    color: #dcdcdc;
}

QMainWindow, QDialog {
    background-color: #191919;
}

QMenuBar {
    background-color: #1e1e1e;
    color: #dcdcdc;
}

QMenuBar::item:selected {
    background-color: #507850;
}

QPushButton {
    background-color: #3c463c;
    color: #dcdcdc;
    border: 1px solid #465a46;
    border-radius: 8px;
    padding: 8px 16px;
}

QPushButton:hover {
    background-color: #507850;
}

QPushButton:pressed {
    background-color: #649664;
}

QLineEdit, QPlainTextEdit, QTextEdit, QSpinBox, QComboBox {
    background-color: #232323;
    color: #dcdcdc;
    border: 1px solid #465a46;
    border-radius: 8px;
    padding: 6px;
}

QSlider::groove:horizontal {
    background: #232323;
    height: 8px;
    border-radius: 4px;
}

QSlider::handle:horizontal {
    background: #649664;
    width: 16px;
    margin: -4px 0;
    border-radius: 8px;
}

QScrollBar:vertical {
    background: #232323;
    width: 12px;
    border-radius: 6px;
}

QScrollBar::handle:vertical {
    background: #3c463c;
    border-radius: 6px;
    min-height: 30px;
}

QListWidget::item:selected {
    background-color: #507850;
}

QCheckBox::indicator:checked {
    background-color: #649664;
}

QGroupBox {
    border: 1px solid #465a46;
    border-radius: 8px;
}

QToolTip {
    background-color: #232323;
    color: #dcdcdc;
    border: 1px solid #465a46;
    border-radius: 8px;
}

For a more dramatic example with gradients and cyan accents, see aurora_theme.qss.