Qt Style Sheets Reference

All derivatives of QAbstractScrollArea, including QTextEdit, and QAbstractItemView (all item view classes), support scrollable backgrounds using background-attachment. Setting the background-attachment to fixed provides a background-image that does not scroll with the viewport. Setting the background-attachment to scroll, scrolls the background-image when the scroll bars move.

See Customizing QAbstractScrollArea for an example.

Warning: Make sure you define the Q_OBJECT macro for your custom widget.

The dock widget border can be styled using the border property. The ::title subcontrol can be used to customize the title bar. The close and float buttons are positioned with respect to the ::title subcontrol using the ::close-button and ::float-button respectively.

When the title bar is vertical, the :vertical pseudo class is set. In addition, depending on QDockWidget::DockWidgetFeature, the :closable, :floatable and :movable pseudo states are set.

Note: Use QMainWindow::separator to style the resize handle.

Warning: The style sheet has no effect when the QDockWidget is undocked as Qt uses native top level windows when undocked.

See Customizing QDockWidget for an example.

Since 4.3, setting a stylesheet on a QLabel automatically sets the QFrame::frameStyle property to QFrame::StyledPanel.

See Customizing QFrame for an example.

The sort indicator can be styled using the ::up-arrow and the ::down-arrow Sub-control.

See Customizing QHeaderView for an example.

The color and background of the selected item is styled using selection-color and selection-background-color respectively.

The password character can be styled using the lineedit-password-character property.

The password mask delay can be changed using the lineedit-password-mask-delay

See Customizing QLineEdit for an example.

Individual items are styled using the ::item subcontrol. In addition to the usually supported pseudo states, item subcontrol supports the :selected, :default, :exclusive and the non-exclusive pseudo states.

The indicator of checkable menu items is styled using the ::indicator subcontrol.

The separator is styled using the ::separator subcontrol.

For items with a sub menu, the arrow marks are styled using the right-arrow and left-arrow.

The scroller is styled using the ::scroller.

The tear-off is styled using the ::tearoff.

See Customizing QMenu for an example.

Since 5.15, the icon property can be set to override the button icon.

For QPushButton with a menu, the menu indicator is styled using the ::menu-indicator subcontrol. Appearance of checkable push buttons can be customized using the :open and :closed pseudo-states.

Warning: If you only set a background-color on a QPushButton, the background may not appear unless you set the border property to some value. This is because, by default, the QPushButton draws a native border which completely overlaps the background-color. For example,

QPushButton { background-color: red; border: none; }

See Customizing QPushButton for an example.

The slider can be styled using the ::handle subcontrol. Setting the min-width or min-height provides size contraints for the slider depending on the orientation.

The ::add-line subcontrol can be used to style the button to add a line. By default, the add-line subcontrol is placed in top right corner of the Border rectangle of the widget. Depending on the orientation the ::right-arrow or ::down-arrow. By default, the arrows are placed in the center of the Contents rectangle of the add-line subcontrol.

The ::sub-line subcontrol can be used to style the button to subtract a line. By default, the sub-line subcontrol is placed in bottom right corner of the Border rectangle of the widget. Depending on the orientation the ::left-arrow or ::up-arrow. By default, the arrows are placed in the center of the Contents rectangle of the sub-line subcontrol.

The ::sub-page subcontrol can be used to style the region of the slider that subtracts a page. The ::add-page subcontrol can be used to style the region of the slider that adds a page.

See Customizing QScrollBar for an example.

The groove of the slider is styled using the ::groove. The groove is positioned by default in the Contents rectangle of the widget. The thumb of the slider is styled using ::handle subcontrol. The subcontrol moves in the Contents rectangle of the groove subcontrol.

See Customizing QSlider for an example.

See Customizing QSplitter for an example.

The :top, :left, :right, :bottom pseudo states depending on the orientation of the tabs.

Overlapping tabs for the selected state are created by using negative margins or using the absolute position scheme.

The tear indicator of the QTabBar is styled using the ::tear subcontrol.

QTabBar used two QToolButtons for its scrollers that can be styled using the QTabBar QToolButton selector. To specify the width of the scroll button use the ::scroller subcontrol.

The alignment of the tabs within the QTabBar is styled using the alignment property.

Warning:

To change the position of the QTabBar within a QTabWidget, use the tab-bar subcontrol (and set subcontrol-position).

See Customizing QTabBar for an example.

The color and background of the selected item is styled using selection-color and selection-background-color respectively.

The corner widget in a QTableView is implemented as a QAbstractButton and can be styled using the "QTableView QTableCornerButton::section" selector.

Warning: If you only set a background-color on a QTableCornerButton, the background may not appear unless you set the border property to some value. This is because, by default, the QTableCornerButton draws a native border which completely overlaps the background-color.

The color of the grid can be specified using the gridline-color property.

See QAbsractScrollArea to style scrollable backgrounds.

See Customzing QTableView for an example.

The color and background of selected text is styled using selection-color and selection-background-color respectively.

See QAbsractScrollArea to style scrollable backgrounds.

The :top, :left, :right, :bottom pseudo states depending on the area in which the tool bar is grouped.

The :first, :last, :middle, :only-one pseudo states indicator the position of the tool bar within a line group (See QStyleOptionToolBar::positionWithinLine).

The separator of a QToolBar is styled using the ::separator subcontrol.

The handle (to move the toolbar) is styled using the ::handle subcontrol.

See Customizing QToolBar for an example.

The individual tabs can by styled using the ::tab subcontrol. The tabs support the :only-one, :first, :last, :middle, :previous-selected, :next-selected, :selected pseudo states.

The color and background of the selected item is styled using selection-color and selection-background-color respectively.

The selection behavior is controlled by the show-decoration-selected property.

The branches of the tree view can be styled using the ::branch subcontrol. The ::branch Sub-control supports the :open, :closed, :has-sibling and :has-children pseudo states.

Use the ::item subcontrol for more fine grained control over the items in the QTreeView.

See QAbsractScrollArea to style scrollable backgrounds.

See Customizing QTreeView for an example to style the branches.

If you subclass from QWidget, you need to provide a paintEvent for your custom QWidget as below:

void CustomWidget::paintEvent(QPaintEvent *)
{
    QStyleOption opt;
    opt.init(this);
    QPainter p(this);
    style()->drawPrimitive(QStyle::PE_Widget, &opt, &p, this);
}

The above code is a no-operation if there is no stylesheet set.

Warning: Make sure you define the Q_OBJECT macro for your custom widget.

If this property is not set, the default value is whatever is set for the palette's AlternateBase role.

Example:

QTreeView {
    alternate-background-color: blue;
    background: yellow;
}

See also background and selection-background-color.

Examples:

QLabel { background-color: yellow }
QLineEdit { background-color: rgb(255, 0, 0) }

If this property is not specified, the background image is repeated in both directions (repeat).

Example:

QFrame {
    background: white url(:/images/ring.png);
    background-repeat: repeat-y;
    background-position: left;
}

Example:

QTextEdit {
    background-image: url("leaves.png");
    background-attachment: fixed;
}

See also background

This property is supported by QAbstractItemView subclasses, QAbstractSpinBox subclasses, QCheckBox, QComboBox, QDialog, QFrame, QGroupBox, QLabel, QPushButton, QRadioButton, QSplitter, QTextEdit, QToolTip, and plain QWidgets.

If this property is not specified, the default is padding.

Example:

QFrame {
    background-image: url(:/images/header.png);
    background-position: top left;
    background-origin: content;
}

See also background and The Box Model.

This property is supported by QAbstractItemView subclasses, QAbstractSpinBox subclasses, QCheckBox, QComboBox, QFrame, QGroupBox, QLabel, QLineEdit, QMenu, QMenuBar, QPushButton, QRadioButton, QSplitter, QTextEdit, QToolTip, and plain QWidgets.

If this property is not specified, it defaults to color (i.e., the widget's foreground color).

Example:

QLineEdit {
    border-width: 1px;
    border-style: solid;
    border-color: white;
}

See also border-style, border-width, border-image, and The Box Model.

The border-radius clips the element's background.

This property is supported by QAbstractItemView subclasses, QAbstractSpinBox subclasses, QCheckBox, QComboBox, QFrame, QGroupBox, QLabel, QLineEdit, QMenu, QMenuBar, QPushButton, QRadioButton, QSplitter, QTextEdit, and QToolTip.

If this property is not specified, it defaults to 0.

Example:

QLineEdit {
    border-width: 1px;
    border-style: solid;
    border-radius: 4px;
}

See also border-width and The Box Model.

This property is supported by QAbstractItemView subclasses, QAbstractSpinBox subclasses, QCheckBox, QComboBox, QFrame, QGroupBox, QLabel, QLineEdit, QMenu, QMenuBar, QPushButton, QRadioButton, QSplitter, QTextEdit, and QToolTip.

Example:

QLineEdit {
    border-width: 2px;
    border-style: solid;
    border-color: darkblue;
}

See also border-color, border-radius, border-style, border-image, and The Box Model.

If this property is not specified, it defaults to the value specified by the current style for the SH_DialogButtonLayout style hint.

Example:

* { button-layout: 2 }

If this property is set to 1, the buttons of a QDialogButtonBox show icons; if it is set to 0, the icons are not shown.

See the List of Icons section for information on how to set icons.

QDialogButtonBox { dialogbuttonbox-buttons-have-icons: 1; }

Note: Styles defining this property must be applied before the QDialogButtonBox is created; this means that you must apply the style to the parent widget or to the application itself.

Example:

QCheckBox { font-family: "New Century Schoolbook" }

Example:

QTextEdit { font-style: italic }

If this property is not specified, it defaults to the value specified by the current style for the SH_Table_GridLineColor style hint.

Example:

* { gridline-color: gray }

The only widget currently supporting this property is QPushButton.

Note: It's the application's responsibilty to assign an icon to a button (using the QAbstractButton API), and not the style's. So be careful setting it unless your stylesheet is targeting a specific application.

Available since 5.15.

The image property accepts a list of Urls or an svg. The actual image that is drawn is determined using the same algorithm as QIcon (i.e) the image is never scaled up but always scaled down if necessary. If a svg is specified, the image is scaled to the size of the contents rectangle.

Setting the image property on sub controls implicitly sets the width and height of the sub-control (unless the image in a SVG).

In Qt 4.3 and later, the alignment of the image within the rectangle can be specified using image-position.

This property is for subcontrols only--we don't support it for other elements.

Warning: The QIcon SVG plugin is needed to render SVG images.

Example:

// implicitly sets the size of down-button to the
// size of spindown.png
QSpinBox::down-button { image: url(:/images/spindown.png) }

If position is absolute, the left property specifies the subcontrol's left edge in relation to the parent's left edge (see also subcontrol-origin).

If this property is not specified, it defaults to 0.

Example:

QSpinBox::down-button { left: 2px }

See also right, top, and bottom.

If this property is not specified, it defaults to the value specified by the current style for the SH_LineEdit_PasswordMaskDelay style hint.

This property was added in Qt 5.4.

Example:

* { lineedit-password-mask-delay: 1000 }

This property is supported by QAbstractItemView subclasses, QAbstractSpinBox subclasses, QCheckBox, QComboBox, QFrame, QGroupBox, QLabel, QLineEdit, QMenu, QMenuBar, QPushButton, QRadioButton, QSizeGrip, QSpinBox, QSplitter, QStatusBar, QTextEdit, and QToolTip.

The value is relative to the contents rect in the box model.

Example:

QSpinBox { max-height: 24px }

See also max-width.

If this property is not specified, it defaults to the value specified by the current style for the SH_MessageBox_TextInteractionFlags style hint.

Example:

QMessageBox { messagebox-text-interaction-flags: 5 }

This property is supported by QAbstractItemView subclasses, QAbstractSpinBox subclasses, QCheckBox, QComboBox, QFrame, QGroupBox, QLabel, QLineEdit, QMenu, QMenuBar, QPushButton, QRadioButton, QSizeGrip, QSpinBox, QSplitter, QStatusBar, QTextEdit, and QToolTip.

If this property is not specified, the minimum width is derived based on the widget's contents and the style.

The value is relative to the contents rect in the box model.

Example:

QComboBox { min-width: 72px }

See also min-height.

If position is absolute, the right property specifies the subcontrol's right edge in relation to the parent's right edge (see also subcontrol-origin).

Example:

QSpinBox::down-button { right: 2px }

See also left, top, and bottom.

This property is supported by all widgets that respect the QWidget::palette and that show selection text.

If this property is not set, the default value is whatever is set for the palette's HighlightedText role.

Example:

QTextEdit { selection-color: white }

See also selection-background-color and color.

This property is supported by QCheckBox, checkable QGroupBoxes, QMenuBar, and QRadioButton.

If this property is not specified, the default value depends on the widget and on the current style.

Example:

QMenuBar { spacing: 10 }

See also padding and margin.

If this property is not specified, it defaults to a value that depends on the subcontrol.

Example:

QSpinBox::down-button {
    image: url(:/images/spindown.png);
    subcontrol-origin: padding;
    subcontrol-position: right bottom;
}

See also subcontrol-origin.

If this property is not specified, it defaults to the value specified by the current style for the SH_Widget_Animation_Duration style hint.

This property was added in Qt 5.10.

Example:

* { widget-animation-duration: 100 }

If this property is not specified, it defaults to a value that depends on the subcontrol/widget and on the current style.

Warning: Unless otherwise specified, this property has no effect when set on widgets. If you want a widget with a fixed width, set the min-width and max-width to the same value.

Example:

QSpinBox::up-button { width: 12px }

See also height.

Note: The list can only include properties that are not pixmap-based.

Example:

QTextEdit { background-position: bottom center }

Examples:

QLabel { border-width: 1px }                    /* 1px 1px 1px 1px */
QLabel { border-width: 1px 2px }                /* 1px 2px 1px 2px */
QLabel { border-width: 1px 2px 3px }            /* 1px 2px 3px 2px */
QLabel { border-width: 1px 2px 3px 4px }        /* 1px 2px 3px 4px */

Examples:

QLabel { border-color: red }                      /* opaque red */
QLabel { border-color: #FF0000 }                  /* opaque red */
QLabel { border-color: rgba(255, 0, 0, 75%) }     /* 75% opaque red */
QLabel { border-color: rgb(255, 0, 0) }           /* opaque red */
QLabel { border-color: rgb(100%, 0%, 0%) }        /* opaque red */
QLabel { border-color: hsv(60, 100%, 100%) }      /* opaque yellow */
QLabel { border-color: hsva(240, 255, 255, 75%) } /* 75% blue */
QLabel { border-color: hsl(60, 100%, 50%) }       /* opaque yellow */
QLabel { border-color: hsla(240, 255, 50%, 75%) } /* 75% blue */

Note: The RGB colors allowed are the same as those allowed with CSS 2.1, as listed here.

Example:

* {
    file-icon: url(file.png),
               url(file_selected.png) selected;
  }

QMessageBox {
    dialogbuttonbox-buttons-have-icons: true;
    dialog-ok-icon: url(ok.svg);
    dialog-cancel-icon: url(cancel.png),
                        url(grayed_cancel.png) disabled;
}

For example,

QPushButton { color: palette(dark); }

• repeat-x: Repeat horizontally.
• repeat-y: Repeat vertically.
• repeat: Repeat horizontally and vertically.
• no-repeat: Don't repeat.