0
# Input Widgets
1

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

4
## Capabilities
5

6
### Button Widgets
7

8
Interactive button controls for triggering actions and navigation.
9

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

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

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

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

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

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

48
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):
49
    """
50
    Display button that downloads data as file when clicked.
51

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

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

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

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

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

88
### Basic Input Widgets
89

90
Simple input controls for boolean and text values.
91

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

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

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

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

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

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

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

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

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

149
### Text Input Widgets
150

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

153
```python { .api }
154
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"):
155
    """
156
    Display single-line text input widget.
157

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

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

177
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"):
178
    """
179
    Display multi-line text input widget.
180

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

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

200
### Number Input Widgets
201

202
Numeric input controls with validation and formatting.
203

204
```python { .api }
205
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"):
206
    """
207
    Display number input widget with validation and step controls.
208

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

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

229
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"):
230
    """
231
    Display slider widget for numeric input with visual feedback.
232

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

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

253
### Selection Widgets
254

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

257
```python { .api }
258
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"):
259
    """
260
    Display dropdown selectbox for single selection from options.
261

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

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

280
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"):
281
    """
282
    Display multi-selection widget for choosing multiple options.
283

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

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

303
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"):
304
    """
305
    Display radio buttons for single selection with all options visible.
306

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

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

326
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"):
327
    """
328
    Display slider for selecting from discrete options.
329

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

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

347
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"):
348
    """
349
    Display pill-shaped selection buttons for single or multiple selection.
350

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

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

369
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"):
370
    """
371
    Display segmented control widget for single or multiple selection.
372

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

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

392
### Date and Time Input
393

394
Specialized input widgets for temporal data.
395

396
```python { .api }
397
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"):
398
    """
399
    Display date picker widget for date selection.
400

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

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

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

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

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

440
### File and Media Input
441

442
Widgets for uploading files and capturing media input.
443

444
```python { .api }
445
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"):
446
    """
447
    Display file uploader widget for file selection and upload.
448

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

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

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

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

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

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

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

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

503
### Color Input
504

505
Widget for color selection with visual color picker.
506

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

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

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

528
### Form Controls
529

530
Special widgets for form submission and organization.
531

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

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

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

546
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):
547
    """
548
    Display form submit button that triggers form submission.
549

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

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