or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

buttons.mddialog-notification.mddisplay-widgets.mdindex.mdinput-controls.mdlayout-animation.mdlist-view-widgets.mdmaterial-effects.mdmenu-command.mdmultimedia.mdsettings-config.mdtheme-styling.mdwindow-navigation.md
tile.json

tessl/pypi-pyqt-fluent-widgets

A fluent design widgets library based on PyQt5 providing modern Windows 11-style UI components

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/pyqt-fluent-widgets@1.8.x

To install, run

npx @tessl/cli install tessl/pypi-pyqt-fluent-widgets@1.8.0

index.mddocs/

PyQt-Fluent-Widgets

A comprehensive fluent design widgets library for PyQt5 applications, enabling developers to create modern Windows 11-style user interfaces with native fluent design components. This library provides an extensive collection of UI widgets including buttons, input controls, navigation components, dialogs, and advanced material effects like acrylic backgrounds, all following Microsoft's Fluent Design System principles.

Package Information

  • Package Name: PyQt-Fluent-Widgets
  • Import Name: qfluentwidgets
  • Language: Python
  • Installation: pip install PyQt-Fluent-Widgets
  • Dependencies: PyQt5>=5.15.0, PyQt5-Frameless-Window>=0.4.0, darkdetect
  • Optional Dependencies: scipy, pillow, colorthief (install with pip install PyQt-Fluent-Widgets[full])

Core Imports

import qfluentwidgets

Common import patterns:

from qfluentwidgets import (
    FluentWindow, NavigationInterface, PushButton, PrimaryPushButton,
    FluentIcon, setTheme, Theme, setThemeColor
)

Icon imports:

from qfluentwidgets import FluentIcon as FIF

Basic Usage

import sys
from PyQt5.QtCore import Qt
from PyQt5.QtWidgets import QApplication, QWidget
from qfluentwidgets import (
    FluentWindow, NavigationInterface, PushButton, PrimaryPushButton,
    FluentIcon as FIF, setTheme, Theme, NavigationItemPosition,
    NavigationAvatarWidget
)

class MainWindow(FluentWindow):
    def __init__(self):
        super().__init__()
        self.initWindow()
        self.initNavigation()
        
    def initWindow(self):
        self.resize(900, 700)
        self.setWindowTitle('Fluent App')
        
        # Apply theme
        setTheme(Theme.AUTO)
        
    def initNavigation(self):
        # Create interfaces
        self.homeInterface = QWidget()
        self.settingsInterface = QWidget()
        
        # Add to navigation
        self.addSubInterface(self.homeInterface, FIF.HOME, 'Home')
        self.addSubInterface(self.settingsInterface, FIF.SETTING, 'Settings')
        
        # Add separator and avatar
        self.navigationInterface.addSeparator()
        self.navigationInterface.addWidget(
            routeKey='avatar',
            widget=NavigationAvatarWidget('User', 'avatar.png'),
            position=NavigationItemPosition.BOTTOM
        )

if __name__ == '__main__':
    # High DPI support
    QApplication.setHighDpiScaleFactorRoundingPolicy(
        Qt.HighDpiScaleFactorRoundingPolicy.PassThrough
    )
    QApplication.setAttribute(Qt.AA_EnableHighDpiScaling)
    QApplication.setAttribute(Qt.AA_UseHighDpiPixmaps)
    
    app = QApplication(sys.argv)
    window = MainWindow()
    window.show()
    app.exec_()

Architecture

The library is organized around five core modules that provide comprehensive fluent design functionality:

  • Components: The main widget collection including buttons, inputs, navigation, dialogs, and material effects
  • Common: Theme system, configuration, icons, styling, and utility functions
  • Window: Fluent-styled window classes with integrated navigation
  • Multimedia: Media player components for audio/video playback
  • Resources: Embedded resources including icons and stylesheets

The architecture follows Microsoft's Fluent Design System principles with automatic theme detection, smooth animations, and modern visual effects.

Capabilities

Button Widgets

Modern button components with fluent design styling, supporting multiple constructor patterns, icons, and various visual styles including primary, transparent, toggle, and hyperlink variants.

class PushButton(QPushButton):
    def __init__(self, parent: QWidget = None): ...
    def __init__(self, text: str, parent: QWidget = None, icon: Union[QIcon, str, FluentIconBase] = None): ...
    def __init__(self, icon: Union[QIcon, FluentIconBase], text: str, parent: QWidget = None): ...

class PrimaryPushButton(PushButton): ...
class TransparentPushButton(PushButton): ...
class TogglePushButton(PushButton): ...  
class HyperlinkButton(QPushButton):
    def __init__(self, url: str, text: str, parent: QWidget = None, icon: Union[QIcon, FluentIconBase, str] = None): ...

Button Widgets

Window and Navigation

Fluent-styled windows with integrated navigation interfaces, supporting hierarchical navigation, route-based page switching, and modern title bars with system integration.

class FluentWindow(FluentWindowBase):
    def __init__(self, parent=None): ...
    def addSubInterface(self, interface: QWidget, icon: Union[FluentIconBase, QIcon, str], text: str,
                      position=NavigationItemPosition.TOP, parent=None, isTransparent=False) -> NavigationTreeWidget: ...

class NavigationInterface(QWidget):
    def __init__(self, parent=None, showMenuButton=True, showReturnButton=False, collapsible=True): ...
    def addItem(self, routeKey: str, icon: Union[str, QIcon, FluentIconBase], text: str, onClick=None,
               selectable=True, position=NavigationItemPosition.TOP, tooltip: str = None,
               parentRouteKey: str = None) -> NavigationTreeWidget: ...

Window and Navigation

Input Controls

Comprehensive form controls including text inputs, combo boxes, sliders, date/time pickers, and spinboxes with fluent design styling and advanced features.

class LineEdit(QLineEdit):
    def __init__(self, parent=None): ...

class ComboBox(QComboBox):
    def __init__(self, parent=None): ...
    def setPlaceholderText(self, text: str): ...

class SearchLineEdit(LineEdit): ...
class PasswordLineEdit(LineEdit): ...
class TextEdit(QTextEdit): ...
class PlainTextEdit(QPlainTextEdit): ...

Input Controls

Display Widgets

Labels, images, cards, and container widgets for displaying content with fluent design typography and layout patterns.

class CardWidget(QWidget):
    def __init__(self, parent=None): ...

class ElevatedCardWidget(CardWidget): ...
class SimpleCardWidget(CardWidget): ...
class HeaderCardWidget(CardWidget): ...

class BodyLabel(QLabel): ...
class TitleLabel(QLabel): ...
class SubtitleLabel(QLabel): ...
class LargeTitleLabel(QLabel): ...
class DisplayLabel(QLabel): ...
class ImageLabel(QLabel): ...
class AvatarWidget(QLabel): ...
class PixmapLabel(QLabel): ...
class IconWidget(QWidget): ...

Display Widgets

List and View Widgets

Advanced list, table, and tree components with custom delegates, smooth scrolling, and fluent design integration.

class ListWidget(QListWidget): ...
class ListView(QListView): ...
class TableWidget(QTableWidget): ...
class TableView(QTableView): ...
class TreeWidget(QTreeWidget): ...
class TreeView(QTreeView): ...
class CycleListWidget(QListWidget): ...

class ListItemDelegate(QStyledItemDelegate): ...
class TableItemDelegate(QStyledItemDelegate): ...
class TreeItemDelegate(QStyledItemDelegate): ...

List and View Widgets

Menu and Command System

Context menus, command bars, and system tray menus with fluent styling, animations, and modern interaction patterns.

class RoundMenu(QMenu): ...
class DWMMenu(QMenu): ...
class LineEditMenu(RoundMenu): ...
class CheckableMenu(RoundMenu): ...
class SystemTrayMenu(QMenu): ...
class CheckableSystemTrayMenu(SystemTrayMenu): ...

class CommandBar(QWidget): ...
class CommandButton(QToolButton): ...
class CommandBarView(QWidget): ...

Menu and Command System

Dialog and Notification System

Modal dialogs, message boxes, flyouts, and notification components with fluent design animations and positioning.

class MessageBox(MaskDialogBase): ...
class MessageDialog(MaskDialogBase): ...
class Dialog(MaskDialogBase): ...
class ColorDialog(MaskDialogBase): ...
class FolderListDialog(MaskDialogBase): ...

class InfoBar(QWidget): ...
class InfoBadge(QWidget): ...
class DotInfoBadge(InfoBadge): ...
class IconInfoBadge(InfoBadge): ...

class TeachingTip(QWidget): ...
class PopupTeachingTip(TeachingTip): ...
class Flyout(QWidget): ...
class FlyoutView(QWidget): ...
class ToolTip(QWidget): ...
class StateToolTip(QWidget): ...

Dialog and Notification System

Settings and Configuration

Setting cards, configuration management, and option panels for building preference interfaces with validation and persistence.

class SettingCard(QWidget): ...
class SwitchSettingCard(SettingCard): ...
class ComboBoxSettingCard(SettingCard): ...
class RangeSettingCard(SettingCard): ...
class PushSettingCard(SettingCard): ...
class ColorSettingCard(SettingCard): ...
class HyperlinkCard(SettingCard): ...
class ExpandSettingCard(SettingCard): ...
class FolderListSettingCard(SettingCard): ...
class OptionsSettingCard(SettingCard): ...
class SettingCardGroup(QWidget): ...

class QConfig(QObject): ...
class ConfigItem: ...
class ConfigValidator: ...

Settings and Configuration

Material Effects

Acrylic blur effects, material design components, and advanced visual effects for modern UI aesthetics.

class AcrylicWidget(QWidget): ...
class AcrylicBrush(QBrush): ...

class AcrylicMenu(RoundMenu): ...
class AcrylicLineEditMenu(RoundMenu): ...
class AcrylicCheckableMenu(RoundMenu): ...
class AcrylicSystemTrayMenu(SystemTrayMenu): ...

class AcrylicLineEdit(LineEdit): ...
class AcrylicSearchLineEdit(SearchLineEdit): ...
class AcrylicComboBox(ComboBox): ...
class AcrylicEditableComboBox(EditableComboBox): ...

class AcrylicFlyout(Flyout): ...
class AcrylicFlyoutView(FlyoutView): ...
class AcrylicToolTip(ToolTip): ...

Material Effects

Theme and Styling System

Comprehensive theme management with automatic dark/light mode detection, color customization, and fluent design stylesheets.

class Theme(Enum):
    LIGHT = "Light"
    DARK = "Dark"
    AUTO = "Auto"

def setTheme(theme: Theme): ...
def setThemeColor(color: QColor): ...
def isDarkTheme() -> bool: ...
def toggleTheme(): ...

class FluentIcon(FluentIconBase, Enum): ...
class ThemeColor(Enum): ...

Theme and Styling System

Layout and Animation

Advanced layout managers, smooth scrolling, animated containers, and transition effects for fluid user experiences.

class FlowLayout(QLayout): ...
class ExpandLayout(QVBoxLayout): ...
class VBoxLayout(QVBoxLayout): ...

class ScrollArea(QScrollArea): ...
class SmoothScrollArea(ScrollArea): ...
class SingleDirectionScrollArea(ScrollArea): ...
class SmoothScrollBar(QScrollBar): ...

class PopUpAniStackedWidget(QStackedWidget): ...
class OpacityAniStackedWidget(QStackedWidget): ...

class ProgressBar(QProgressBar): ...
class ProgressRing(QWidget): ...
class IndeterminateProgressBar(ProgressBar): ...
class IndeterminateProgressRing(ProgressRing): ...

Layout and Animation

Multimedia Components

Media player widgets, video display, and audio/video control components with modern playback interfaces.

class MediaPlayer(QWidget): ...
class MediaPlayerBase(QWidget): ...
class VideoWidget(QVideoWidget): ...
class StandardMediaPlayBar(QWidget): ...
class SimpleMediaPlayBar(QWidget): ...
class MediaPlayBarButton(QToolButton): ...

Multimedia Components

Error Handling

Common exceptions that may be raised:

  • ImportError: When required PyQt5 dependencies are not installed
  • AttributeError: When accessing undefined widget properties or methods
  • ValueError: When providing invalid parameters to configuration functions
  • RuntimeError: When widget operations are performed outside the main thread

Most widget methods follow PyQt5 conventions and raise standard Qt exceptions for invalid operations.