0
# Button Widgets
1

2
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.
3

4
## Capabilities
5

6
### Push Buttons
7

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

10
```python { .api }
11
class PushButton(QPushButton):
12
    def __init__(self, parent: QWidget = None): ...
13
    def __init__(self, text: str, parent: QWidget = None, icon: Union[QIcon, str, FluentIconBase] = None): ...
14
    def __init__(self, icon: QIcon, text: str, parent: QWidget = None): ...
15
    def __init__(self, icon: FluentIconBase, text: str, parent: QWidget = None): ...
16
    
17
    def setIcon(self, icon: Union[QIcon, str, FluentIconBase]): ...
18
    def icon(self) -> QIcon: ...
19
```
20

21
**Usage Example:**
22
```python
23
from qfluentwidgets import PushButton, FluentIcon as FIF
24

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

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

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

34
# Icon only button
35
icon_btn = PushButton(self)
36
icon_btn.setIcon(FIF.CLOSE)
37
```
38

39
### Primary Push Buttons
40

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

43
```python { .api }
44
class PrimaryPushButton(PushButton):
45
    def __init__(self, parent: QWidget = None): ...
46
    def __init__(self, text: str, parent: QWidget = None, icon: Union[QIcon, str, FluentIconBase] = None): ...
47
    def __init__(self, icon: QIcon, text: str, parent: QWidget = None): ...
48
    def __init__(self, icon: FluentIconBase, text: str, parent: QWidget = None): ...
49
```
50

51
**Usage Example:**
52
```python
53
from qfluentwidgets import PrimaryPushButton, FluentIcon as FIF
54

55
# Primary action button
56
submit_btn = PrimaryPushButton("Submit", self, FIF.ACCEPT)
57
login_btn = PrimaryPushButton("Login", self)
58
```
59

60
### Transparent Buttons
61

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

64
```python { .api }
65
class TransparentPushButton(PushButton):
66
    def __init__(self, parent: QWidget = None): ...
67
    def __init__(self, text: str, parent: QWidget = None, icon: Union[QIcon, str, FluentIconBase] = None): ...
68
    def __init__(self, icon: QIcon, text: str, parent: QWidget = None): ...
69
    def __init__(self, icon: FluentIconBase, text: str, parent: QWidget = None): ...
70
```
71

72
**Usage Example:**
73
```python
74
from qfluentwidgets import TransparentPushButton, FluentIcon as FIF
75

76
# Subtle action button
77
cancel_btn = TransparentPushButton("Cancel", self)
78
help_btn = TransparentPushButton("Help", self, FIF.HELP)
79
```
80

81
### Toggle Buttons
82

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

85
```python { .api }
86
class ToggleButton(QPushButton):
87
    def __init__(self, parent: QWidget = None): ...
88
    def __init__(self, text: str, parent: QWidget = None, icon: Union[QIcon, str, FluentIconBase] = None): ...
89
    def __init__(self, icon: QIcon, text: str, parent: QWidget = None): ...
90
    def __init__(self, icon: FluentIconBase, text: str, parent: QWidget = None): ...
91

92
class TogglePushButton(ToggleButton): ...
93
class TransparentTogglePushButton(ToggleButton): ...
94
```
95

96
**Usage Example:**
97
```python
98
from qfluentwidgets import TogglePushButton, FluentIcon as FIF
99

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

105
# Setting toggle
106
notifications_btn = TogglePushButton("Notifications", self, FIF.NOTIFICATION)
107
notifications_btn.setChecked(True)  # Default on
108
```
109

110
### Tool Buttons
111

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

114
```python { .api }
115
class ToolButton(QToolButton):
116
    def __init__(self, parent: QWidget = None): ...
117
    def __init__(self, icon: Union[QIcon, str, FluentIconBase], parent: QWidget = None): ...
118

119
class PrimaryToolButton(ToolButton): ...
120
class TransparentToolButton(ToolButton): ...
121
class ToggleToolButton(ToolButton): ...
122
class TransparentToggleToolButton(ToolButton): ...
123
```
124

125
**Usage Example:**
126
```python
127
from qfluentwidgets import ToolButton, PrimaryToolButton, FluentIcon as FIF
128

129
# Toolbar buttons
130
copy_btn = ToolButton(FIF.COPY, self)
131
paste_btn = ToolButton(FIF.PASTE, self)
132
primary_action = PrimaryToolButton(FIF.PLAY, self)
133

134
# Tool button with text
135
save_tool = ToolButton(FIF.SAVE, self)
136
save_tool.setText("Save")
137
save_tool.setToolButtonStyle(Qt.ToolButtonTextBesideIcon)
138
```
139

140
### Hyperlink Buttons
141

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

144
```python { .api }
145
class HyperlinkButton(QPushButton):
146
    def __init__(self, parent: QWidget = None): ...
147
    def __init__(self, url: str, text: str, parent: QWidget = None, icon: Union[QIcon, FluentIconBase, str] = None): ...
148
    
149
    def setUrl(self, url: str): ...
150
    def getUrl(self) -> str: ...
151
```
152

153
**Usage Example:**
154
```python
155
from qfluentwidgets import HyperlinkButton, FluentIcon as FIF
156

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

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

163
# Programmatic URL setting
164
link_btn = HyperlinkButton(self)
165
link_btn.setText("GitHub")
166
link_btn.setUrl("https://github.com/user/repo")
167
```
168

169
### Dropdown Buttons
170

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

173
```python { .api }
174
class DropDownPushButton(PushButton):
175
    def __init__(self, parent: QWidget = None): ...
176
    def __init__(self, text: str, parent: QWidget = None, icon: Union[QIcon, str, FluentIconBase] = None): ...
177
    def __init__(self, icon: QIcon, text: str, parent: QWidget = None): ...
178
    def __init__(self, icon: FluentIconBase, text: str, parent: QWidget = None): ...
179

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

184
class PrimaryDropDownPushButton(DropDownPushButton): ...
185
class PrimaryDropDownToolButton(DropDownToolButton): ...
186
class TransparentDropDownPushButton(DropDownPushButton): ...
187
class TransparentDropDownToolButton(DropDownToolButton): ...
188
```
189

190
**Usage Example:**
191
```python
192
from qfluentwidgets import DropDownPushButton, RoundMenu, Action, FluentIcon as FIF
193

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

197
# Create and assign menu
198
menu = RoundMenu(parent=self)
199
menu.addAction(Action(FIF.SAVE, "Save", self))
200
menu.addAction(Action(FIF.SAVE_AS, "Save As", self))
201
menu.addAction(Action(FIF.SAVE_COPY, "Save Copy", self))
202

203
save_dropdown.setMenu(menu)
204
```
205

206
### Split Buttons
207

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

210
```python { .api }
211
class SplitWidgetBase(QWidget): ...
212

213
class SplitPushButton(SplitWidgetBase):
214
    def __init__(self, parent: QWidget = None): ...
215
    def __init__(self, text: str, parent: QWidget = None, icon: Union[QIcon, str, FluentIconBase] = None): ...
216
    def __init__(self, icon: QIcon, text: str, parent: QWidget = None): ...
217
    def __init__(self, icon: FluentIconBase, text: str, parent: QWidget = None): ...
218

219
class SplitToolButton(SplitWidgetBase): ...
220
class PrimarySplitPushButton(SplitPushButton): ...
221
class PrimarySplitToolButton(SplitToolButton): ...
222
```
223

224
**Usage Example:**
225
```python
226
from qfluentwidgets import SplitPushButton, RoundMenu, Action, FluentIcon as FIF
227

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

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

234
# Create dropdown menu
235
menu = RoundMenu(parent=self)
236
menu.addAction(Action(FIF.DOCUMENT, "New Document", self))
237
menu.addAction(Action(FIF.FOLDER, "New Folder", self))
238
menu.addAction(Action(FIF.PROJECT, "New Project", self))
239

240
new_btn.setMenu(menu)
241
```
242

243
### Pill Buttons
244

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

247
```python { .api }
248
class PillPushButton(QPushButton):
249
    def __init__(self, parent: QWidget = None): ...
250
    def __init__(self, text: str, parent: QWidget = None, icon: Union[QIcon, str, FluentIconBase] = None): ...
251
    def __init__(self, icon: QIcon, text: str, parent: QWidget = None): ...
252
    def __init__(self, icon: FluentIconBase, text: str, parent: QWidget = None): ...
253

254
class PillToolButton(QToolButton):
255
    def __init__(self, parent: QWidget = None): ...
256
    def __init__(self, icon: Union[QIcon, str, FluentIconBase], parent: QWidget = None): ...
257
```
258

259
**Usage Example:**
260
```python
261
from qfluentwidgets import PillPushButton, PillToolButton, FluentIcon as FIF
262

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

267
# Pill tool button for compact spaces
268
pill_tool = PillToolButton(FIF.SETTING, self)
269
```
270

271
### Radio Buttons
272

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

275
```python { .api }
276
class RadioButton(QRadioButton):
277
    def __init__(self, parent: QWidget = None): ...
278
    def __init__(self, text: str, parent: QWidget = None): ...
279
```
280

281
**Usage Example:**
282
```python
283
from qfluentwidgets import RadioButton
284
from PyQt5.QtWidgets import QButtonGroup
285

286
# Create radio button group
287
size_group = QButtonGroup(self)
288

289
small_radio = RadioButton("Small", self)
290
medium_radio = RadioButton("Medium", self)  
291
large_radio = RadioButton("Large", self)
292

293
size_group.addButton(small_radio, 0)
294
size_group.addButton(medium_radio, 1)
295
size_group.addButton(large_radio, 2)
296

297
medium_radio.setChecked(True)  # Default selection
298
size_group.buttonClicked.connect(self.on_size_changed)
299
```
300

301
## Common Button Properties and Methods
302

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

305
```python
306
# Standard PyQt methods work with fluent styling
307
button.setText("New Text")
308
button.setEnabled(False)
309
button.setVisible(False)
310
button.resize(120, 32)
311

312
# Signal connections
313
button.clicked.connect(callback)
314
button.pressed.connect(on_press)
315
button.released.connect(on_release)
316

317
# For toggle buttons
318
toggle_btn.toggled.connect(on_toggle)
319
toggle_btn.setChecked(True)
320
```
321

322
### Switch Buttons
323

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

326
```python { .api }
327
class SwitchButton(QWidget):
328
    def __init__(self, parent=None, indicatorPos=IndicatorPosition.LEFT): ...
329
    def setChecked(self, checked: bool): ...
330
    def isChecked(self) -> bool: ...
331
    def setText(self, text: str): ...
332
    def text(self) -> str: ...
333
    def setIndicatorPosition(self, pos: IndicatorPosition): ...
334
    
335
    checkedChanged = pyqtSignal(bool)
336

337
class IndicatorPosition(Enum):
338
    LEFT = 0
339
    RIGHT = 1
340
```
341

342
**Usage Example:**
343
```python
344
from qfluentwidgets import SwitchButton, IndicatorPosition
345

346
# Basic switch
347
notifications_switch = SwitchButton(self)
348
notifications_switch.setText("Enable Notifications")
349
notifications_switch.setChecked(True)
350
notifications_switch.checkedChanged.connect(self.toggle_notifications)
351

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

357
def toggle_notifications(self, enabled):
358
    if enabled:
359
        print("Notifications enabled")
360
    else:
361
        print("Notifications disabled")
362
```
363

364
## Button Styling and Themes
365

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

368
```python
369
from qfluentwidgets import setThemeColor, FluentThemeColor
370

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

374
# Buttons automatically update their appearance
375
```