0
# Widgets
1

2
Interactive UI components for building data applications and dashboards. Bokeh provides a comprehensive widget system with 40+ widget types including buttons, inputs, tables, sliders, and specialized controls that enable rich user interactions with Python callbacks.
3

4
## Capabilities
5

6
### Buttons and Controls
7

8
Interactive buttons and toggle controls for triggering actions and state changes.
9

10
```python { .api }
11
class Button:
12
    """Standard push button widget."""
13
    def __init__(self, label="Button", button_type="default", **kwargs):
14
        """
15
        Parameters:
16
        - label: str, button text
17
        - button_type: str, button style ('default', 'primary', 'success', 'warning', 'danger', 'light')
18
        """
19

20
class Toggle:
21
    """Toggle button that maintains on/off state."""
22
    def __init__(self, label="Toggle", active=False, button_type="default", **kwargs):
23
        """
24
        Parameters:
25
        - label: str, button text
26
        - active: bool, initial toggle state
27
        - button_type: str, button style
28
        """
29

30
class Dropdown:
31
    """Dropdown menu with selectable options."""
32
    def __init__(self, label="Dropdown", button_type="default", menu=None, **kwargs):
33
        """
34
        Parameters:
35
        - label: str, dropdown label
36
        - button_type: str, button style
37
        - menu: list, menu items as (label, value) tuples or strings
38
        """
39
```
40

41
### Input Widgets
42

43
Text and numeric input controls for data entry and parameter configuration.
44

45
```python { .api }
46
class TextInput:
47
    """Single-line text input field."""
48
    def __init__(self, value="", title=None, placeholder="", **kwargs):
49
        """
50
        Parameters:
51
        - value: str, initial text value
52
        - title: str, input label
53
        - placeholder: str, placeholder text
54
        """
55

56
class TextAreaInput:
57
    """Multi-line text input area."""
58
    def __init__(self, value="", title=None, placeholder="", rows=2, **kwargs):
59
        """
60
        Parameters:
61
        - value: str, initial text content
62
        - title: str, input label
63
        - placeholder: str, placeholder text
64
        - rows: int, number of visible text rows
65
        """
66

67
class NumericInput:
68
    """Numeric input with validation and formatting."""
69
    def __init__(self, value=None, low=None, high=None, title=None, format=None, **kwargs):
70
        """
71
        Parameters:
72
        - value: float, initial numeric value
73
        - low: float, minimum allowed value
74
        - high: float, maximum allowed value
75
        - title: str, input label
76
        - format: str, number format pattern
77
        """
78

79
class PasswordInput:
80
    """Password input field with hidden text."""
81
    def __init__(self, value="", title=None, placeholder="", **kwargs):
82
        """
83
        Parameters:
84
        - value: str, initial password value
85
        - title: str, input label
86
        - placeholder: str, placeholder text
87
        """
88

89
class FileInput:
90
    """File upload input widget."""
91
    def __init__(self, accept="", multiple=False, **kwargs):
92
        """
93
        Parameters:
94
        - accept: str, accepted file types (MIME types or extensions)
95
        - multiple: bool, allow multiple file selection
96
        """
97
```
98

99
### Selection Widgets
100

101
Widgets for selecting from predefined options and ranges.
102

103
```python { .api }
104
class Select:
105
    """Dropdown selection widget."""
106
    def __init__(self, value=None, title=None, options=None, **kwargs):
107
        """
108
        Parameters:
109
        - value: str, selected option value
110
        - title: str, selection label
111
        - options: list, available options as strings or (label, value) tuples
112
        """
113

114
class MultiSelect:
115
    """Multi-selection dropdown widget."""
116
    def __init__(self, value=None, title=None, options=None, size=4, **kwargs):
117
        """
118
        Parameters:
119
        - value: list, selected option values
120
        - title: str, selection label
121
        - options: list, available options
122
        - size: int, visible option count
123
        """
124

125
class AutocompleteInput:
126
    """Text input with autocomplete suggestions."""
127
    def __init__(self, value="", title=None, completions=None, **kwargs):
128
        """
129
        Parameters:
130
        - value: str, initial input value
131
        - title: str, input label
132
        - completions: list, available completion strings
133
        """
134
```
135

136
### Group Widgets
137

138
Grouped selection controls for multiple related options.
139

140
```python { .api }
141
class CheckboxGroup:
142
    """Group of checkbox options."""
143
    def __init__(self, labels=None, active=None, inline=False, **kwargs):
144
        """
145
        Parameters:
146
        - labels: list, checkbox labels
147
        - active: list, indices of initially active checkboxes
148
        - inline: bool, horizontal layout if True
149
        """
150

151
class RadioGroup:
152
    """Group of radio button options."""
153
    def __init__(self, labels=None, active=None, inline=False, **kwargs):
154
        """
155
        Parameters:
156
        - labels: list, radio button labels
157
        - active: int, index of initially active radio button
158
        - inline: bool, horizontal layout if True
159
        """
160

161
class CheckboxButtonGroup:
162
    """Group of toggle buttons behaving like checkboxes."""
163
    def __init__(self, labels=None, active=None, **kwargs):
164
        """
165
        Parameters:
166
        - labels: list, button labels
167
        - active: list, indices of initially active buttons
168
        """
169

170
class RadioButtonGroup:
171
    """Group of toggle buttons behaving like radio buttons."""
172
    def __init__(self, labels=None, active=None, **kwargs):
173
        """
174
        Parameters:
175
        - labels: list, button labels
176
        - active: int, index of initially active button
177
        """
178
```
179

180
### Slider Widgets
181

182
Range and value selection through draggable slider controls.
183

184
```python { .api }
185
class Slider:
186
    """Single-value slider widget."""
187
    def __init__(self, start=0, end=1, value=0.5, step=0.1, title=None, **kwargs):
188
        """
189
        Parameters:
190
        - start: float, minimum slider value
191
        - end: float, maximum slider value
192
        - value: float, initial slider value
193
        - step: float, increment between values
194
        - title: str, slider label
195
        """
196

197
class RangeSlider:
198
    """Dual-handle slider for selecting value ranges."""
199
    def __init__(self, start=0, end=1, value=(0.1, 0.9), step=0.1, title=None, **kwargs):
200
        """
201
        Parameters:
202
        - start: float, minimum range value
203
        - end: float, maximum range value
204
        - value: tuple, initial range as (low, high)
205
        - step: float, increment between values
206
        - title: str, slider label
207
        """
208

209
class DateSlider:
210
    """Slider for selecting dates."""
211
    def __init__(self, start=None, end=None, value=None, step=1, title=None, **kwargs):
212
        """
213
        Parameters:
214
        - start: date, minimum date value
215
        - end: date, maximum date value
216
        - value: date, initial selected date
217
        - step: int, step size in days
218
        - title: str, slider label
219
        """
220

221
class DateRangeSlider:
222
    """Dual-handle slider for selecting date ranges."""
223
    def __init__(self, start=None, end=None, value=None, step=1, title=None, **kwargs):
224
        """
225
        Parameters:
226
        - start: date, minimum date value
227
        - end: date, maximum date value
228
        - value: tuple, initial date range as (start_date, end_date)
229
        - step: int, step size in days
230
        - title: str, slider label
231
        """
232
```
233

234
### Date and Time Pickers
235

236
Specialized widgets for date and time selection with calendar interfaces.
237

238
```python { .api }
239
class DatePicker:
240
    """Calendar-based date picker widget."""
241
    def __init__(self, value=None, min_date=None, max_date=None, title=None, **kwargs):
242
        """
243
        Parameters:
244
        - value: date, initial selected date
245
        - min_date: date, minimum selectable date
246
        - max_date: date, maximum selectable date
247
        - title: str, picker label
248
        """
249

250
class DateRangePicker:
251
    """Calendar-based date range picker widget."""
252
    def __init__(self, value=None, min_date=None, max_date=None, title=None, **kwargs):
253
        """
254
        Parameters:
255
        - value: tuple, initial date range as (start_date, end_date)
256
        - min_date: date, minimum selectable date
257
        - max_date: date, maximum selectable date
258
        - title: str, picker label
259
        """
260

261
class TimePicker:
262
    """Time selection widget with hour/minute controls."""
263
    def __init__(self, value=None, min_time=None, max_time=None, title=None, **kwargs):
264
        """
265
        Parameters:
266
        - value: time, initial selected time
267
        - min_time: time, minimum selectable time
268
        - max_time: time, maximum selectable time
269
        - title: str, picker label
270
        """
271

272
class DatetimePicker:
273
    """Combined date and time picker widget."""
274
    def __init__(self, value=None, min_date=None, max_date=None, title=None, **kwargs):
275
        """
276
        Parameters:
277
        - value: datetime, initial selected datetime
278
        - min_date: date, minimum selectable date
279
        - max_date: date, maximum selectable date
280
        - title: str, picker label
281
        """
282
```
283

284
### Data Tables
285

286
Interactive tabular data display with sorting, filtering, and editing capabilities.
287

288
```python { .api }
289
class DataTable:
290
    """Interactive data table widget."""
291
    def __init__(self, source=None, columns=None, width=600, height=400, **kwargs):
292
        """
293
        Parameters:
294
        - source: ColumnDataSource, table data source
295
        - columns: list, TableColumn objects defining columns
296
        - width: int, table width in pixels
297
        - height: int, table height in pixels
298
        """
299

300
class TableColumn:
301
    """Column definition for data tables."""
302
    def __init__(self, field=None, title=None, width=None, formatter=None, editor=None, **kwargs):
303
        """
304
        Parameters:
305
        - field: str, data field name
306
        - title: str, column header text
307
        - width: int, column width in pixels
308
        - formatter: CellFormatter, cell display formatter
309
        - editor: CellEditor, cell editor for inline editing
310
        """
311
```
312

313
### Markup Widgets
314

315
Widgets for displaying formatted text and content.
316

317
```python { .api }
318
class Div:
319
    """HTML div element for rich text display."""
320
    def __init__(self, text="", width=None, height=None, **kwargs):
321
        """
322
        Parameters:
323
        - text: str, HTML content to display
324
        - width: int, div width in pixels
325
        - height: int, div height in pixels
326
        """
327

328
class Paragraph:
329
    """Paragraph text display widget."""
330
    def __init__(self, text="", width=None, height=None, **kwargs):
331
        """
332
        Parameters:
333
        - text: str, paragraph text content
334
        - width: int, paragraph width in pixels
335
        - height: int, paragraph height in pixels
336
        """
337

338
class PreText:
339
    """Preformatted text display widget."""
340
    def __init__(self, text="", width=None, height=None, **kwargs):
341
        """
342
        Parameters:
343
        - text: str, preformatted text content
344
        - width: int, text area width in pixels
345
        - height: int, text area height in pixels
346
        """
347
```
348

349
## Usage Examples
350

351
### Basic Widget Usage
352

353
```python
354
from bokeh.models.widgets import Button, TextInput, Select
355
from bokeh.io import show
356
from bokeh.layouts import column
357

358
# Create widgets
359
text_input = TextInput(title="Enter text:", placeholder="Type here...")
360
select_widget = Select(title="Choose option:", value="option1", 
361
                      options=["option1", "option2", "option3"])
362
button = Button(label="Submit", button_type="primary")
363

364
# Arrange in layout
365
layout = column(text_input, select_widget, button)
366
show(layout)
367
```
368

369
### Interactive Dashboard with Callbacks
370

371
```python
372
from bokeh.models.widgets import Slider, Select
373
from bokeh.plotting import figure, show
374
from bokeh.layouts import column, row
375
from bokeh.models import ColumnDataSource
376

377
# Create data source
378
source = ColumnDataSource(data=dict(x=[1, 2, 3, 4, 5], y=[2, 5, 3, 8, 7]))
379

380
# Create plot
381
plot = figure(width=400, height=400)
382
plot.circle('x', 'y', source=source, size=10)
383

384
# Create widgets
385
x_slider = Slider(title="X Multiplier", start=0.1, end=2.0, value=1.0, step=0.1)
386
y_select = Select(title="Y Transform", value="linear", options=["linear", "square", "sqrt"])
387

388
# Layout
389
layout = column(row(x_slider, y_select), plot)
390
show(layout)
391
```
392

393
## Common Data Types
394

395
```python { .api }
396
# Widget-specific types
397
MenuItemLike = Union[str, Tuple[str, str], None]  # Menu item specification
398
OptionsLike = Union[List[str], List[Tuple[str, str]]]  # Widget options
399
DateLike = Union[date, datetime, str]  # Date specification
400
TimeLike = Union[time, datetime, str]  # Time specification
401

402
# Table-related types
403
class CellFormatter:
404
    """Base formatter for table cells."""
405

406
class CellEditor:
407
    """Base editor for table cells."""
408

409
class NumberFormatter(CellFormatter):
410
    """Numeric cell formatter."""
411
    def __init__(self, format="0,0", **kwargs): ...
412

413
class StringFormatter(CellFormatter):
414
    """String cell formatter."""
415
    def __init__(self, font_style="normal", **kwargs): ...
416

417
class DateFormatter(CellFormatter):
418
    """Date cell formatter."""
419
    def __init__(self, format="yy-mm-dd", **kwargs): ...
420
```