CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-pyqt-fluent-widgets

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

window-navigation.mddocs/

Window and Navigation

Fluent-styled windows with integrated navigation interfaces, supporting hierarchical navigation, route-based page switching, and modern title bars with system integration. These components provide the foundation for modern Windows 11-style applications.

Capabilities

Fluent Window

Main application window with integrated navigation interface, fluent design title bar, and automatic theme support.

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: ...
    def switchTo(self, interface: QWidget): ...
    def stackedWidget(self) -> QStackedWidget: ...
    def resizeEvent(self, e): ...
    def closeEvent(self, e): ...

Usage Example:

from qfluentwidgets import FluentWindow, FluentIcon as FIF, NavigationItemPosition
from PyQt5.QtWidgets import QWidget, QApplication
from PyQt5.QtCore import Qt

class MainWindow(FluentWindow):
    def __init__(self):
        super().__init__()
        self.initWindow()
        self.initNavigation()
        
    def initWindow(self):
        self.resize(900, 700)
        self.setWindowTitle('My Fluent App')
        
        # Center window on screen
        desktop = QApplication.desktop().availableGeometry()
        w, h = desktop.width(), desktop.height()
        self.move(w//2 - self.width()//2, h//2 - self.height()//2)
        
    def initNavigation(self):
        # Create interface pages
        self.homeInterface = HomeWidget(self)
        self.settingsInterface = SettingsWidget(self)
        self.aboutInterface = AboutWidget(self)
        
        # Add to navigation
        self.addSubInterface(self.homeInterface, FIF.HOME, 'Home')
        self.addSubInterface(self.settingsInterface, FIF.SETTING, 'Settings')
        
        # Add separator
        self.navigationInterface.addSeparator()
        
        # Add bottom items
        self.addSubInterface(
            self.aboutInterface, 
            FIF.INFO, 
            'About', 
            NavigationItemPosition.BOTTOM
        )

Microsoft-Style Fluent Window

Alternative window style that more closely matches Microsoft's own fluent design applications.

class MSFluentWindow(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: ...

Usage Example:

from qfluentwidgets import MSFluentWindow, FluentIcon as FIF

class MSStyleWindow(MSFluentWindow):
    def __init__(self):
        super().__init__()
        self.resize(1000, 750)
        self.setWindowTitle('Microsoft Style App')
        
        # Add interfaces with MS styling
        self.addSubInterface(self.mainInterface, FIF.HOME, 'Home')
        self.addSubInterface(self.dataInterface, FIF.DATABASE, 'Data')

Split Fluent Window

Window with split navigation panel that can be collapsed or expanded for more flexible layout options.

class SplitFluentWindow(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: ...

Navigation Interface

Core navigation component that manages route-based page switching, hierarchical navigation, and navigation items.

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: ...
               
    def addWidget(self, routeKey: str, widget: NavigationWidget, onClick=None, 
                 position=NavigationItemPosition.TOP, tooltip: str = None,
                 parentRouteKey: str = None) -> NavigationTreeWidget: ...
                 
    def addSeparator(self, position=NavigationItemPosition.TOP): ...
    def setCurrentItem(self, routeKey: str): ...
    def setExpandWidth(self, width: int): ...
    def setCollapsible(self, collapsible: bool): ...
    def panel(self) -> NavigationPanel: ...

Usage Example:

from qfluentwidgets import NavigationInterface, NavigationAvatarWidget, FluentIcon as FIF

# Create standalone navigation
nav = NavigationInterface(self, showMenuButton=True, collapsible=True)

# Add navigation items
nav.addItem('home', FIF.HOME, 'Home', self.show_home)
nav.addItem('documents', FIF.DOCUMENT, 'Documents', self.show_documents)
nav.addItem('pictures', FIF.PHOTO, 'Pictures', self.show_pictures)

# Add separator
nav.addSeparator()

# Add hierarchical items
nav.addItem('settings', FIF.SETTING, 'Settings')
nav.addItem('general', FIF.SETTING, 'General', parentRouteKey='settings')
nav.addItem('advanced', FIF.DEVELOPER_TOOLS, 'Advanced', parentRouteKey='settings')

# Add custom widget
avatar = NavigationAvatarWidget('John Doe', 'avatar.png')
nav.addWidget('profile', avatar, self.show_profile, NavigationItemPosition.BOTTOM)

# Set current page
nav.setCurrentItem('home')

Navigation Components

Individual navigation elements for building custom navigation interfaces.

class NavigationWidget(QWidget): ...

class NavigationPushButton(NavigationWidget):
    def __init__(self, icon: Union[str, QIcon, FluentIconBase], text: str, isSelectable: bool = True, parent=None): ...

class NavigationToolButton(NavigationWidget):
    def __init__(self, icon: Union[str, QIcon, FluentIconBase], isSelectable: bool = True, parent=None): ...
    
class NavigationSeparator(NavigationWidget): ...

class NavigationTreeWidget(NavigationWidget):
    def __init__(self, icon: Union[str, QIcon, FluentIconBase], text: str, isSelectable: bool = True, parent=None): ...
    def addChild(self, child: NavigationWidget): ...

class NavigationAvatarWidget(NavigationWidget):
    def __init__(self, name: str, avatar: Union[str, QPixmap, QIcon], parent=None): ...
    def setName(self, name: str): ...
    def setAvatar(self, avatar: Union[str, QPixmap, QIcon]): ...

Usage Example:

from qfluentwidgets import (NavigationPushButton, NavigationSeparator, 
                           NavigationAvatarWidget, FluentIcon as FIF)

# Create individual navigation components
home_btn = NavigationPushButton(FIF.HOME, 'Home', True, self)
settings_btn = NavigationPushButton(FIF.SETTING, 'Settings', True, self)
separator = NavigationSeparator(self)
avatar = NavigationAvatarWidget('User', 'user_avatar.png', self)

# Connect signals
home_btn.clicked.connect(self.show_home_page)
settings_btn.clicked.connect(self.show_settings_page)

Navigation Bar

Horizontal navigation bar for tab-style navigation patterns.

class NavigationBar(QWidget):
    def __init__(self, parent=None): ...
    def addItem(self, routeKey: str, icon: Union[str, QIcon, FluentIconBase], text: str, onClick=None,
               selectable: bool = True, tooltip: str = None) -> NavigationBarPushButton: ...
    def setCurrentItem(self, routeKey: str): ...

class NavigationBarPushButton(QPushButton): ...

Usage Example:

from qfluentwidgets import NavigationBar, FluentIcon as FIF

# Create horizontal navigation bar
nav_bar = NavigationBar(self)

# Add navigation items
nav_bar.addItem('overview', FIF.HOME, 'Overview', self.show_overview)
nav_bar.addItem('analytics', FIF.CHART, 'Analytics', self.show_analytics)
nav_bar.addItem('reports', FIF.DOCUMENT, 'Reports', self.show_reports)

# Set initial selection
nav_bar.setCurrentItem('overview')

Pivot Navigation

Tabbed navigation component for switching between related content areas.

class Pivot(QWidget):
    def __init__(self, parent=None): ...
    def addItem(self, routeKey: str, text: str, onClick=None, icon: Union[QIcon, str, FluentIconBase] = None) -> PivotItem: ...
    def setCurrentItem(self, routeKey: str): ...
    def currentRouteKey(self) -> str: ...

class PivotItem(QWidget):
    def __init__(self, routeKey: str, text: str, parent=None): ...
    def setSelected(self, isSelected: bool): ...

Usage Example:

from qfluentwidgets import Pivot, FluentIcon as FIF

# Create pivot navigation
pivot = Pivot(self)

# Add pivot items
pivot.addItem('emails', 'Emails', self.show_emails, FIF.MAIL)
pivot.addItem('calendar', 'Calendar', self.show_calendar, FIF.CALENDAR)
pivot.addItem('contacts', 'Contacts', self.show_contacts, FIF.CONTACT)

# Set current pivot
pivot.setCurrentItem('emails')

# Connect to content switching
pivot.currentItemChanged.connect(self.switch_content)

Segmented Controls

Compact navigation for closely related options and view modes.

class SegmentedWidget(QWidget):
    def __init__(self, parent=None): ...
    def addItem(self, routeKey: str, text: str, onClick=None, icon: Union[QIcon, str, FluentIconBase] = None) -> SegmentedItem: ...
    def setCurrentItem(self, routeKey: str): ...

class SegmentedItem(QWidget): ...

class SegmentedToolWidget(QWidget):
    def __init__(self, parent=None): ...
    def addItem(self, routeKey: str, icon: Union[QIcon, str, FluentIconBase], onClick=None) -> SegmentedToolItem: ...

class SegmentedToggleToolWidget(SegmentedToolWidget): ...

Usage Example:

from qfluentwidgets import SegmentedWidget, SegmentedToolWidget, FluentIcon as FIF

# Text-based segmented control
view_segments = SegmentedWidget(self)
view_segments.addItem('list', 'List View', self.show_list_view)
view_segments.addItem('grid', 'Grid View', self.show_grid_view)
view_segments.addItem('detail', 'Detail View', self.show_detail_view)

# Icon-based segmented tools
tool_segments = SegmentedToolWidget(self)
tool_segments.addItem('bold', FIF.BOLD, self.toggle_bold)
tool_segments.addItem('italic', FIF.ITALIC, self.toggle_italic)
tool_segments.addItem('underline', FIF.UNDERLINE, self.toggle_underline)

Breadcrumb Navigation

Hierarchical navigation showing the current location within nested content.

class BreadcrumbBar(QWidget):
    def __init__(self, parent=None): ...
    def addItem(self, routeKey: str, text: str, onClick=None) -> BreadcrumbItem: ...
    def clear(): ...
    def setCurrentItem(self, routeKey: str): ...

class BreadcrumbItem(QWidget):
    def __init__(self, routeKey: str, text: str, parent=None): ...
    def setText(self, text: str): ...
    def setSelected(self, isSelected: bool): ...

Usage Example:

from qfluentwidgets import BreadcrumbBar

# Create breadcrumb navigation
breadcrumb = BreadcrumbBar(self)

# Build breadcrumb path
breadcrumb.addItem('home', 'Home', self.navigate_home)
breadcrumb.addItem('documents', 'Documents', self.navigate_documents)
breadcrumb.addItem('projects', 'Projects', self.navigate_projects)
breadcrumb.addItem('current', 'My Project', self.navigate_current)

# Set current location
breadcrumb.setCurrentItem('current')

# Update breadcrumb when navigating
def update_breadcrumb(self, path_items):
    breadcrumb.clear()
    for item in path_items:
        breadcrumb.addItem(item['key'], item['text'], item['callback'])

Title Bars

Custom title bars with fluent design styling and system window controls.

class FluentTitleBar(QWidget):
    def __init__(self, parent=None): ...
    def setTitle(self, title: str): ...
    def setIcon(self, icon: QIcon): ...

class MSFluentTitleBar(FluentTitleBar): ...
class SplitTitleBar(FluentTitleBar): ...

Navigation Item Positions

class NavigationItemPosition(Enum):
    TOP = 0
    SCROLL = 1
    BOTTOM = 2

Navigation Display Modes

class NavigationDisplayMode(Enum):
    EXPAND = 0
    COMPACT = 1
    MINIMAL = 2

Common Navigation Patterns

Multi-level Navigation

# Create hierarchical navigation structure
nav.addItem('media', FIF.MEDIA, 'Media')
nav.addItem('music', FIF.MUSIC, 'Music', parentRouteKey='media')
nav.addItem('videos', FIF.VIDEO, 'Videos', parentRouteKey='media')
nav.addItem('photos', FIF.PHOTO, 'Photos', parentRouteKey='media')

Dynamic Navigation Updates

# Add items dynamically
def add_recent_file(self, filename, filepath):
    route_key = f"recent_{filename}"
    self.navigationInterface.addItem(
        route_key, FIF.DOCUMENT, filename,
        lambda: self.open_file(filepath),
        position=NavigationItemPosition.TOP
    )

Navigation with Custom Actions

# Add items with custom click handling
nav.addItem('export', FIF.SHARE, 'Export Data', self.show_export_dialog)
nav.addItem('import', FIF.DOWNLOAD, 'Import Data', self.show_import_dialog)

Install with Tessl CLI

npx tessl i tessl/pypi-pyqt-fluent-widgets

docs

buttons.md

dialog-notification.md

display-widgets.md

index.md

input-controls.md

layout-animation.md

list-view-widgets.md

material-effects.md

menu-command.md

multimedia.md

settings-config.md

theme-styling.md

window-navigation.md

tile.json