- Spec files
pypi-streamlit
Describes: pkg:pypi/streamlit@1.49.x
- Description
- A faster way to build and share data apps
- Author
- tessl
- Last updated
input-widgets.md docs/
1# Input Widgets23Interactive widgets for user input and interaction. These widgets enable user engagement and data collection in Streamlit applications.45## Capabilities67### Button Widgets89Interactive button elements for triggering actions and navigation.1011```python { .api }12def button(label, key=None, help=None, on_click=None, args=None, kwargs=None, type="secondary", disabled=False, use_container_width=False, icon=None):13"""14Display a button widget.1516Parameters:17- label (str): Button label text18- key (str): Unique key for the widget19- help (str): Optional tooltip text20- on_click (callable): Function to call when clicked21- args (tuple): Arguments to pass to on_click function22- kwargs (dict): Keyword arguments to pass to on_click function23- type (str): Button type ('primary' or 'secondary')24- disabled (bool): Disable the button25- use_container_width (bool): Use full container width26- icon (str): Optional icon name2728Returns:29bool: True if button was clicked, False otherwise30"""3132def 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"""34Display a download button widget.3536Parameters:37- label (str): Button label text38- data: Data to download (str, bytes, file-like object, or DataFrame)39- file_name (str): Suggested filename for download40- mime (str): MIME type of the data41- key (str): Unique key for the widget42- help (str): Optional tooltip text43- on_click (callable): Function to call when clicked44- args (tuple): Arguments to pass to on_click function45- kwargs (dict): Keyword arguments to pass to on_click function46- disabled (bool): Disable the button47- use_container_width (bool): Use full container width48- icon (str): Optional icon name4950Returns:51bool: True if button was clicked, False otherwise52"""5354def link_button(label, url, help=None, disabled=False, use_container_width=False, icon=None):55"""56Display a button that opens a URL when clicked.5758Parameters:59- label (str): Button label text60- url (str): URL to open61- help (str): Optional tooltip text62- disabled (bool): Disable the button63- use_container_width (bool): Use full container width64- icon (str): Optional icon name6566Returns:67bool: True if button was clicked, False otherwise68"""6970def page_link(page, label=None, icon=None, help=None, disabled=False, use_container_width=False):71"""72Display a link to another page in a multipage app.7374Parameters:75- page: Page object or path to link to76- label (str): Link label text (defaults to page title)77- icon (str): Optional icon name78- help (str): Optional tooltip text79- disabled (bool): Disable the link80- use_container_width (bool): Use full container width8182Returns:83bool: True if link was clicked, False otherwise84"""85```8687### Text Input Widgets8889Text input widgets for collecting user text input.9091```python { .api }92def 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"""94Display a single-line text input widget.9596Parameters:97- label (str): Widget label98- value (str): Initial value99- max_chars (int): Maximum number of characters100- key (str): Unique key for the widget101- type (str): Input type ('default' or 'password')102- help (str): Optional tooltip text103- autocomplete (str): HTML autocomplete attribute104- on_change (callable): Function to call when value changes105- args (tuple): Arguments to pass to on_change function106- kwargs (dict): Keyword arguments to pass to on_change function107- placeholder (str): Placeholder text108- disabled (bool): Disable the widget109- label_visibility (str): Label visibility ('visible', 'hidden', 'collapsed')110111Returns:112str: Current text input value113"""114115def 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"""117Display a multi-line text input widget.118119Parameters:120- label (str): Widget label121- value (str): Initial value122- height (int): Height in pixels123- max_chars (int): Maximum number of characters124- key (str): Unique key for the widget125- help (str): Optional tooltip text126- on_change (callable): Function to call when value changes127- args (tuple): Arguments to pass to on_change function128- kwargs (dict): Keyword arguments to pass to on_change function129- placeholder (str): Placeholder text130- disabled (bool): Disable the widget131- label_visibility (str): Label visibility ('visible', 'hidden', 'collapsed')132133Returns:134str: Current text area value135"""136```137138### Numeric Input Widgets139140Widgets for numeric input and selection.141142```python { .api }143def 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"""145Display a numeric input widget.146147Parameters:148- label (str): Widget label149- min_value (float): Minimum allowed value150- max_value (float): Maximum allowed value151- value (float): Initial value152- step (float): Step size for increment/decrement153- format (str): Number format string154- key (str): Unique key for the widget155- help (str): Optional tooltip text156- on_change (callable): Function to call when value changes157- args (tuple): Arguments to pass to on_change function158- kwargs (dict): Keyword arguments to pass to on_change function159- disabled (bool): Disable the widget160- label_visibility (str): Label visibility ('visible', 'hidden', 'collapsed')161- placeholder (str): Placeholder text162163Returns:164float or int: Current numeric value165"""166167def 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"""169Display a slider widget.170171Parameters:172- label (str): Widget label173- min_value (float): Minimum value174- max_value (float): Maximum value175- value (float or tuple): Initial value(s) - single value or (min, max) for range176- step (float): Step size177- format (str): Value format string178- key (str): Unique key for the widget179- help (str): Optional tooltip text180- on_change (callable): Function to call when value changes181- args (tuple): Arguments to pass to on_change function182- kwargs (dict): Keyword arguments to pass to on_change function183- disabled (bool): Disable the widget184- label_visibility (str): Label visibility ('visible', 'hidden', 'collapsed')185186Returns:187float or tuple: Current slider value(s)188"""189190def 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"""192Display a slider widget for selecting from discrete options.193194Parameters:195- label (str): Widget label196- options (sequence): List of options to select from197- value: Initial selected value198- format_func (callable): Function to format option display199- key (str): Unique key for the widget200- help (str): Optional tooltip text201- on_change (callable): Function to call when value changes202- args (tuple): Arguments to pass to on_change function203- kwargs (dict): Keyword arguments to pass to on_change function204- disabled (bool): Disable the widget205- label_visibility (str): Label visibility ('visible', 'hidden', 'collapsed')206207Returns:208Any: Currently selected value209"""210```211212### Selection Widgets213214Widgets for selecting from predefined options.215216```python { .api }217def 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"""219Display a select widget (dropdown).220221Parameters:222- label (str): Widget label223- options (sequence): List of options to select from224- index (int): Index of initially selected option225- format_func (callable): Function to format option display226- key (str): Unique key for the widget227- help (str): Optional tooltip text228- on_change (callable): Function to call when value changes229- args (tuple): Arguments to pass to on_change function230- kwargs (dict): Keyword arguments to pass to on_change function231- disabled (bool): Disable the widget232- label_visibility (str): Label visibility ('visible', 'hidden', 'collapsed')233- placeholder (str): Placeholder text when no option selected234235Returns:236Any: Currently selected option237"""238239def 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"""241Display a multiselect widget.242243Parameters:244- label (str): Widget label245- options (sequence): List of options to select from246- default (list): Initially selected options247- format_func (callable): Function to format option display248- key (str): Unique key for the widget249- help (str): Optional tooltip text250- on_change (callable): Function to call when value changes251- args (tuple): Arguments to pass to on_change function252- kwargs (dict): Keyword arguments to pass to on_change function253- disabled (bool): Disable the widget254- label_visibility (str): Label visibility ('visible', 'hidden', 'collapsed')255- max_selections (int): Maximum number of selections allowed256- placeholder (str): Placeholder text when no options selected257258Returns:259list: Currently selected options260"""261262def 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"""264Display a radio button widget.265266Parameters:267- label (str): Widget label268- options (sequence): List of options to select from269- index (int): Index of initially selected option270- format_func (callable): Function to format option display271- key (str): Unique key for the widget272- help (str): Optional tooltip text273- on_change (callable): Function to call when value changes274- args (tuple): Arguments to pass to on_change function275- kwargs (dict): Keyword arguments to pass to on_change function276- disabled (bool): Disable the widget277- horizontal (bool): Display options horizontally278- captions (list): Optional captions for each option279- selection_mode (str): Selection mode ('single')280- label_visibility (str): Label visibility ('visible', 'hidden', 'collapsed')281282Returns:283Any: Currently selected option284"""285286def checkbox(label, value=False, key=None, help=None, on_change=None, args=None, kwargs=None, disabled=False, label_visibility="visible"):287"""288Display a checkbox widget.289290Parameters:291- label (str): Widget label292- value (bool): Initial checkbox state293- key (str): Unique key for the widget294- help (str): Optional tooltip text295- on_change (callable): Function to call when value changes296- args (tuple): Arguments to pass to on_change function297- kwargs (dict): Keyword arguments to pass to on_change function298- disabled (bool): Disable the widget299- label_visibility (str): Label visibility ('visible', 'hidden', 'collapsed')300301Returns:302bool: Current checkbox state303"""304305def toggle(label, value=False, key=None, help=None, on_change=None, args=None, kwargs=None, disabled=False, label_visibility="visible"):306"""307Display a toggle switch widget.308309Parameters:310- label (str): Widget label311- value (bool): Initial toggle state312- key (str): Unique key for the widget313- help (str): Optional tooltip text314- on_change (callable): Function to call when value changes315- args (tuple): Arguments to pass to on_change function316- kwargs (dict): Keyword arguments to pass to on_change function317- disabled (bool): Disable the widget318- label_visibility (str): Label visibility ('visible', 'hidden', 'collapsed')319320Returns:321bool: Current toggle state322"""323```324325### Modern Selection Widgets326327Contemporary selection interfaces with enhanced user experience.328329```python { .api }330def 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"""332Display a pills widget for selection.333334Parameters:335- label (str): Widget label336- options (sequence): List of options to select from337- selection_mode (str): Selection mode ('single' or 'multi')338- format_func (callable): Function to format option display339- default: Initially selected option(s)340- key (str): Unique key for the widget341- help (str): Optional tooltip text342- on_change (callable): Function to call when value changes343- args (tuple): Arguments to pass to on_change function344- kwargs (dict): Keyword arguments to pass to on_change function345- disabled (bool): Disable the widget346- label_visibility (str): Label visibility ('visible', 'hidden', 'collapsed')347348Returns:349Any or list: Currently selected option(s)350"""351352def 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"""354Display a segmented control widget.355356Parameters:357- label (str): Widget label358- options (sequence): List of options to select from359- selection_mode (str): Selection mode ('single' or 'multi')360- format_func (callable): Function to format option display361- default: Initially selected option(s)362- key (str): Unique key for the widget363- help (str): Optional tooltip text364- on_change (callable): Function to call when value changes365- args (tuple): Arguments to pass to on_change function366- kwargs (dict): Keyword arguments to pass to on_change function367- disabled (bool): Disable the widget368- label_visibility (str): Label visibility ('visible', 'hidden', 'collapsed')369370Returns:371Any or list: Currently selected option(s)372"""373```374375### Date and Time Widgets376377Widgets for temporal input and selection.378379```python { .api }380def 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"""382Display a date input widget.383384Parameters:385- label (str): Widget label386- value: Initial date value ('today', date object, or None)387- min_value (date): Minimum selectable date388- max_value (date): Maximum selectable date389- key (str): Unique key for the widget390- help (str): Optional tooltip text391- on_change (callable): Function to call when value changes392- args (tuple): Arguments to pass to on_change function393- kwargs (dict): Keyword arguments to pass to on_change function394- format (str): Date display format395- disabled (bool): Disable the widget396- label_visibility (str): Label visibility ('visible', 'hidden', 'collapsed')397398Returns:399date or None: Selected date400"""401402def time_input(label, value=None, key=None, help=None, on_change=None, args=None, kwargs=None, disabled=False, label_visibility="visible", step=60):403"""404Display a time input widget.405406Parameters:407- label (str): Widget label408- value (time): Initial time value409- key (str): Unique key for the widget410- help (str): Optional tooltip text411- on_change (callable): Function to call when value changes412- args (tuple): Arguments to pass to on_change function413- kwargs (dict): Keyword arguments to pass to on_change function414- disabled (bool): Disable the widget415- label_visibility (str): Label visibility ('visible', 'hidden', 'collapsed')416- step (int): Step size in seconds417418Returns:419time: Selected time420"""421```422423### File and Media Input Widgets424425Widgets for file uploads and media capture.426427```python { .api }428def 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"""430Display a file uploader widget.431432Parameters:433- label (str): Widget label434- type (str or list): Allowed file extensions (e.g., 'csv', ['png', 'jpg'])435- accept_multiple_files (bool): Allow multiple file selection436- key (str): Unique key for the widget437- help (str): Optional tooltip text438- on_change (callable): Function to call when files change439- args (tuple): Arguments to pass to on_change function440- kwargs (dict): Keyword arguments to pass to on_change function441- disabled (bool): Disable the widget442- label_visibility (str): Label visibility ('visible', 'hidden', 'collapsed')443444Returns:445UploadedFile or list or None: Uploaded file(s)446"""447448def camera_input(label, key=None, help=None, on_change=None, args=None, kwargs=None, disabled=False, label_visibility="visible"):449"""450Display a camera input widget for taking photos.451452Parameters:453- label (str): Widget label454- key (str): Unique key for the widget455- help (str): Optional tooltip text456- on_change (callable): Function to call when photo is taken457- args (tuple): Arguments to pass to on_change function458- kwargs (dict): Keyword arguments to pass to on_change function459- disabled (bool): Disable the widget460- label_visibility (str): Label visibility ('visible', 'hidden', 'collapsed')461462Returns:463UploadedFile or None: Captured photo464"""465466def audio_input(label, key=None, help=None, on_change=None, args=None, kwargs=None, disabled=False, label_visibility="visible"):467"""468Display an audio input widget for recording audio.469470Parameters:471- label (str): Widget label472- key (str): Unique key for the widget473- help (str): Optional tooltip text474- on_change (callable): Function to call when audio is recorded475- args (tuple): Arguments to pass to on_change function476- kwargs (dict): Keyword arguments to pass to on_change function477- disabled (bool): Disable the widget478- label_visibility (str): Label visibility ('visible', 'hidden', 'collapsed')479480Returns:481UploadedFile or None: Recorded audio482"""483484def color_picker(label, value=None, key=None, help=None, on_change=None, args=None, kwargs=None, disabled=False, label_visibility="visible"):485"""486Display a color picker widget.487488Parameters:489- label (str): Widget label490- value (str): Initial color value (hex format)491- key (str): Unique key for the widget492- help (str): Optional tooltip text493- on_change (callable): Function to call when color changes494- args (tuple): Arguments to pass to on_change function495- kwargs (dict): Keyword arguments to pass to on_change function496- disabled (bool): Disable the widget497- label_visibility (str): Label visibility ('visible', 'hidden', 'collapsed')498499Returns:500str: Selected color in hex format501"""502```503504### Form Controls505506Form-specific input widgets and controls.507508```python { .api }509def 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"""511Display a form submit button.512513Parameters:514- label (str): Button label515- help (str): Optional tooltip text516- on_click (callable): Function to call when clicked517- args (tuple): Arguments to pass to on_click function518- kwargs (dict): Keyword arguments to pass to on_click function519- type (str): Button type ('primary' or 'secondary')520- disabled (bool): Disable the button521- use_container_width (bool): Use full container width522- icon (str): Optional icon name523524Returns:525bool: True if form was submitted, False otherwise526"""527```528529## Usage Examples530531### Basic Input Collection532533```python534import streamlit as st535536# Text inputs537name = st.text_input("Enter your name:")538description = st.text_area("Tell us about yourself:", height=100)539540# Numeric inputs541age = st.number_input("Age:", min_value=0, max_value=120, value=25)542rating = st.slider("Rate your experience:", 1, 10, 5)543544# Selection widgets545city = st.selectbox("Select your city:", ["New York", "London", "Tokyo"])546hobbies = st.multiselect("Select hobbies:", ["Reading", "Sports", "Music", "Travel"])547newsletter = st.checkbox("Subscribe to newsletter")548```549550### Advanced Widget Features551552```python553# Button with callback554def on_button_click():555st.session_state.clicked = True556557if st.button("Click me!", on_click=on_button_click):558st.success("Button was clicked!")559560# File upload with type restrictions561uploaded_file = st.file_uploader(562"Choose a CSV file",563type=['csv'],564help="Upload a CSV file for analysis"565)566567if uploaded_file is not None:568df = pd.read_csv(uploaded_file)569st.dataframe(df)570571# Date range selection572from datetime import date, timedelta573574start_date = st.date_input(575"Start date",576value=date.today() - timedelta(days=7)577)578end_date = st.date_input("End date", value=date.today())579580if start_date > end_date:581st.error("Start date must be before end date")582```583584### Chat Interface Widgets585586Interactive chat interface components for building conversational applications.587588```python { .api }589def 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"""591Display a chat input widget for conversational interfaces.592593Parameters:594- placeholder (str): Placeholder text when input is empty595- key (str): Unique key for the widget596- max_chars (int): Maximum number of characters allowed597- accept_file (bool, "multiple", "directory"): File acceptance configuration598- file_type (str or list): Accepted file types (e.g., [".jpg", ".png"])599- disabled (bool): Disable the input widget600- on_submit (callable): Function to call on submission601- args (tuple): Arguments to pass to on_submit function602- kwargs (dict): Keyword arguments to pass to on_submit function603- width (str): Widget width configuration604605Returns:606str or ChatInputValue or None: User input text or file data, None if no input607"""608609def chat_message(name, avatar=None, width="stretch"):610"""611Insert a chat message container for conversational interfaces.612613Parameters:614- name (str): Message author name ("user", "assistant", "ai", "human", or custom)615- avatar (str or image): Avatar image or emoji for the message616- width (str): Container width configuration617618Returns:619DeltaGenerator: Container for chat message content620"""621```622623#### Usage Examples624625```python626import streamlit as st627628# Initialize chat history629if "messages" not in st.session_state:630st.session_state.messages = []631632# Display chat messages from history633for message in st.session_state.messages:634with st.chat_message(message["role"]):635st.markdown(message["content"])636637# Chat input638if prompt := st.chat_input("What would you like to know?"):639# Add user message to chat history640st.session_state.messages.append({"role": "user", "content": prompt})641with st.chat_message("user"):642st.markdown(prompt)643644# Generate assistant response645response = f"Echo: {prompt}"646st.session_state.messages.append({"role": "assistant", "content": response})647with st.chat_message("assistant"):648st.markdown(response)649650# Chat input with file upload651prompt = st.chat_input("Send a message", accept_file="multiple", file_type=[".txt", ".py", ".md"])652653if prompt:654if hasattr(prompt, 'message') and hasattr(prompt, 'files'):655st.write(f"Message: {prompt.message}")656st.write(f"Files: {[f.name for f in prompt.files]}")657else:658st.write(f"Text message: {prompt}")659```