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

buttons.mddocs/

Button Widgets

Modern button components with fluent design styling, supporting multiple constructor patterns, icons, and various visual styles. All button widgets provide automatic theme awareness, smooth hover animations, and consistent fluent design appearance.

Capabilities

Push Buttons

Standard push buttons that can contain text, icons, or both. Supports multiple constructor overloads for flexible initialization.

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: QIcon, text: str, parent: QWidget = None): ...
    def __init__(self, icon: FluentIconBase, text: str, parent: QWidget = None): ...
    
    def setIcon(self, icon: Union[QIcon, str, FluentIconBase]): ...
    def icon(self) -> QIcon: ...

Usage Example:

from qfluentwidgets import PushButton, FluentIcon as FIF

# Basic button
button = PushButton("Click me", self)

# Button with icon
save_btn = PushButton("Save", self, FIF.SAVE)

# Icon-first constructor  
open_btn = PushButton(FIF.FOLDER, "Open File", self)

# Icon only button
icon_btn = PushButton(self)
icon_btn.setIcon(FIF.CLOSE)

Primary Push Buttons

Emphasized buttons using the application's primary theme color for important actions like submit, confirm, or primary navigation.

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

Usage Example:

from qfluentwidgets import PrimaryPushButton, FluentIcon as FIF

# Primary action button
submit_btn = PrimaryPushButton("Submit", self, FIF.ACCEPT)
login_btn = PrimaryPushButton("Login", self)

Transparent Buttons

Buttons with transparent backgrounds that show content clearly while maintaining interactive feedback through hover and press states.

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

Usage Example:

from qfluentwidgets import TransparentPushButton, FluentIcon as FIF

# Subtle action button
cancel_btn = TransparentPushButton("Cancel", self)
help_btn = TransparentPushButton("Help", self, FIF.HELP)

Toggle Buttons

Checkable buttons that maintain pressed/unpressed state, useful for on/off settings, view toggles, and option selection.

class ToggleButton(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: QIcon, text: str, parent: QWidget = None): ...
    def __init__(self, icon: FluentIconBase, text: str, parent: QWidget = None): ...

class TogglePushButton(ToggleButton): ...
class TransparentTogglePushButton(ToggleButton): ...

Usage Example:

from qfluentwidgets import TogglePushButton, FluentIcon as FIF

# View toggle
grid_view_btn = TogglePushButton("Grid View", self, FIF.GRID_VIEW)
grid_view_btn.setCheckable(True)
grid_view_btn.toggled.connect(self.on_view_changed)

# Setting toggle
notifications_btn = TogglePushButton("Notifications", self, FIF.NOTIFICATION)
notifications_btn.setChecked(True)  # Default on

Tool Buttons

Compact buttons designed for toolbars and action bars, optimized for icon display and space efficiency.

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

class PrimaryToolButton(ToolButton): ...
class TransparentToolButton(ToolButton): ...
class ToggleToolButton(ToolButton): ...
class TransparentToggleToolButton(ToolButton): ...

Usage Example:

from qfluentwidgets import ToolButton, PrimaryToolButton, FluentIcon as FIF

# Toolbar buttons
copy_btn = ToolButton(FIF.COPY, self)
paste_btn = ToolButton(FIF.PASTE, self)
primary_action = PrimaryToolButton(FIF.PLAY, self)

# Tool button with text
save_tool = ToolButton(FIF.SAVE, self)
save_tool.setText("Save")
save_tool.setToolButtonStyle(Qt.ToolButtonTextBesideIcon)

Hyperlink Buttons

Specialized buttons for web links and navigation, automatically handling URL opening and providing appropriate visual styling.

class HyperlinkButton(QPushButton):
    def __init__(self, parent: QWidget = None): ...
    def __init__(self, url: str, text: str, parent: QWidget = None, icon: Union[QIcon, FluentIconBase, str] = None): ...
    
    def setUrl(self, url: str): ...
    def getUrl(self) -> str: ...

Usage Example:

from qfluentwidgets import HyperlinkButton, FluentIcon as FIF

# Website link
website_btn = HyperlinkButton("https://example.com", "Visit Website", self)

# Documentation link with icon
docs_btn = HyperlinkButton("https://docs.example.com", "Documentation", self, FIF.DOCUMENT)

# Programmatic URL setting
link_btn = HyperlinkButton(self)
link_btn.setText("GitHub")
link_btn.setUrl("https://github.com/user/repo")

Dropdown Buttons

Buttons with integrated dropdown menus for grouped actions and option selection.

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

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

class PrimaryDropDownPushButton(DropDownPushButton): ...
class PrimaryDropDownToolButton(DropDownToolButton): ...
class TransparentDropDownPushButton(DropDownPushButton): ...
class TransparentDropDownToolButton(DropDownToolButton): ...

Usage Example:

from qfluentwidgets import DropDownPushButton, RoundMenu, Action, FluentIcon as FIF

# Create dropdown button
save_dropdown = DropDownPushButton("Save", self, FIF.SAVE)

# Create and assign menu
menu = RoundMenu(parent=self)
menu.addAction(Action(FIF.SAVE, "Save", self))
menu.addAction(Action(FIF.SAVE_AS, "Save As", self))
menu.addAction(Action(FIF.SAVE_COPY, "Save Copy", self))

save_dropdown.setMenu(menu)

Split Buttons

Buttons with separate clickable areas for default action and dropdown menu access.

class SplitWidgetBase(QWidget): ...

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

class SplitToolButton(SplitWidgetBase): ...
class PrimarySplitPushButton(SplitPushButton): ...
class PrimarySplitToolButton(SplitToolButton): ...

Usage Example:

from qfluentwidgets import SplitPushButton, RoundMenu, Action, FluentIcon as FIF

# Split button with default action
new_btn = SplitPushButton("New Document", self, FIF.DOCUMENT)

# Connect main button action
new_btn.clicked.connect(self.create_new_document)

# Create dropdown menu
menu = RoundMenu(parent=self)
menu.addAction(Action(FIF.DOCUMENT, "New Document", self))
menu.addAction(Action(FIF.FOLDER, "New Folder", self))
menu.addAction(Action(FIF.PROJECT, "New Project", self))

new_btn.setMenu(menu)

Pill Buttons

Rounded button variants with distinctive pill-shaped appearance for modern interface designs.

class PillPushButton(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: QIcon, text: str, parent: QWidget = None): ...
    def __init__(self, icon: FluentIconBase, text: str, parent: QWidget = None): ...

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

Usage Example:

from qfluentwidgets import PillPushButton, PillToolButton, FluentIcon as FIF

# Modern pill-shaped button
action_btn = PillPushButton("Get Started", self, FIF.PLAY)
tag_btn = PillPushButton("Python", self)

# Pill tool button for compact spaces
pill_tool = PillToolButton(FIF.SETTING, self)

Radio Buttons

Mutually exclusive selection buttons following fluent design principles with smooth animations and proper grouping behavior.

class RadioButton(QRadioButton):
    def __init__(self, parent: QWidget = None): ...
    def __init__(self, text: str, parent: QWidget = None): ...

Usage Example:

from qfluentwidgets import RadioButton
from PyQt5.QtWidgets import QButtonGroup

# Create radio button group
size_group = QButtonGroup(self)

small_radio = RadioButton("Small", self)
medium_radio = RadioButton("Medium", self)  
large_radio = RadioButton("Large", self)

size_group.addButton(small_radio, 0)
size_group.addButton(medium_radio, 1)
size_group.addButton(large_radio, 2)

medium_radio.setChecked(True)  # Default selection
size_group.buttonClicked.connect(self.on_size_changed)

Common Button Properties and Methods

All button widgets inherit standard PyQt button functionality with fluent design enhancements:

# Standard PyQt methods work with fluent styling
button.setText("New Text")
button.setEnabled(False)
button.setVisible(False)
button.resize(120, 32)

# Signal connections
button.clicked.connect(callback)
button.pressed.connect(on_press)
button.released.connect(on_release)

# For toggle buttons
toggle_btn.toggled.connect(on_toggle)
toggle_btn.setChecked(True)

Switch Buttons

Toggle switches for boolean settings and on/off states with smooth animations.

class SwitchButton(QWidget):
    def __init__(self, parent=None, indicatorPos=IndicatorPosition.LEFT): ...
    def setChecked(self, checked: bool): ...
    def isChecked(self) -> bool: ...
    def setText(self, text: str): ...
    def text(self) -> str: ...
    def setIndicatorPosition(self, pos: IndicatorPosition): ...
    
    checkedChanged = pyqtSignal(bool)

class IndicatorPosition(Enum):
    LEFT = 0
    RIGHT = 1

Usage Example:

from qfluentwidgets import SwitchButton, IndicatorPosition

# Basic switch
notifications_switch = SwitchButton(self)
notifications_switch.setText("Enable Notifications")
notifications_switch.setChecked(True)
notifications_switch.checkedChanged.connect(self.toggle_notifications)

# Switch with indicator on right
auto_save_switch = SwitchButton(self, IndicatorPosition.RIGHT)
auto_save_switch.setText("Auto Save")
auto_save_switch.setChecked(False)

def toggle_notifications(self, enabled):
    if enabled:
        print("Notifications enabled")
    else:
        print("Notifications disabled")

Button Styling and Themes

All buttons automatically adapt to the current theme (light/dark) and can be customized with theme colors:

from qfluentwidgets import setThemeColor, FluentThemeColor

# Apply custom theme color to all buttons
setThemeColor(FluentThemeColor.RED.color())

# Buttons automatically update their appearance

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