pypi-streamlit

1
# Input Widgets
2

3
Interactive form controls for user input. These widgets enable user interaction by capturing clicks, text input, selections, and file uploads. All widgets return values that can be used to control application flow and data processing.
4

5
## Capabilities
6

7
### Buttons and Actions
8

9
Trigger actions and downloads through button interactions.
10

11
```python { .api }
12
def button(label: str, key: str = None, help: str = None, on_click=None, args=None, kwargs=None, type: str = "secondary", disabled: bool = False, use_container_width: bool = False) -> bool:
13
    """
14
    Display a button widget that returns True when clicked.
15
    
16
    Parameters:
17
    - label: Text displayed on the button
18
    - key: Unique key for the widget
19
    - help: Tooltip text shown on hover
20
    - on_click: Callback function executed on click
21
    - args: Arguments passed to callback function
22
    - kwargs: Keyword arguments passed to callback function
23
    - type: Button type ("primary" or "secondary")
24
    - disabled: Whether the button is disabled
25
    - use_container_width: Whether to use full container width
26
    
27
    Returns:
28
    bool: True if button was clicked in this run, False otherwise
29
    """
30

31
def download_button(label: str, data, file_name: str = None, mime: str = None, key: str = None, help: str = None, on_click=None, args=None, kwargs=None, type: str = "secondary", disabled: bool = False, use_container_width: bool = False) -> bool:
32
    """
33
    Display a download button that triggers file download.
34
    
35
    Parameters:
36
    - label: Text displayed on the button
37
    - data: Raw data, string, or bytes to download
38
    - file_name: Name for the downloaded file
39
    - mime: MIME type of the file
40
    - key: Unique key for the widget
41
    - help: Tooltip text shown on hover
42
    - on_click: Callback function executed on click
43
    - args: Arguments passed to callback function
44
    - kwargs: Keyword arguments passed to callback function
45
    - type: Button type ("primary" or "secondary")
46
    - disabled: Whether the button is disabled
47
    - use_container_width: Whether to use full container width
48
    
49
    Returns:
50
    bool: True if button was clicked in this run, False otherwise
51
    """
52
```
53

54
#### Usage Example
55

56
```python
57
import streamlit as st
58

59
# Simple button
60
if st.button("Click me!"):
61
    st.write("Button was clicked!")
62

63
# Download button
64
csv_data = "Name,Age\nAlice,25\nBob,30"
65
st.download_button(
66
    label="Download CSV",
67
    data=csv_data,
68
    file_name="data.csv",
69
    mime="text/csv"
70
)
71
```
72

73
### Boolean Input
74

75
Capture boolean (true/false) user selections.
76

77
```python { .api }
78
def checkbox(label: str, value: bool = False, key: str = None, help: str = None, on_change=None, args=None, kwargs=None) -> bool:
79
    """
80
    Display a checkbox widget.
81
    
82
    Parameters:
83
    - label: Text displayed next to the checkbox
84
    - value: Initial checked state
85
    - key: Unique key for the widget
86
    - help: Tooltip text shown on hover
87
    - on_change: Callback function executed when value changes
88
    - args: Arguments passed to callback function
89
    - kwargs: Keyword arguments passed to callback function
90
    
91
    Returns:
92
    bool: Current checked state of the checkbox
93
    """
94
```
95

96
#### Usage Example
97

98
```python
99
import streamlit as st
100

101
# Checkbox for agreement
102
agree = st.checkbox("I agree to the terms and conditions")
103

104
if agree:
105
    st.write("Thank you for agreeing!")
106
```
107

108
### Selection Widgets
109

110
Capture single or multiple selections from predefined options.
111

112
```python { .api }
113
def radio(label: str, options, index: int = 0, key: str = None, help: str = None, on_change=None, args=None, kwargs=None, horizontal: bool = False):
114
    """
115
    Display radio button selection widget.
116
    
117
    Parameters:
118
    - label: Text displayed above the radio buttons
119
    - options: List of options to choose from
120
    - index: Index of the initially selected option
121
    - key: Unique key for the widget
122
    - help: Tooltip text shown on hover
123
    - on_change: Callback function executed when selection changes
124
    - args: Arguments passed to callback function
125
    - kwargs: Keyword arguments passed to callback function
126
    - horizontal: Whether to display options horizontally
127
    
128
    Returns:
129
    The selected option value
130
    """
131

132
def selectbox(label: str, options, index: int = 0, key: str = None, help: str = None, on_change=None, args=None, kwargs=None):
133
    """
134
    Display a dropdown selectbox widget.
135
    
136
    Parameters:
137
    - label: Text displayed above the selectbox
138
    - options: List of options to choose from
139
    - index: Index of the initially selected option
140
    - key: Unique key for the widget
141
    - help: Tooltip text shown on hover
142
    - on_change: Callback function executed when selection changes
143
    - args: Arguments passed to callback function
144
    - kwargs: Keyword arguments passed to callback function
145
    
146
    Returns:
147
    The selected option value
148
    """
149

150
def multiselect(label: str, options, default=None, key: str = None, help: str = None, on_change=None, args=None, kwargs=None):
151
    """
152
    Display a multiselect widget for choosing multiple options.
153
    
154
    Parameters:
155
    - label: Text displayed above the multiselect
156
    - options: List of options to choose from
157
    - default: List of initially selected options
158
    - key: Unique key for the widget
159
    - help: Tooltip text shown on hover
160
    - on_change: Callback function executed when selection changes
161
    - args: Arguments passed to callback function
162
    - kwargs: Keyword arguments passed to callback function
163
    
164
    Returns:
165
    List of selected option values
166
    """
167
```
168

169
#### Usage Example
170

171
```python
172
import streamlit as st
173

174
# Radio buttons
175
choice = st.radio(
176
    "Choose your favorite color:",
177
    ["Red", "Green", "Blue"]
178
)
179

180
# Selectbox
181
city = st.selectbox(
182
    "Select your city:",
183
    ["New York", "London", "Tokyo", "Sydney"]
184
)
185

186
# Multiselect
187
interests = st.multiselect(
188
    "Select your interests:",
189
    ["Sports", "Music", "Movies", "Reading", "Travel"],
190
    default=["Music"]
191
)
192

193
st.write(f"You chose {choice}, live in {city}, and are interested in {interests}")
194
```
195

196
### Slider Inputs
197

198
Capture numeric values through intuitive slider interfaces.
199

200
```python { .api }
201
def slider(label: str, min_value=None, max_value=None, value=None, step=None, format: str = None, key: str = None, help: str = None, on_change=None, args=None, kwargs=None):
202
    """
203
    Display a slider widget for numeric input.
204
    
205
    Parameters:
206
    - label: Text displayed above the slider
207
    - min_value: Minimum value allowed
208
    - max_value: Maximum value allowed  
209
    - value: Initial value (or tuple for range slider)
210
    - step: Step size for value increments
211
    - format: Printf-style format string for display
212
    - key: Unique key for the widget
213
    - help: Tooltip text shown on hover
214
    - on_change: Callback function executed when value changes
215
    - args: Arguments passed to callback function
216
    - kwargs: Keyword arguments passed to callback function
217
    
218
    Returns:
219
    The selected numeric value or tuple for range slider
220
    """
221

222
def select_slider(label: str, options, value=None, key: str = None, help: str = None, on_change=None, args=None, kwargs=None):
223
    """
224
    Display a slider widget for selecting from predefined options.
225
    
226
    Parameters:
227
    - label: Text displayed above the slider
228
    - options: List of options to choose from
229
    - value: Initial selected value
230
    - key: Unique key for the widget
231
    - help: Tooltip text shown on hover
232
    - on_change: Callback function executed when value changes
233
    - args: Arguments passed to callback function
234
    - kwargs: Keyword arguments passed to callback function
235
    
236
    Returns:
237
    The selected option value
238
    """
239
```
240

241
#### Usage Example
242

243
```python
244
import streamlit as st
245

246
# Numeric slider
247
age = st.slider("Select your age:", 0, 100, 25)
248

249
# Range slider
250
price_range = st.slider(
251
    "Select price range:",
252
    0.0, 100.0, (20.0, 80.0)
253
)
254

255
# Select slider with custom options
256
size = st.select_slider(
257
    "Select size:",
258
    options=["XS", "S", "M", "L", "XL"],
259
    value="M"
260
)
261

262
st.write(f"Age: {age}, Price range: ${price_range[0]}-${price_range[1]}, Size: {size}")
263
```
264

265
### Text Input
266

267
Capture text and numeric input from users.
268

269
```python { .api }
270
def text_input(label: str, value: str = "", max_chars: int = None, key: str = None, type: str = "default", help: str = None, autocomplete: str = None, on_change=None, args=None, kwargs=None, placeholder: str = None, disabled: bool = False) -> str:
271
    """
272
    Display a single-line text input widget.
273
    
274
    Parameters:
275
    - label: Text displayed above the input
276
    - value: Initial text value
277
    - max_chars: Maximum number of characters allowed
278
    - key: Unique key for the widget
279
    - type: Input type ("default" or "password")
280
    - help: Tooltip text shown on hover
281
    - autocomplete: Autocomplete attribute value
282
    - on_change: Callback function executed when value changes
283
    - args: Arguments passed to callback function
284
    - kwargs: Keyword arguments passed to callback function
285
    - placeholder: Placeholder text shown when empty
286
    - disabled: Whether the input is disabled
287
    
288
    Returns:
289
    str: Current text value
290
    """
291

292
def text_area(label: str, value: str = "", height: int = None, max_chars: int = None, key: str = None, help: str = None, on_change=None, args=None, kwargs=None, placeholder: str = None) -> str:
293
    """
294
    Display a multi-line text input widget.
295
    
296
    Parameters:
297
    - label: Text displayed above the text area
298
    - value: Initial text value
299
    - height: Height of the text area in pixels
300
    - max_chars: Maximum number of characters allowed
301
    - key: Unique key for the widget
302
    - help: Tooltip text shown on hover
303
    - on_change: Callback function executed when value changes
304
    - args: Arguments passed to callback function
305
    - kwargs: Keyword arguments passed to callback function
306
    - placeholder: Placeholder text shown when empty
307
    
308
    Returns:
309
    str: Current text value
310
    """
311

312
def number_input(label: str, min_value=None, max_value=None, value=None, step=None, format: str = None, key: str = None, help: str = None, on_change=None, args=None, kwargs=None, placeholder: str = None):
313
    """
314
    Display a numeric input widget.
315
    
316
    Parameters:
317
    - label: Text displayed above the input
318
    - min_value: Minimum value allowed
319
    - max_value: Maximum value allowed
320
    - value: Initial numeric value
321
    - step: Step size for value increments
322
    - format: Printf-style format string for display
323
    - key: Unique key for the widget
324
    - help: Tooltip text shown on hover
325
    - on_change: Callback function executed when value changes
326
    - args: Arguments passed to callback function
327
    - kwargs: Keyword arguments passed to callback function
328
    - placeholder: Placeholder text shown when empty
329
    
330
    Returns:
331
    int or float: Current numeric value
332
    """
333
```
334

335
#### Usage Example
336

337
```python
338
import streamlit as st
339

340
# Text inputs
341
name = st.text_input("Enter your name:", placeholder="Your full name")
342
password = st.text_input("Enter password:", type="password")
343

344
# Text area
345
feedback = st.text_area(
346
    "Leave feedback:",
347
    height=100,
348
    placeholder="Tell us what you think..."
349
)
350

351
# Number input
352
quantity = st.number_input(
353
    "Quantity:",
354
    min_value=1,
355
    max_value=100,
356
    value=1,
357
    step=1
358
)
359

360
st.write(f"Hello {name}! You ordered {quantity} items.")
361
```
362

363
### Date and Time Input
364

365
Capture date and time values from users.
366

367
```python { .api }
368
def date_input(label: str, value=None, min_value=None, max_value=None, key: str = None, help: str = None, on_change=None, args=None, kwargs=None):
369
    """
370
    Display a date input widget.
371
    
372
    Parameters:
373
    - label: Text displayed above the date picker
374
    - value: Initial date value (datetime.date object or None)
375
    - min_value: Minimum date allowed
376
    - max_value: Maximum date allowed
377
    - key: Unique key for the widget
378
    - help: Tooltip text shown on hover
379
    - on_change: Callback function executed when value changes
380
    - args: Arguments passed to callback function
381
    - kwargs: Keyword arguments passed to callback function
382
    
383
    Returns:
384
    datetime.date: Selected date
385
    """
386

387
def time_input(label: str, value=None, key: str = None, help: str = None, on_change=None, args=None, kwargs=None):
388
    """
389
    Display a time input widget.
390
    
391
    Parameters:
392
    - label: Text displayed above the time picker
393
    - value: Initial time value (datetime.time object or None)
394
    - key: Unique key for the widget
395
    - help: Tooltip text shown on hover
396
    - on_change: Callback function executed when value changes
397
    - args: Arguments passed to callback function
398
    - kwargs: Keyword arguments passed to callback function
399
    
400
    Returns:
401
    datetime.time: Selected time
402
    """
403
```
404

405
#### Usage Example
406

407
```python
408
import streamlit as st
409
from datetime import datetime, date, time
410

411
# Date input
412
selected_date = st.date_input(
413
    "Select a date:",
414
    value=date.today()
415
)
416

417
# Time input
418
selected_time = st.time_input(
419
    "Select a time:",
420
    value=time(9, 0)
421
)
422

423
st.write(f"You selected {selected_date} at {selected_time}")
424
```
425

426
### File and Media Input
427

428
Handle file uploads and camera input for multimedia content.
429

430
```python { .api }
431
def file_uploader(label: str, type=None, accept_multiple_files: bool = False, key: str = None, help: str = None, on_change=None, args=None, kwargs=None):
432
    """
433
    Display a file uploader widget.
434
    
435
    Parameters:
436
    - label: Text displayed above the file uploader
437
    - type: List of allowed file extensions (e.g., ["csv", "txt"])
438
    - accept_multiple_files: Whether to allow multiple file selection
439
    - key: Unique key for the widget
440
    - help: Tooltip text shown on hover
441
    - on_change: Callback function executed when files change
442
    - args: Arguments passed to callback function
443
    - kwargs: Keyword arguments passed to callback function
444
    
445
    Returns:
446
    UploadedFile or List[UploadedFile] or None: Uploaded file(s)
447
    """
448

449
def camera_input(label: str, key: str = None, help: str = None, on_change=None, args=None, kwargs=None):
450
    """
451
    Display a camera input widget for taking photos.
452
    
453
    Parameters:
454
    - label: Text displayed above the camera input
455
    - key: Unique key for the widget
456
    - help: Tooltip text shown on hover
457
    - on_change: Callback function executed when photo is taken
458
    - args: Arguments passed to callback function
459
    - kwargs: Keyword arguments passed to callback function
460
    
461
    Returns:
462
    UploadedFile or None: Captured photo file
463
    """
464
```
465

466
#### Usage Example
467

468
```python
469
import streamlit as st
470
import pandas as pd
471

472
# File uploader
473
uploaded_file = st.file_uploader("Choose a CSV file", type="csv")
474

475
if uploaded_file is not None:
476
    df = pd.read_csv(uploaded_file)
477
    st.write("File contents:")
478
    st.dataframe(df)
479

480
# Multiple file upload
481
uploaded_files = st.file_uploader(
482
    "Choose multiple images",
483
    type=["png", "jpg", "jpeg"],
484
    accept_multiple_files=True
485
)
486

487
for uploaded_file in uploaded_files:
488
    st.image(uploaded_file)
489

490
# Camera input
491
camera_photo = st.camera_input("Take a photo")
492

493
if camera_photo is not None:
494
    st.image(camera_photo)
495
```
496

497
### Color Input
498

499
Capture color selections from users.
500

501
```python { .api }
502
def color_picker(label: str, value: str = "#000000", key: str = None, help: str = None, on_change=None, args=None, kwargs=None) -> str:
503
    """
504
    Display a color picker widget.
505
    
506
    Parameters:
507
    - label: Text displayed above the color picker
508
    - value: Initial color value in hex format
509
    - key: Unique key for the widget
510
    - help: Tooltip text shown on hover
511
    - on_change: Callback function executed when color changes
512
    - args: Arguments passed to callback function
513
    - kwargs: Keyword arguments passed to callback function
514
    
515
    Returns:
516
    str: Selected color in hex format (e.g., "#FF0000")
517
    """
518
```
519

520
#### Usage Example
521

522
```python
523
import streamlit as st
524

525
# Color picker
526
color = st.color_picker("Pick a color:", "#FF0000")
527

528
st.write(f"Selected color: {color}")
529

530
# Use the color in styling
531
st.markdown(
532
    f'<div style="background-color: {color}; padding: 10px; border-radius: 5px;">'
533
    f'This div has the selected background color!'
534
    f'</div>',
535
    unsafe_allow_html=True
536
)
537
```
538

539
## Widget State and Keys
540

541
All widgets support a `key` parameter for unique identification and state management:
542

543
```python
544
# Widget with key for session state access
545
if st.button("Increment", key="increment_btn"):
546
    if "counter" not in st.session_state:
547
        st.session_state.counter = 0
548
    st.session_state.counter += 1
549

550
st.write(f"Counter: {st.session_state.get('counter', 0)}")
551
```