pyqt-styling
Use when styling PyQt/PySide6 widgets with QSS - selectors and pseudo-states, stylesheet application, common style properties, widget-specific styling, or building a dark theme
How do I install this agent skill?
npx skills add https://github.com/codeatcode/oss-ai-skills --skill pyqt-stylingIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides documentation and code examples for styling PyQt and PySide6 applications using Qt Style Sheets (QSS). It contains no executable risks, data access, or network operations.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Objective: Use this skill to prevent cross-platform rendering bugs and style inconsistencies by enforcing QSS-specific syntax, platform-aware theming, and proper cascade discipline.
PyQt Styling - QSS (Qt Style Sheets)
QSS (Qt Style Sheets) is Qt's styling system. It resembles CSS but has critical differences that cause cross-platform bugs.
QSS Is Not CSS
QSS shares CSS syntax but differs in supported selectors, properties, and cascade behavior. These differences are the source of most cross-platform bugs.
Unsupported or Different Selectors
| Selector | CSS | QSS |
|---|---|---|
::pseudo-element | Supported (e.g., ::before, ::after) | Limited support - only Qt-specific pseudo-elements like ::indicator, ::drop-down, ::item |
Descendant selector (A B) | Matches nested elements | Does not work in most widgets - Qt uses parent-to-child cascade instead |
Child selector (A > B) | Matches direct children | Partially supported, but widget hierarchy matters more than DOM-like nesting |
Sibling selector (A + B, A ~ B) | Supported | Not supported - widgets don't have sibling relationships like DOM |
Attribute selectors ([attr]) | Full support | Supported via setProperty() but syntax differs ([attr="value"] works) |
Class selector (.my-class) | Supported | Not supported - use objectName or custom properties instead |
Properties Qt Ignores
Qt silently ignores CSS properties it doesn't implement:
box-shadow- Qt uses custom properties orqproperty-prefix insteadtext-shadow- Not implementedfilter- Not implemented (useQGraphicsEffectinstead)transform- Not implemented (use widget geometry methods)position: absolute/fixed- Qt uses layouts or manual geometrydisplay: flex/grid- Qt uses QLayout classes, not CSS display::before,::after- Not supported (use child widgets instead)
Border-Radius Clipping Issue
border-radius on a parent widget does not clip child widgets unless the parent sets a mask:
# Bad - children overflow rounded corners
parent.setStyleSheet("border-radius: 10px;")
parent.addWidget(child) # child shows outside rounded area
# Good - use a mask
from PySide6.QtGui import QRegion
from PySide6.QtCore import QRect
parent.setMask(QRegion(QRect(0, 0, parent.width(), parent.height()), QRegion.Ellipse))
# Or use a custom paintEvent for rounded rectangle mask
Cascade Behavior
Widgets cascade styles from parent to child differently from the DOM:
- DOM: Styles cascade through the document tree based on selector specificity
- Qt: Styles applied to a parent widget propagate to children only if the child has no explicit stylesheet
- Key difference: Setting
app.setStyleSheet()applies globally, butparent.setStyleSheet()only affects children that don't have their own stylesheet set
# Bad - child overrides parent
app.setStyleSheet("QPushButton { background: blue; }")
child_button.setStyleSheet("") # Empty string clears inherited style
# Good - use custom properties for theming
app.setStyleSheet("QPushButton { background: $primary-color; }")
child_button.setProperty("primary-color", "#0078d4")
child_button.style().polish(child_button)
Platform Differences
The same QSS renders differently across Windows, macOS, and Linux due to native widget rendering.
Default Widget Metrics
- Font sizes: macOS uses larger default fonts; Windows uses smaller
- Padding: Native look varies - macOS buttons have more padding, Windows has less
- Line heights: Not consistent across platforms
Fix: Use explicit min-height, padding on critical widgets rather than relying on defaults.
Native-Appearance Opt-Out
Qt widgets may render with native platform styling that ignores QSS:
# Force QSS rendering on Windows/macOS
widget.setAttribute(Qt.WidgetAttribute.WA_StyleSheet)
# For QComboBox dropdown - native rendering ignores QSS
combo.setStyleSheet("QComboBox::drop-down { border: none; }")
combo.view().setAttribute(Qt.WidgetAttribute.WA_StyleSheet)
High-DPI Scaling
QSS uses device-independent pixels, but scaling behavior varies:
# Set high-DPI scaling policy (Qt 6)
from PySide6.QtWidgets import QApplication
from PySide6.QtCore import Qt
app = QApplication(sys.argv)
app.setHighDpiScaleFactorRoundingPolicy(
Qt.HighDpiScaleFactorRoundingPolicy.PassThrough
)
Verification on a platform you don't have: Use Qt's remote desktop or CI services (GitHub Actions with Xvfb), or test in a VM with the target OS.
Theming Discipline
Tokenize Your Theme
A theme should be a single QSS source with placeholder/palette substitution, not per-widget stylesheets:
# Bad - per-widget stylesheets
class MainWindow(QMainWindow):
def __init__(self):
self.button1.setStyleSheet("background: #0078d4;")
self.button2.setStyleSheet("background: #0078d4;")
self.label.setStyleSheet("color: #333;")
# Good - tokenized theme
class Theme:
@staticmethod
def apply(app):
app.setStyleSheet("""
QPushButton { background-color: $primary; }
QLabel { color: $text-primary; }
""".replace("$primary", "#0078d4").replace("$text-primary", "#333"))
# Or use a palette
from PySide6.QtGui import QPalette, QColor
class Theme:
@staticmethod
def apply_dark(app):
palette = QPalette()
palette.setColor(QPalette.ColorRole.Window, QColor("#1e1e1e"))
palette.setColor(QPalette.ColorRole.WindowText, QColor("#ffffff"))
app.setPalette(palette)
Test a Theme Change Across Widget Types
Create a gallery page to verify theme changes:
class ThemeGallery(QWidget):
def __init__(self):
super().__init__()
# Create one of each widget type
self.buttons = [QPushButton(f"Button {i}") for i in range(3)]
self.inputs = [QLineEdit(f"Input {i}") for i in range(3)]
self.labels = [QLabel(f"Label {i}") for i in range(3)]
# Layout them all
# Switch themes with a button to verify consistency
When to Use Custom paintEvent/Delegates
Use custom painting instead of fighting QSS when:
- You need gradients, shadows, or complex shapes QSS can't express
- You need per-pixel control (e.g., custom progress bar animation)
- QSS performance is poor with many widgets
- You need platform-independent rendering (QSS varies by platform)
class RoundedButton(QPushButton):
def paintEvent(self, event):
painter = QPainter(self)
painter.setRenderHint(QPainter.RenderHint.Antialiasing)
# Custom rounded rectangle with gradient
gradient = QLinearGradient(0, 0, 0, self.height())
gradient.setColorAt(0, "#0078d4")
gradient.setColorAt(1, "#106ebe")
painter.setBrush(gradient)
painter.setPen(Qt.PenStyle.NoPen)
painter.drawRoundedRect(self.rect().adjusted(1, 1, -1, -1), 8, 8)
Basic Syntax (Quick Reference)
Assumes familiarity with CSS selectors and specificity. Focuses on Qt-specific syntax.
Property Support
QSS supports a subset of CSS properties. Check the official reference before using unfamiliar properties.
Selector Specificity
QSS uses similar specificity rules to CSS:
- Inline
setStyleSheet()calls have highest priority - ID selectors (
#objectName) beat class-like selectors ([property="value"]) - Element selectors (
QPushButton) have lowest priority
Applying Styles
Application-Wide
from PySide6.QtWidgets import QApplication
app = QApplication()
# Inline
app.setStyleSheet("""
QLabel { color: #333; }
QPushButton { padding: 5px 10px; }
""")
# From file
with open("style.qss", "r") as f:
app.setStyleSheet(f.read())
Widget-Specific
button = QPushButton("Styled")
button.setStyleSheet("""
QPushButton {
background-color: blue;
color: white;
border-radius: 5px;
}
QPushButton:hover {
background-color: darkblue;
}
""")
Custom Properties
# Set custom property
button = QPushButton("Primary")
button.setProperty("primary", True)
# Force style refresh
button.style().unpolish(button)
button.style().polish(button)
/* Use in QSS */
QPushButton[primary="true"] {
background-color: #0078d4;
color: white;
}
QPushButton[primary="true"]:hover {
background-color: #106ebe;
}
Widget-Specific Styles
QPushButton
QPushButton {
background-color: #0078d4;
color: white;
border: none;
border-radius: 4px;
padding: 8px 16px;
font-weight: bold;
}
QPushButton:hover {
background-color: #106ebe;
}
QPushButton:pressed {
background-color: #005a9e;
}
QPushButton:disabled {
background-color: #cccccc;
color: #666666;
}
/* Flat button */
QPushButton[flat="true"] {
background-color: transparent;
color: #0078d4;
border: 1px solid #0078d4;
}
QLineEdit
QLineEdit {
background-color: white;
border: 1px solid #cccccc;
border-radius: 4px;
padding: 4px 8px;
selection-background-color: #0078d4;
}
QLineEdit:focus {
border: 2px solid #0078d4;
}
QLineEdit:disabled {
background-color: #f5f5f5;
color: #999999;
}
/* Password field */
QLineEdit[echoMode="2"] {
lineedit-password-character: 9679; /* Unicode bullet */
}
QComboBox
QComboBox {
background-color: white;
border: 1px solid #cccccc;
border-radius: 4px;
padding: 4px 8px;
}
QComboBox:hover {
border-color: #999999;
}
QComboBox::drop-down {
border: none;
width: 24px;
}
QComboBox::down-arrow {
image: url(down_arrow.png);
width: 12px;
height: 12px;
}
/* Dropdown list */
QComboBox QAbstractItemView {
background-color: white;
border: 1px solid #cccccc;
selection-background-color: #0078d4;
}
QTabWidget
QTabWidget::pane {
border: 1px solid #cccccc;
border-radius: 4px;
}
QTabBar::tab {
background-color: #f5f5f5;
border: 1px solid #cccccc;
padding: 8px 16px;
margin-right: 2px;
}
QTabBar::tab:selected {
background-color: white;
border-bottom-color: white;
}
QTabBar::tab:hover {
background-color: #e5e5e5;
}
QScrollBar
/* Vertical scrollbar */
QScrollBar:vertical {
background-color: #f5f5f5;
width: 12px;
margin: 0;
}
QScrollBar::handle:vertical {
background-color: #cccccc;
border-radius: 6px;
min-height: 30px;
}
QScrollBar::handle:vertical:hover {
background-color: #999999;
}
QScrollBar::add-line:vertical,
QScrollBar::sub-line:vertical {
height: 0;
}
Deep Dives
- Dark Theme Example: See references/dark-theme.md for a complete VS Code-inspired dark theme stylesheet.
Best Practices
- Tokenize themes - Single QSS source with placeholder substitution, not per-widget stylesheets
- Test on all platforms - Colors, fonts, and native rendering vary significantly
- Use custom properties -
setProperty()for theme variables instead of hardcoding colors - Prefer delegates for complex rendering - Don't fight QSS for gradients, animations, or platform-independent drawing
- Verify border-radius clipping - Use masks or custom paintEvent if children must respect rounded corners
- Block signals during bulk updates -
widget.blockSignals(True)before batch changes, thenblockSignals(False)
References
- Qt Style Sheets: https://doc.qt.io/qtforpython-6/overviews/stylesheet.html (reference for QSS syntax and supported properties)
- QSS Reference: https://doc.qt.io/qtforpython-6/overviews/stylesheet-reference.html (lookup property support before using)
- Qt Examples: https://doc.qt.io/qtforpython-6/overviews/stylesheet-examples.html (see working QSS patterns)
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/codeatcode/oss-ai-skills/pyqt-styling">View pyqt-styling on skillZs</a>