shadcn-qt

Appearance

Theming ​

shadcn-qt uses the same semantic vocabulary as shadcn/ui: background, foreground, primary, secondary, muted, accent, destructive, border, input, and ring. Widgets consume those roles instead of hard-coded brand colors.

The built-in visual profile is classic new-york + Zinc. new-york defines component geometry, spacing, shadows, focus states, and interaction rhythm; Zinc defines the neutral light/dark palette. This is the classic registry profile, not one of the newer Vega/Nova/Maia presets. The repository's visual baseline records the audited metrics and official registry references.

Apply a built-in theme ​

python
from shadcn_qt import apply_theme
from shadcn_qt._qt import QtWidgets

app = QtWidgets.QApplication([])
apply_theme(app, "dark")

apply_theme("dark") is also valid after a QApplication exists.

Style existing native Qt widgets ​

Existing projects can keep their QPushButton, QLineEdit, QCheckBox, and other standard widget classes. Enable compatibility mode before constructing the main window:

python
from shadcn_qt import apply_theme, enable_native_widget_styling

app = QtWidgets.QApplication([])
enable_native_widget_styling(app)

window = MainWindow()
apply_theme(app, "dark")

The adapter covers the complete QtWidgets QWidget family, including editors, item views, scrollbars, toolbars, docks, dialogs, containers, and dynamically created widgets. Known controls receive component-specific QSS and reversible runtime enhancements where QSS is insufficient; unknown QWidget subclasses receive a neutral theme fallback. Explicit component properties are preserved. Use shadcn_qt_native_styling=False to exclude an individual widget, or adopt_native_widgets(page) for a one-time scoped migration.

See Native QtWidgets for the coverage matrix, Gallery previews, screenshot regression workflow, and platform-native dialog limits. The existing-project migration guide covers semantic overrides, cleanup, and legacy QSS integration.

Global configuration ​

Call configure() once near application startup. All later parameterless apply_theme() calls use this configuration.

python
from shadcn_qt import configure, apply_theme

configure(
    theme="light",
    colors={"primary": "#7c3aed", "ring": "#8b5cf6"},
    radius_base=9,
    radius={"xl": "20px"},
    font={"sansFamily": "Inter, 'Segoe UI', sans-serif"},
    extra_qss="QWidget#sidebar { border-right: 1px solid #ddd; }",
)
apply_theme()

radius_base is the md corner radius in pixels. It derives every semantic surface tier with the ratio sm/md/lg/xl = 2/3 : 1 : 4/3 : 2; a base of 9 therefore produces 6px / 9px / 12px / 18px. Entries supplied through radius are applied afterward and can override an individual tier. Radio indicators, slider handles, switch tracks, and other circle or pill geometry continue to derive their radius from their own dimensions.

The Gallery header can switch among Zinc, Blue, Violet, Emerald, Orange, and Rose with one selection, and its Radius control previews global semantic corner scaling live. Each color preset changes the related primary, primaryForeground, ring, accent, and accentForeground tokens together and supplies matching low-saturation background, card, popover, secondary, muted, border, and input surfaces. Separate light and dark values keep windows, components, buttons, focused inputs, checked controls, selections, and hover states in the same color family while preserving readable contrast.

Launch a preset directly when comparing components or capturing a screenshot:

bash
python examples/python_gallery/run.py --theme dark --color-theme emerald --radius-base 12

Reusable custom themes ​

python
from shadcn_qt import create_theme, register_theme, apply_theme

ocean = create_theme(
    "ocean",
    base="dark",
    colors={
        "primary": "#38bdf8",
        "primaryForeground": "#082f49",
        "ring": "#7dd3fc",
    },
)
register_theme(ocean)
apply_theme("ocean")

create_theme() merges the override into a complete light or dark base, so all semantic tokens remain defined.

JSON theme ​

json
{
  "name": "brand",
  "base": "light",
  "colors": {
    "primary": "#7c3aed",
    "ring": "#8b5cf6"
  },
  "radiusBase": 9,
  "radius": { "xl": "20px" }
}
python
from shadcn_qt import load_theme, apply_theme
apply_theme(load_theme("brand.json"))

Token source and code generation ​

The repository's built-in palette lives in packages/design-tokens/tokens.json. After editing it, run:

bash
python tools/token-codegen/generate.py

This writes Python QSS, the C++ resource QSS, and the C++ token header from the same source. Application-specific themes do not require regeneration; they are rendered at runtime.