pypi-streamlit

Description
A faster way to build and share data apps
Author
tessl
Last updated

How to use

npx @tessl/cli registry install tessl/pypi-streamlit@1.49.0

input-widgets.md docs/

1
# Input Widgets
2
3
Interactive widgets for user input and interaction. These widgets enable user engagement and data collection in Streamlit applications.
4
5
## Capabilities
6
7
### Button Widgets
8
9
Interactive button elements 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 a button widget.
15
16
Parameters:
17
- label (str): Button label text
18
- key (str): Unique key for the widget
19
- help (str): Optional tooltip text
20
- on_click (callable): Function to call when clicked
21
- args (tuple): Arguments to pass to on_click function
22
- kwargs (dict): Keyword arguments to pass to on_click function
23
- type (str): Button type ('primary' or 'secondary')
24
- disabled (bool): Disable the button
25
- use_container_width (bool): Use full container width
26
- icon (str): Optional icon name
27
28
Returns:
29
bool: True if button was clicked, False otherwise
30
"""
31
32
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, icon=None):
33
"""
34
Display a download button widget.
35
36
Parameters:
37
- label (str): Button label text
38
- data: Data to download (str, bytes, file-like object, or DataFrame)
39
- file_name (str): Suggested filename for download
40
- mime (str): MIME type of the data
41
- key (str): Unique key for the widget
42
- help (str): Optional tooltip text
43
- on_click (callable): Function to call when clicked
44
- args (tuple): Arguments to pass to on_click function
45
- kwargs (dict): Keyword arguments to pass to on_click function
46
- disabled (bool): Disable the button
47
- use_container_width (bool): Use full container width
48
- icon (str): Optional icon name
49
50
Returns:
51
bool: True if button was clicked, False otherwise
52
"""
53
54
def link_button(label, url, help=None, disabled=False, use_container_width=False, icon=None):
55
"""
56
Display a button that opens a URL when clicked.
57
58
Parameters:
59
- label (str): Button label text
60
- url (str): URL to open
61
- help (str): Optional tooltip text
62
- disabled (bool): Disable the button
63
- use_container_width (bool): Use full container width
64
- icon (str): Optional icon name
65
66
Returns:
67
bool: True if button was clicked, False otherwise
68
"""
69
70
def page_link(page, label=None, icon=None, help=None, disabled=False, use_container_width=False):
71
"""
72
Display a link to another page in a multipage app.
73
74
Parameters:
75
- page: Page object or path to link to
76
- label (str): Link label text (defaults to page title)
77
- icon (str): Optional icon name
78
- help (str): Optional tooltip text
79
- disabled (bool): Disable the link
80
- use_container_width (bool): Use full container width
81
82
Returns:
83
bool: True if link was clicked, False otherwise
84
"""
85
```
86
87
### Text Input Widgets
88
89
Text input widgets for collecting user text input.
90
91
```python { .api }
92
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"):
93
"""
94
Display a single-line text input widget.
95
96
Parameters:
97
- label (str): Widget label
98
- value (str): Initial value
99
- max_chars (int): Maximum number of characters
100
- key (str): Unique key for the widget
101
- type (str): Input type ('default' or 'password')
102
- help (str): Optional tooltip text
103
- autocomplete (str): HTML autocomplete attribute
104
- on_change (callable): Function to call when value changes
105
- args (tuple): Arguments to pass to on_change function
106
- kwargs (dict): Keyword arguments to pass to on_change function
107
- placeholder (str): Placeholder text
108
- disabled (bool): Disable the widget
109
- label_visibility (str): Label visibility ('visible', 'hidden', 'collapsed')
110
111
Returns:
112
str: Current text input value
113
"""
114
115
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"):
116
"""
117
Display a multi-line text input widget.
118
119
Parameters:
120
- label (str): Widget label
121
- value (str): Initial value
122
- height (int): Height in pixels
123
- max_chars (int): Maximum number of characters
124
- key (str): Unique key for the widget
125
- help (str): Optional tooltip text
126
- on_change (callable): Function to call when value changes
127
- args (tuple): Arguments to pass to on_change function
128
- kwargs (dict): Keyword arguments to pass to on_change function
129
- placeholder (str): Placeholder text
130
- disabled (bool): Disable the widget
131
- label_visibility (str): Label visibility ('visible', 'hidden', 'collapsed')
132
133
Returns:
134
str: Current text area value
135
"""
136
```
137
138
### Numeric Input Widgets
139
140
Widgets for numeric input and selection.
141
142
```python { .api }
143
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, disabled=False, label_visibility="visible", placeholder=None):
144
"""
145
Display a numeric input widget.
146
147
Parameters:
148
- label (str): Widget label
149
- min_value (float): Minimum allowed value
150
- max_value (float): Maximum allowed value
151
- value (float): Initial value
152
- step (float): Step size for increment/decrement
153
- format (str): Number format string
154
- key (str): Unique key for the widget
155
- help (str): Optional tooltip text
156
- on_change (callable): Function to call when value changes
157
- args (tuple): Arguments to pass to on_change function
158
- kwargs (dict): Keyword arguments to pass to on_change function
159
- disabled (bool): Disable the widget
160
- label_visibility (str): Label visibility ('visible', 'hidden', 'collapsed')
161
- placeholder (str): Placeholder text
162
163
Returns:
164
float or int: Current numeric value
165
"""
166
167
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"):
168
"""
169
Display a slider widget.
170
171
Parameters:
172
- label (str): Widget label
173
- min_value (float): Minimum value
174
- max_value (float): Maximum value
175
- value (float or tuple): Initial value(s) - single value or (min, max) for range
176
- step (float): Step size
177
- format (str): Value format string
178
- key (str): Unique key for the widget
179
- help (str): Optional tooltip text
180
- on_change (callable): Function to call when value changes
181
- args (tuple): Arguments to pass to on_change function
182
- kwargs (dict): Keyword arguments to pass to on_change function
183
- disabled (bool): Disable the widget
184
- label_visibility (str): Label visibility ('visible', 'hidden', 'collapsed')
185
186
Returns:
187
float or tuple: Current slider value(s)
188
"""
189
190
def select_slider(label, options=(), value=None, format_func=None, key=None, help=None, on_change=None, args=None, kwargs=None, disabled=False, label_visibility="visible"):
191
"""
192
Display a slider widget for selecting from discrete options.
193
194
Parameters:
195
- label (str): Widget label
196
- options (sequence): List of options to select from
197
- value: Initial selected value
198
- format_func (callable): Function to format option display
199
- key (str): Unique key for the widget
200
- help (str): Optional tooltip text
201
- on_change (callable): Function to call when value changes
202
- args (tuple): Arguments to pass to on_change function
203
- kwargs (dict): Keyword arguments to pass to on_change function
204
- disabled (bool): Disable the widget
205
- label_visibility (str): Label visibility ('visible', 'hidden', 'collapsed')
206
207
Returns:
208
Any: Currently selected value
209
"""
210
```
211
212
### Selection Widgets
213
214
Widgets for selecting from predefined options.
215
216
```python { .api }
217
def selectbox(label, options, index=0, format_func=None, key=None, help=None, on_change=None, args=None, kwargs=None, disabled=False, label_visibility="visible", placeholder="Choose an option"):
218
"""
219
Display a select widget (dropdown).
220
221
Parameters:
222
- label (str): Widget label
223
- options (sequence): List of options to select from
224
- index (int): Index of initially selected option
225
- format_func (callable): Function to format option display
226
- key (str): Unique key for the widget
227
- help (str): Optional tooltip text
228
- on_change (callable): Function to call when value changes
229
- args (tuple): Arguments to pass to on_change function
230
- kwargs (dict): Keyword arguments to pass to on_change function
231
- disabled (bool): Disable the widget
232
- label_visibility (str): Label visibility ('visible', 'hidden', 'collapsed')
233
- placeholder (str): Placeholder text when no option selected
234
235
Returns:
236
Any: Currently selected option
237
"""
238
239
def multiselect(label, options, default=None, format_func=None, key=None, help=None, on_change=None, args=None, kwargs=None, disabled=False, label_visibility="visible", max_selections=None, placeholder="Choose an option"):
240
"""
241
Display a multiselect widget.
242
243
Parameters:
244
- label (str): Widget label
245
- options (sequence): List of options to select from
246
- default (list): Initially selected options
247
- format_func (callable): Function to format option display
248
- key (str): Unique key for the widget
249
- help (str): Optional tooltip text
250
- on_change (callable): Function to call when value changes
251
- args (tuple): Arguments to pass to on_change function
252
- kwargs (dict): Keyword arguments to pass to on_change function
253
- disabled (bool): Disable the widget
254
- label_visibility (str): Label visibility ('visible', 'hidden', 'collapsed')
255
- max_selections (int): Maximum number of selections allowed
256
- placeholder (str): Placeholder text when no options selected
257
258
Returns:
259
list: Currently selected options
260
"""
261
262
def radio(label, options, index=0, format_func=None, key=None, help=None, on_change=None, args=None, kwargs=None, disabled=False, horizontal=False, captions=None, selection_mode="single", label_visibility="visible"):
263
"""
264
Display a radio button widget.
265
266
Parameters:
267
- label (str): Widget label
268
- options (sequence): List of options to select from
269
- index (int): Index of initially selected option
270
- format_func (callable): Function to format option display
271
- key (str): Unique key for the widget
272
- help (str): Optional tooltip text
273
- on_change (callable): Function to call when value changes
274
- args (tuple): Arguments to pass to on_change function
275
- kwargs (dict): Keyword arguments to pass to on_change function
276
- disabled (bool): Disable the widget
277
- horizontal (bool): Display options horizontally
278
- captions (list): Optional captions for each option
279
- selection_mode (str): Selection mode ('single')
280
- label_visibility (str): Label visibility ('visible', 'hidden', 'collapsed')
281
282
Returns:
283
Any: Currently selected option
284
"""
285
286
def checkbox(label, value=False, key=None, help=None, on_change=None, args=None, kwargs=None, disabled=False, label_visibility="visible"):
287
"""
288
Display a checkbox widget.
289
290
Parameters:
291
- label (str): Widget label
292
- value (bool): Initial checkbox state
293
- key (str): Unique key for the widget
294
- help (str): Optional tooltip text
295
- on_change (callable): Function to call when value changes
296
- args (tuple): Arguments to pass to on_change function
297
- kwargs (dict): Keyword arguments to pass to on_change function
298
- disabled (bool): Disable the widget
299
- label_visibility (str): Label visibility ('visible', 'hidden', 'collapsed')
300
301
Returns:
302
bool: Current checkbox state
303
"""
304
305
def toggle(label, value=False, key=None, help=None, on_change=None, args=None, kwargs=None, disabled=False, label_visibility="visible"):
306
"""
307
Display a toggle switch widget.
308
309
Parameters:
310
- label (str): Widget label
311
- value (bool): Initial toggle state
312
- key (str): Unique key for the widget
313
- help (str): Optional tooltip text
314
- on_change (callable): Function to call when value changes
315
- args (tuple): Arguments to pass to on_change function
316
- kwargs (dict): Keyword arguments to pass to on_change function
317
- disabled (bool): Disable the widget
318
- label_visibility (str): Label visibility ('visible', 'hidden', 'collapsed')
319
320
Returns:
321
bool: Current toggle state
322
"""
323
```
324
325
### Modern Selection Widgets
326
327
Contemporary selection interfaces with enhanced user experience.
328
329
```python { .api }
330
def pills(label, options, selection_mode="single", format_func=None, default=None, key=None, help=None, on_change=None, args=None, kwargs=None, disabled=False, label_visibility="visible"):
331
"""
332
Display a pills widget for selection.
333
334
Parameters:
335
- label (str): Widget label
336
- options (sequence): List of options to select from
337
- selection_mode (str): Selection mode ('single' or 'multi')
338
- format_func (callable): Function to format option display
339
- default: Initially selected option(s)
340
- key (str): Unique key for the widget
341
- help (str): Optional tooltip text
342
- on_change (callable): Function to call when value changes
343
- args (tuple): Arguments to pass to on_change function
344
- kwargs (dict): Keyword arguments to pass to on_change function
345
- disabled (bool): Disable the widget
346
- label_visibility (str): Label visibility ('visible', 'hidden', 'collapsed')
347
348
Returns:
349
Any or list: Currently selected option(s)
350
"""
351
352
def segmented_control(label, options, selection_mode="single", format_func=None, default=None, key=None, help=None, on_change=None, args=None, kwargs=None, disabled=False, label_visibility="visible"):
353
"""
354
Display a segmented control widget.
355
356
Parameters:
357
- label (str): Widget label
358
- options (sequence): List of options to select from
359
- selection_mode (str): Selection mode ('single' or 'multi')
360
- format_func (callable): Function to format option display
361
- default: Initially selected option(s)
362
- key (str): Unique key for the widget
363
- help (str): Optional tooltip text
364
- on_change (callable): Function to call when value changes
365
- args (tuple): Arguments to pass to on_change function
366
- kwargs (dict): Keyword arguments to pass to on_change function
367
- disabled (bool): Disable the widget
368
- label_visibility (str): Label visibility ('visible', 'hidden', 'collapsed')
369
370
Returns:
371
Any or list: Currently selected option(s)
372
"""
373
```
374
375
### Date and Time Widgets
376
377
Widgets for temporal input and selection.
378
379
```python { .api }
380
def date_input(label, value="today", 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"):
381
"""
382
Display a date input widget.
383
384
Parameters:
385
- label (str): Widget label
386
- value: Initial date value ('today', date object, or None)
387
- min_value (date): Minimum selectable date
388
- max_value (date): Maximum selectable date
389
- key (str): Unique key for the widget
390
- help (str): Optional tooltip text
391
- on_change (callable): Function to call when value changes
392
- args (tuple): Arguments to pass to on_change function
393
- kwargs (dict): Keyword arguments to pass to on_change function
394
- format (str): Date display format
395
- disabled (bool): Disable the widget
396
- label_visibility (str): Label visibility ('visible', 'hidden', 'collapsed')
397
398
Returns:
399
date or None: Selected date
400
"""
401
402
def time_input(label, value=None, key=None, help=None, on_change=None, args=None, kwargs=None, disabled=False, label_visibility="visible", step=60):
403
"""
404
Display a time input widget.
405
406
Parameters:
407
- label (str): Widget label
408
- value (time): Initial time value
409
- key (str): Unique key for the widget
410
- help (str): Optional tooltip text
411
- on_change (callable): Function to call when value changes
412
- args (tuple): Arguments to pass to on_change function
413
- kwargs (dict): Keyword arguments to pass to on_change function
414
- disabled (bool): Disable the widget
415
- label_visibility (str): Label visibility ('visible', 'hidden', 'collapsed')
416
- step (int): Step size in seconds
417
418
Returns:
419
time: Selected time
420
"""
421
```
422
423
### File and Media Input Widgets
424
425
Widgets for file uploads and media capture.
426
427
```python { .api }
428
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"):
429
"""
430
Display a file uploader widget.
431
432
Parameters:
433
- label (str): Widget label
434
- type (str or list): Allowed file extensions (e.g., 'csv', ['png', 'jpg'])
435
- accept_multiple_files (bool): Allow multiple file selection
436
- key (str): Unique key for the widget
437
- help (str): Optional tooltip text
438
- on_change (callable): Function to call when files change
439
- args (tuple): Arguments to pass to on_change function
440
- kwargs (dict): Keyword arguments to pass to on_change function
441
- disabled (bool): Disable the widget
442
- label_visibility (str): Label visibility ('visible', 'hidden', 'collapsed')
443
444
Returns:
445
UploadedFile or list or None: Uploaded file(s)
446
"""
447
448
def camera_input(label, key=None, help=None, on_change=None, args=None, kwargs=None, disabled=False, label_visibility="visible"):
449
"""
450
Display a camera input widget for taking photos.
451
452
Parameters:
453
- label (str): Widget label
454
- key (str): Unique key for the widget
455
- help (str): Optional tooltip text
456
- on_change (callable): Function to call when photo is taken
457
- args (tuple): Arguments to pass to on_change function
458
- kwargs (dict): Keyword arguments to pass to on_change function
459
- disabled (bool): Disable the widget
460
- label_visibility (str): Label visibility ('visible', 'hidden', 'collapsed')
461
462
Returns:
463
UploadedFile or None: Captured photo
464
"""
465
466
def audio_input(label, key=None, help=None, on_change=None, args=None, kwargs=None, disabled=False, label_visibility="visible"):
467
"""
468
Display an audio input widget for recording audio.
469
470
Parameters:
471
- label (str): Widget label
472
- key (str): Unique key for the widget
473
- help (str): Optional tooltip text
474
- on_change (callable): Function to call when audio is recorded
475
- args (tuple): Arguments to pass to on_change function
476
- kwargs (dict): Keyword arguments to pass to on_change function
477
- disabled (bool): Disable the widget
478
- label_visibility (str): Label visibility ('visible', 'hidden', 'collapsed')
479
480
Returns:
481
UploadedFile or None: Recorded audio
482
"""
483
484
def color_picker(label, value=None, key=None, help=None, on_change=None, args=None, kwargs=None, disabled=False, label_visibility="visible"):
485
"""
486
Display a color picker widget.
487
488
Parameters:
489
- label (str): Widget label
490
- value (str): Initial color value (hex format)
491
- key (str): Unique key for the widget
492
- help (str): Optional tooltip text
493
- on_change (callable): Function to call when color changes
494
- args (tuple): Arguments to pass to on_change function
495
- kwargs (dict): Keyword arguments to pass to on_change function
496
- disabled (bool): Disable the widget
497
- label_visibility (str): Label visibility ('visible', 'hidden', 'collapsed')
498
499
Returns:
500
str: Selected color in hex format
501
"""
502
```
503
504
### Form Controls
505
506
Form-specific input widgets and controls.
507
508
```python { .api }
509
def form_submit_button(label="Submit", help=None, on_click=None, args=None, kwargs=None, type="secondary", disabled=False, use_container_width=False, icon=None):
510
"""
511
Display a form submit button.
512
513
Parameters:
514
- label (str): Button label
515
- help (str): Optional tooltip text
516
- on_click (callable): Function to call when clicked
517
- args (tuple): Arguments to pass to on_click function
518
- kwargs (dict): Keyword arguments to pass to on_click function
519
- type (str): Button type ('primary' or 'secondary')
520
- disabled (bool): Disable the button
521
- use_container_width (bool): Use full container width
522
- icon (str): Optional icon name
523
524
Returns:
525
bool: True if form was submitted, False otherwise
526
"""
527
```
528
529
## Usage Examples
530
531
### Basic Input Collection
532
533
```python
534
import streamlit as st
535
536
# Text inputs
537
name = st.text_input("Enter your name:")
538
description = st.text_area("Tell us about yourself:", height=100)
539
540
# Numeric inputs
541
age = st.number_input("Age:", min_value=0, max_value=120, value=25)
542
rating = st.slider("Rate your experience:", 1, 10, 5)
543
544
# Selection widgets
545
city = st.selectbox("Select your city:", ["New York", "London", "Tokyo"])
546
hobbies = st.multiselect("Select hobbies:", ["Reading", "Sports", "Music", "Travel"])
547
newsletter = st.checkbox("Subscribe to newsletter")
548
```
549
550
### Advanced Widget Features
551
552
```python
553
# Button with callback
554
def on_button_click():
555
st.session_state.clicked = True
556
557
if st.button("Click me!", on_click=on_button_click):
558
st.success("Button was clicked!")
559
560
# File upload with type restrictions
561
uploaded_file = st.file_uploader(
562
"Choose a CSV file",
563
type=['csv'],
564
help="Upload a CSV file for analysis"
565
)
566
567
if uploaded_file is not None:
568
df = pd.read_csv(uploaded_file)
569
st.dataframe(df)
570
571
# Date range selection
572
from datetime import date, timedelta
573
574
start_date = st.date_input(
575
"Start date",
576
value=date.today() - timedelta(days=7)
577
)
578
end_date = st.date_input("End date", value=date.today())
579
580
if start_date > end_date:
581
st.error("Start date must be before end date")
582
```
583
584
### Chat Interface Widgets
585
586
Interactive chat interface components for building conversational applications.
587
588
```python { .api }
589
def chat_input(placeholder="Your message", key=None, max_chars=None, accept_file=False, file_type=None, disabled=False, on_submit=None, args=None, kwargs=None, width="stretch"):
590
"""
591
Display a chat input widget for conversational interfaces.
592
593
Parameters:
594
- placeholder (str): Placeholder text when input is empty
595
- key (str): Unique key for the widget
596
- max_chars (int): Maximum number of characters allowed
597
- accept_file (bool, "multiple", "directory"): File acceptance configuration
598
- file_type (str or list): Accepted file types (e.g., [".jpg", ".png"])
599
- disabled (bool): Disable the input widget
600
- on_submit (callable): Function to call on submission
601
- args (tuple): Arguments to pass to on_submit function
602
- kwargs (dict): Keyword arguments to pass to on_submit function
603
- width (str): Widget width configuration
604
605
Returns:
606
str or ChatInputValue or None: User input text or file data, None if no input
607
"""
608
609
def chat_message(name, avatar=None, width="stretch"):
610
"""
611
Insert a chat message container for conversational interfaces.
612
613
Parameters:
614
- name (str): Message author name ("user", "assistant", "ai", "human", or custom)
615
- avatar (str or image): Avatar image or emoji for the message
616
- width (str): Container width configuration
617
618
Returns:
619
DeltaGenerator: Container for chat message content
620
"""
621
```
622
623
#### Usage Examples
624
625
```python
626
import streamlit as st
627
628
# Initialize chat history
629
if "messages" not in st.session_state:
630
st.session_state.messages = []
631
632
# Display chat messages from history
633
for message in st.session_state.messages:
634
with st.chat_message(message["role"]):
635
st.markdown(message["content"])
636
637
# Chat input
638
if prompt := st.chat_input("What would you like to know?"):
639
# Add user message to chat history
640
st.session_state.messages.append({"role": "user", "content": prompt})
641
with st.chat_message("user"):
642
st.markdown(prompt)
643
644
# Generate assistant response
645
response = f"Echo: {prompt}"
646
st.session_state.messages.append({"role": "assistant", "content": response})
647
with st.chat_message("assistant"):
648
st.markdown(response)
649
650
# Chat input with file upload
651
prompt = st.chat_input("Send a message", accept_file="multiple", file_type=[".txt", ".py", ".md"])
652
653
if prompt:
654
if hasattr(prompt, 'message') and hasattr(prompt, 'files'):
655
st.write(f"Message: {prompt.message}")
656
st.write(f"Files: {[f.name for f in prompt.files]}")
657
else:
658
st.write(f"Text message: {prompt}")
659
```