pypi-streamlit

1
# Input Widgets
2

3
Interactive widgets for user input including buttons, text inputs, selection widgets, file uploads, and form controls. These widgets enable user interaction and data collection in Streamlit applications.
4

5
## Capabilities
6

7
### Button Widgets
8

9
Interactive button controls for triggering actions and navigation.
10

11
```python { .api }
12
def button(label, key=None, help=None, on_click=None, args=None, kwargs=None, *, type="secondary", disabled=False, use_container_width=False, icon=None):
13
    """
14
    Display clickable button that returns True when clicked.
15

16
    Args:
17
        label (str): Button text label
18
        key (str, optional): Unique widget key for state management
19
        help (str, optional): Tooltip text
20
        on_click (callable, optional): Callback function when clicked
21
        args (tuple, optional): Arguments for on_click callback
22
        kwargs (dict, optional): Keyword arguments for on_click callback
23
        type (str): Button style ("primary", "secondary")
24
        disabled (bool): Whether button is disabled
25
        use_container_width (bool): Whether to use full container width
26
        icon (str, optional): Icon name or emoji
27

28
    Returns:
29
        bool: True if button was clicked in this run
30
    """
31

32
def link_button(label, url, *, help=None, disabled=False, use_container_width=False, type="secondary", icon=None):
33
    """
34
    Display button that opens external link in new tab.
35

36
    Args:
37
        label (str): Button text label
38
        url (str): URL to open when clicked
39
        help (str, optional): Tooltip text
40
        disabled (bool): Whether button is disabled
41
        use_container_width (bool): Whether to use full container width
42
        type (str): Button style ("primary", "secondary")
43
        icon (str, optional): Icon name or emoji
44

45
    Returns:
46
        bool: True if button was clicked in this run
47
    """
48

49
def download_button(label, data, file_name=None, mime=None, key=None, help=None, on_click=None, args=None, kwargs=None, *, disabled=False, use_container_width=False, type="secondary", icon=None):
50
    """
51
    Display button that downloads data as file when clicked.
52

53
    Args:
54
        label (str): Button text label
55
        data: Data to download (bytes, str, or file-like object)
56
        file_name (str, optional): Default filename for download
57
        mime (str, optional): MIME type of the data
58
        key (str, optional): Unique widget key for state management
59
        help (str, optional): Tooltip text
60
        on_click (callable, optional): Callback function when clicked
61
        args (tuple, optional): Arguments for on_click callback
62
        kwargs (dict, optional): Keyword arguments for on_click callback
63
        disabled (bool): Whether button is disabled
64
        use_container_width (bool): Whether to use full container width
65
        type (str): Button style ("primary", "secondary")
66
        icon (str, optional): Icon name or emoji
67

68
    Returns:
69
        bool: True if button was clicked in this run
70
    """
71

72
def page_link(page, *, label=None, icon=None, help=None, disabled=False, use_container_width=False):
73
    """
74
    Display button that navigates to another page in multi-page app.
75

76
    Args:
77
        page (str or Page): Page name or Page object to navigate to
78
        label (str, optional): Button label (uses page title if not provided)
79
        icon (str, optional): Icon name or emoji
80
        help (str, optional): Tooltip text
81
        disabled (bool): Whether button is disabled
82
        use_container_width (bool): Whether to use full container width
83

84
    Returns:
85
        bool: True if button was clicked in this run
86
    """
87
```
88

89
### Basic Input Widgets
90

91
Simple input controls for boolean and text values.
92

93
```python { .api }
94
def checkbox(label, value=False, key=None, help=None, on_change=None, args=None, kwargs=None, *, disabled=False, label_visibility="visible"):
95
    """
96
    Display checkbox for boolean input.
97

98
    Args:
99
        label (str): Widget label
100
        value (bool): Initial/default value
101
        key (str, optional): Unique widget key for state management
102
        help (str, optional): Tooltip text
103
        on_change (callable, optional): Callback when value changes
104
        args (tuple, optional): Arguments for on_change callback
105
        kwargs (dict, optional): Keyword arguments for on_change callback
106
        disabled (bool): Whether widget is disabled
107
        label_visibility (str): Label visibility ("visible", "hidden", "collapsed")
108

109
    Returns:
110
        bool: Current checkbox state
111
    """
112

113
def toggle(label, value=False, key=None, help=None, on_change=None, args=None, kwargs=None, *, disabled=False, label_visibility="visible"):
114
    """
115
    Display toggle switch for boolean input.
116

117
    Args:
118
        label (str): Widget label
119
        value (bool): Initial/default value
120
        key (str, optional): Unique widget key for state management
121
        help (str, optional): Tooltip text
122
        on_change (callable, optional): Callback when value changes
123
        args (tuple, optional): Arguments for on_change callback
124
        kwargs (dict, optional): Keyword arguments for on_change callback
125
        disabled (bool): Whether widget is disabled
126
        label_visibility (str): Label visibility ("visible", "hidden", "collapsed")
127

128
    Returns:
129
        bool: Current toggle state
130
    """
131

132
def feedback(options, key=None, help=None, on_change=None, args=None, kwargs=None, *, disabled=False):
133
    """
134
    Display feedback widget with thumbs up/down or custom options.
135

136
    Args:
137
        options (str or dict): Feedback options ("thumbs", "faces", or custom dict)
138
        key (str, optional): Unique widget key for state management
139
        help (str, optional): Tooltip text
140
        on_change (callable, optional): Callback when value changes
141
        args (tuple, optional): Arguments for on_change callback
142
        kwargs (dict, optional): Keyword arguments for on_change callback
143
        disabled (bool): Whether widget is disabled
144

145
    Returns:
146
        dict or None: Selected feedback option
147
    """
148
```
149

150
### Text Input Widgets
151

152
Text input controls for single-line and multi-line text entry.
153

154
```python { .api }
155
def text_input(label, value="", max_chars=None, key=None, type="default", help=None, autocomplete=None, on_change=None, args=None, kwargs=None, *, placeholder=None, disabled=False, label_visibility="visible"):
156
    """
157
    Display single-line text input widget.
158

159
    Args:
160
        label (str): Widget label
161
        value (str): Initial/default text value
162
        max_chars (int, optional): Maximum number of characters allowed
163
        key (str, optional): Unique widget key for state management
164
        type (str): Input type ("default" or "password")
165
        help (str, optional): Tooltip text
166
        autocomplete (str, optional): HTML autocomplete attribute
167
        on_change (callable, optional): Callback when value changes
168
        args (tuple, optional): Arguments for on_change callback
169
        kwargs (dict, optional): Keyword arguments for on_change callback
170
        placeholder (str, optional): Placeholder text when empty
171
        disabled (bool): Whether widget is disabled
172
        label_visibility (str): Label visibility ("visible", "hidden", "collapsed")
173

174
    Returns:
175
        str: Current text input value
176
    """
177

178
def text_area(label, value="", height=None, max_chars=None, key=None, help=None, on_change=None, args=None, kwargs=None, *, placeholder=None, disabled=False, label_visibility="visible"):
179
    """
180
    Display multi-line text input widget.
181

182
    Args:
183
        label (str): Widget label
184
        value (str): Initial/default text value
185
        height (int, optional): Height in pixels
186
        max_chars (int, optional): Maximum number of characters allowed
187
        key (str, optional): Unique widget key for state management
188
        help (str, optional): Tooltip text
189
        on_change (callable, optional): Callback when value changes
190
        args (tuple, optional): Arguments for on_change callback
191
        kwargs (dict, optional): Keyword arguments for on_change callback
192
        placeholder (str, optional): Placeholder text when empty
193
        disabled (bool): Whether widget is disabled
194
        label_visibility (str): Label visibility ("visible", "hidden", "collapsed")
195

196
    Returns:
197
        str: Current text area value
198
    """
199
```
200

201
### Number Input Widgets
202

203
Numeric input controls with validation and formatting.
204

205
```python { .api }
206
def number_input(label, min_value=None, max_value=None, value=None, step=None, format=None, key=None, help=None, on_change=None, args=None, kwargs=None, *, placeholder=None, disabled=False, label_visibility="visible"):
207
    """
208
    Display number input widget with validation and step controls.
209

210
    Args:
211
        label (str): Widget label
212
        min_value (float, optional): Minimum allowed value
213
        max_value (float, optional): Maximum allowed value
214
        value (float, optional): Initial/default value
215
        step (float, optional): Step size for increment/decrement
216
        format (str, optional): Printf-style format string
217
        key (str, optional): Unique widget key for state management
218
        help (str, optional): Tooltip text
219
        on_change (callable, optional): Callback when value changes
220
        args (tuple, optional): Arguments for on_change callback
221
        kwargs (dict, optional): Keyword arguments for on_change callback
222
        placeholder (str, optional): Placeholder text when empty
223
        disabled (bool): Whether widget is disabled
224
        label_visibility (str): Label visibility ("visible", "hidden", "collapsed")
225

226
    Returns:
227
        float or int: Current number input value
228
    """
229

230
def slider(label, min_value=None, max_value=None, value=None, step=None, format=None, key=None, help=None, on_change=None, args=None, kwargs=None, *, disabled=False, label_visibility="visible"):
231
    """
232
    Display slider widget for numeric input with visual feedback.
233

234
    Args:
235
        label (str): Widget label
236
        min_value (float, optional): Minimum slider value
237
        max_value (float, optional): Maximum slider value
238
        value (float or tuple, optional): Initial value or range for range slider
239
        step (float, optional): Step size between values
240
        format (str, optional): Printf-style format string for display
241
        key (str, optional): Unique widget key for state management
242
        help (str, optional): Tooltip text
243
        on_change (callable, optional): Callback when value changes
244
        args (tuple, optional): Arguments for on_change callback
245
        kwargs (dict, optional): Keyword arguments for on_change callback
246
        disabled (bool): Whether widget is disabled
247
        label_visibility (str): Label visibility ("visible", "hidden", "collapsed")
248

249
    Returns:
250
        float or tuple: Current slider value or range
251
    """
252
```
253

254
### Selection Widgets
255

256
Widgets for selecting from predefined options with various interaction modes.
257

258
```python { .api }
259
def selectbox(label, options, index=0, format_func=str, key=None, help=None, on_change=None, args=None, kwargs=None, *, placeholder="Choose an option", disabled=False, label_visibility="visible"):
260
    """
261
    Display dropdown selectbox for single selection from options.
262

263
    Args:
264
        label (str): Widget label
265
        options (list): Available options to choose from
266
        index (int): Index of default selected option
267
        format_func (callable): Function to format option display
268
        key (str, optional): Unique widget key for state management
269
        help (str, optional): Tooltip text
270
        on_change (callable, optional): Callback when selection changes
271
        args (tuple, optional): Arguments for on_change callback
272
        kwargs (dict, optional): Keyword arguments for on_change callback
273
        placeholder (str): Placeholder text when no selection
274
        disabled (bool): Whether widget is disabled
275
        label_visibility (str): Label visibility ("visible", "hidden", "collapsed")
276

277
    Returns:
278
        Any: Currently selected option
279
    """
280

281
def multiselect(label, options, default=None, format_func=str, key=None, help=None, on_change=None, args=None, kwargs=None, *, max_selections=None, placeholder="Choose options", disabled=False, label_visibility="visible"):
282
    """
283
    Display multi-selection widget for choosing multiple options.
284

285
    Args:
286
        label (str): Widget label
287
        options (list): Available options to choose from
288
        default (list, optional): Default selected options
289
        format_func (callable): Function to format option display
290
        key (str, optional): Unique widget key for state management
291
        help (str, optional): Tooltip text
292
        on_change (callable, optional): Callback when selection changes
293
        args (tuple, optional): Arguments for on_change callback
294
        kwargs (dict, optional): Keyword arguments for on_change callback
295
        max_selections (int, optional): Maximum number of selections allowed
296
        placeholder (str): Placeholder text when no selections
297
        disabled (bool): Whether widget is disabled
298
        label_visibility (str): Label visibility ("visible", "hidden", "collapsed")
299

300
    Returns:
301
        list: Currently selected options
302
    """
303

304
def radio(label, options, index=0, format_func=str, key=None, help=None, on_change=None, args=None, kwargs=None, *, captions=None, disabled=False, horizontal=False, label_visibility="visible"):
305
    """
306
    Display radio buttons for single selection with all options visible.
307

308
    Args:
309
        label (str): Widget label
310
        options (list): Available options to choose from
311
        index (int): Index of default selected option
312
        format_func (callable): Function to format option display
313
        key (str, optional): Unique widget key for state management
314
        help (str, optional): Tooltip text
315
        on_change (callable, optional): Callback when selection changes
316
        args (tuple, optional): Arguments for on_change callback
317
        kwargs (dict, optional): Keyword arguments for on_change callback
318
        captions (list, optional): Caption text for each option
319
        disabled (bool): Whether widget is disabled
320
        horizontal (bool): Whether to layout options horizontally
321
        label_visibility (str): Label visibility ("visible", "hidden", "collapsed")
322

323
    Returns:
324
        Any: Currently selected option
325
    """
326

327
def select_slider(label, options, value=None, format_func=str, key=None, help=None, on_change=None, args=None, kwargs=None, *, disabled=False, label_visibility="visible"):
328
    """
329
    Display slider for selecting from discrete options.
330

331
    Args:
332
        label (str): Widget label
333
        options (list): Available options in order
334
        value (any or tuple, optional): Initial value or range
335
        format_func (callable): Function to format option display
336
        key (str, optional): Unique widget key for state management
337
        help (str, optional): Tooltip text
338
        on_change (callable, optional): Callback when selection changes
339
        args (tuple, optional): Arguments for on_change callback
340
        kwargs (dict, optional): Keyword arguments for on_change callback
341
        disabled (bool): Whether widget is disabled
342
        label_visibility (str): Label visibility ("visible", "hidden", "collapsed")
343

344
    Returns:
345
        Any or tuple: Currently selected option or range
346
    """
347

348
def pills(label, options, selection_mode="single", default=None, format_func=str, key=None, help=None, on_change=None, args=None, kwargs=None, *, disabled=False, label_visibility="visible"):
349
    """
350
    Display pill-shaped selection buttons for single or multiple selection.
351

352
    Args:
353
        label (str): Widget label
354
        options (list): Available options to choose from
355
        selection_mode (str): Selection mode ("single" or "multi")
356
        default: Default selected option(s)
357
        format_func (callable): Function to format option display
358
        key (str, optional): Unique widget key for state management
359
        help (str, optional): Tooltip text
360
        on_change (callable, optional): Callback when selection changes
361
        args (tuple, optional): Arguments for on_change callback
362
        kwargs (dict, optional): Keyword arguments for on_change callback
363
        disabled (bool): Whether widget is disabled
364
        label_visibility (str): Label visibility ("visible", "hidden", "collapsed")
365

366
    Returns:
367
        Any or list: Currently selected option(s)
368
    """
369

370
def segmented_control(label, options, selection_mode="single", default=None, format_func=str, key=None, help=None, on_change=None, args=None, kwargs=None, *, disabled=False, label_visibility="visible"):
371
    """
372
    Display segmented control widget for single or multiple selection.
373

374
    Args:
375
        label (str): Widget label
376
        options (list): Available options to choose from
377
        selection_mode (str): Selection mode ("single" or "multi")
378
        default: Default selected option(s)
379
        format_func (callable): Function to format option display
380
        key (str, optional): Unique widget key for state management
381
        help (str, optional): Tooltip text
382
        on_change (callable, optional): Callback when selection changes
383
        args (tuple, optional): Arguments for on_change callback
384
        kwargs (dict, optional): Keyword arguments for on_change callback
385
        disabled (bool): Whether widget is disabled
386
        label_visibility (str): Label visibility ("visible", "hidden", "collapsed")
387

388
    Returns:
389
        Any or list: Currently selected option(s)
390
    """
391
```
392

393
### Date and Time Input
394

395
Specialized input widgets for temporal data.
396

397
```python { .api }
398
def date_input(label, value=None, min_value=None, max_value=None, key=None, help=None, on_change=None, args=None, kwargs=None, *, format="YYYY/MM/DD", disabled=False, label_visibility="visible"):
399
    """
400
    Display date picker widget for date selection.
401

402
    Args:
403
        label (str): Widget label
404
        value (datetime.date, optional): Initial date value
405
        min_value (datetime.date, optional): Minimum selectable date
406
        max_value (datetime.date, optional): Maximum selectable date
407
        key (str, optional): Unique widget key for state management
408
        help (str, optional): Tooltip text
409
        on_change (callable, optional): Callback when date changes
410
        args (tuple, optional): Arguments for on_change callback
411
        kwargs (dict, optional): Keyword arguments for on_change callback
412
        format (str): Date format for display
413
        disabled (bool): Whether widget is disabled
414
        label_visibility (str): Label visibility ("visible", "hidden", "collapsed")
415

416
    Returns:
417
        datetime.date: Selected date
418
    """
419

420
def time_input(label, value=None, key=None, help=None, on_change=None, args=None, kwargs=None, *, step=900, disabled=False, label_visibility="visible"):
421
    """
422
    Display time picker widget for time selection.
423

424
    Args:
425
        label (str): Widget label
426
        value (datetime.time, optional): Initial time value
427
        key (str, optional): Unique widget key for state management
428
        help (str, optional): Tooltip text
429
        on_change (callable, optional): Callback when time changes
430
        args (tuple, optional): Arguments for on_change callback
431
        kwargs (dict, optional): Keyword arguments for on_change callback
432
        step (int): Step size in seconds (default 15 minutes)
433
        disabled (bool): Whether widget is disabled
434
        label_visibility (str): Label visibility ("visible", "hidden", "collapsed")
435

436
    Returns:
437
        datetime.time: Selected time
438
    """
439
```
440

441
### File and Media Input
442

443
Widgets for uploading files and capturing media input.
444

445
```python { .api }
446
def file_uploader(label, type=None, accept_multiple_files=False, key=None, help=None, on_change=None, args=None, kwargs=None, *, disabled=False, label_visibility="visible"):
447
    """
448
    Display file uploader widget for file selection and upload.
449

450
    Args:
451
        label (str): Widget label
452
        type (str or list, optional): Accepted file extensions
453
        accept_multiple_files (bool): Whether to allow multiple file selection
454
        key (str, optional): Unique widget key for state management
455
        help (str, optional): Tooltip text
456
        on_change (callable, optional): Callback when files are uploaded
457
        args (tuple, optional): Arguments for on_change callback
458
        kwargs (dict, optional): Keyword arguments for on_change callback
459
        disabled (bool): Whether widget is disabled
460
        label_visibility (str): Label visibility ("visible", "hidden", "collapsed")
461

462
    Returns:
463
        UploadedFile or list or None: Uploaded file(s) or None if no upload
464
    """
465

466
def camera_input(label, key=None, help=None, on_change=None, args=None, kwargs=None, *, disabled=False, label_visibility="visible"):
467
    """
468
    Display camera input widget for taking photos.
469

470
    Args:
471
        label (str): Widget label
472
        key (str, optional): Unique widget key for state management
473
        help (str, optional): Tooltip text
474
        on_change (callable, optional): Callback when photo is taken
475
        args (tuple, optional): Arguments for on_change callback
476
        kwargs (dict, optional): Keyword arguments for on_change callback
477
        disabled (bool): Whether widget is disabled
478
        label_visibility (str): Label visibility ("visible", "hidden", "collapsed")
479

480
    Returns:
481
        UploadedFile or None: Captured image or None if no photo taken
482
    """
483

484
def audio_input(label, key=None, help=None, on_change=None, args=None, kwargs=None, *, disabled=False, label_visibility="visible", max_duration=None):
485
    """
486
    Display audio input widget for recording audio.
487

488
    Args:
489
        label (str): Widget label
490
        key (str, optional): Unique widget key for state management
491
        help (str, optional): Tooltip text
492
        on_change (callable, optional): Callback when audio is recorded
493
        args (tuple, optional): Arguments for on_change callback
494
        kwargs (dict, optional): Keyword arguments for on_change callback
495
        disabled (bool): Whether widget is disabled
496
        label_visibility (str): Label visibility ("visible", "hidden", "collapsed")
497
        max_duration (int, optional): Maximum recording duration in seconds
498

499
    Returns:
500
        UploadedFile or None: Recorded audio or None if no recording
501
    """
502
```
503

504
### Color Input
505

506
Widget for color selection with visual color picker.
507

508
```python { .api }
509
def color_picker(label, value="#000000", key=None, help=None, on_change=None, args=None, kwargs=None, *, disabled=False, label_visibility="visible"):
510
    """
511
    Display color picker widget for color selection.
512

513
    Args:
514
        label (str): Widget label
515
        value (str): Initial color value as hex string
516
        key (str, optional): Unique widget key for state management
517
        help (str, optional): Tooltip text
518
        on_change (callable, optional): Callback when color changes
519
        args (tuple, optional): Arguments for on_change callback
520
        kwargs (dict, optional): Keyword arguments for on_change callback
521
        disabled (bool): Whether widget is disabled
522
        label_visibility (str): Label visibility ("visible", "hidden", "collapsed")
523

524
    Returns:
525
        str: Selected color as hex string
526
    """
527
```
528

529
### Form Controls
530

531
Special widgets for form submission and organization.
532

533
```python { .api }
534
def form(key, *, clear_on_submit=False, border=True):
535
    """
536
    Create form container that batches widget interactions until submit.
537

538
    Args:
539
        key (str): Unique form identifier
540
        clear_on_submit (bool): Whether to clear form values on submit
541
        border (bool): Whether to show form border
542

543
    Returns:
544
        DeltaGenerator: Form container context manager
545
    """
546

547
def form_submit_button(label, key=None, help=None, on_click=None, args=None, kwargs=None, *, disabled=False, use_container_width=False, type="secondary", icon=None):
548
    """
549
    Display form submit button that triggers form submission.
550

551
    Args:
552
        label (str): Button text label
553
        key (str, optional): Unique widget key for state management
554
        help (str, optional): Tooltip text
555
        on_click (callable, optional): Callback function when clicked
556
        args (tuple, optional): Arguments for on_click callback
557
        kwargs (dict, optional): Keyword arguments for on_click callback
558
        disabled (bool): Whether button is disabled
559
        use_container_width (bool): Whether to use full container width
560
        type (str): Button style ("primary", "secondary")
561
        icon (str, optional): Icon name or emoji
562

563
    Returns:
564
        bool: True if form was submitted in this run
565
    """
566
```