⚡ Event-Driven Python Architectures
Gradio goes beyond static interfaces by supporting rich event-driven programming. Using triggers like .click(), .change(), and .submit(), developers can link user actions directly to backend Python functions with full control over inputs, outputs, and reactive state updates.
Example 1: Button Click Event Trigger (`.click()`)
Triggers a backend Python text-processing function explicitly when the user clicks a submit button.
Python (event_click.py)
import gradio as gr
def calculate_bmi(weight, height):
bmi = weight / ((height / 100) ** 2)
category = "Underweight" if bmi < 18.5 else ("Normal" if bmi < 25 else "Overweight")
return f"BMI: {bmi:.2f} ({category})"
with gr.Blocks() as demo:
gr.Markdown("### BMI Calculator")
w_input = gr.Number(label="Weight (kg)", value=70)
h_input = gr.Number(label="Height (cm)", value=175)
btn = gr.Button("Calculate BMI", variant="primary")
output = gr.Textbox(label="Result")
# Explicit event binding
btn.click(fn=calculate_bmi, inputs=[w_input, h_input], outputs=output)
if __name__ == "__main__":
demo.launch()
Event Trigger: User clicks "Calculate BMI" button.
Inputs Mapping: [w_input, h_input] → Outputs Mapping: output
Inputs Mapping: [w_input, h_input] → Outputs Mapping: output
Example 2: Real-Time Slider Change Event (`.change()`)
Updates output values instantly as the user drags a slider without requiring a submit button click.
Python (event_change.py)
import gradio as gr
def convert_currency(usd):
inr = usd * 83.25
eur = usd * 0.92
return f"₹ {inr:,.2f} INR", f"€ {eur:,.2f} EUR"
with gr.Blocks() as demo:
gr.Markdown("### Real-Time Currency Converter")
usd_slider = gr.Slider(0, 1000, value=100, step=10, label="Amount in USD ($)")
with gr.Row():
out_inr = gr.Textbox(label="Indian Rupees (INR)")
out_eur = gr.Textbox(label="Euros (EUR)")
# Real-time event triggered on slider value change
usd_slider.change(fn=convert_currency, inputs=usd_slider, outputs=[out_inr, out_eur])
if __name__ == "__main__":
demo.launch()
Event Trigger: Slider value adjustment (`.change()`).
Inputs Mapping: usd_slider → Outputs Mapping: [out_inr, out_eur]
Inputs Mapping: usd_slider → Outputs Mapping: [out_inr, out_eur]
Example 3: Textbox Submit Event on Enter Key (`.submit()`)
Executes a search or AI query immediately when the user presses the Enter key inside a textbox.
Python (event_submit.py)
import gradio as gr
def search_database(query):
return f"🔍 Search Results for: '{query}' -> Found 3 matching records in database."
with gr.Blocks() as demo:
gr.Markdown("### Quick Search Portal")
search_box = gr.Textbox(label="Search Query", placeholder="Type and press Enter...")
results_box = gr.Textbox(label="Search Results")
# Triggered when Enter key is pressed inside textbox
search_box.submit(fn=search_database, inputs=search_box, outputs=results_box)
if __name__ == "__main__":
demo.launch()
Event Trigger: Pressing Enter key (`.submit()`).
Inputs Mapping: search_box → Outputs Mapping: results_box
Inputs Mapping: search_box → Outputs Mapping: results_box
Example 4: Multi-Step Dependent Dropdowns (`.change()`)
Dynamically updates secondary dropdown options based on the primary dropdown selection.
Python (event_dependent.py)
import gradio as gr
data = {
"India": ["Mumbai", "Pune", "Delhi", "Bangalore"],
"USA": ["New York", "San Francisco", "Chicago", "Austin"]
}
def update_cities(country):
cities = data.get(country, [])
return gr.update(choices=cities, value=cities[0] if cities else "")
with gr.Blocks() as demo:
gr.Markdown("### Region Selector")
country_drop = gr.Dropdown(choices=list(data.keys()), value="India", label="Select Country")
city_drop = gr.Dropdown(choices=data["India"], value="Mumbai", label="Select City")
# Update city options when country changes
country_drop.change(fn=update_cities, inputs=country_drop, outputs=city_drop)
if __name__ == "__main__":
demo.launch()
Event Trigger: Country dropdown selection change.
Dynamic Update: Re-renders city dropdown choices using `gr.update()`.
Dynamic Update: Re-renders city dropdown choices using `gr.update()`.
Example 5: Stateful Session Memory (`gr.State`)
Maintains persistent session state across multiple event interactions (e.g., a click counter).
Python (event_state.py)
import gradio as gr
def increment_counter(count):
new_count = count + 1
return new_count, f"Button clicked {new_count} times."
with gr.Blocks() as demo:
gr.Markdown("### Click Tracker with State")
count_state = gr.State(value=0) # Hidden state variable
btn = gr.Button("Click Me!")
output = gr.Textbox(label="Status")
btn.click(fn=increment_counter, inputs=count_state, outputs=[count_state, output])
if __name__ == "__main__":
demo.launch()
Event Trigger: Button click storing and updating integer value inside `gr.State`.
Example 6: Component Visibility Toggle (`.click()` with `gr.update()`)
Shows or hides form sections dynamically depending on checkbox selections or button clicks.
Python (event_visibility.py)
import gradio as gr
def toggle_advanced(show):
return gr.update(visible=show)
with gr.Blocks() as demo:
gr.Markdown("### Advanced Settings Toggle")
chk = gr.Checkbox(label="Show Advanced Options", value=False)
adv_box = gr.Textbox(label="Advanced API Key", visible=False)
chk.change(fn=toggle_advanced, inputs=chk, outputs=adv_box)
if __name__ == "__main__":
demo.launch()
Event Trigger: Checkbox state change toggling component visibility attribute dynamically.
Example 7: Multi-Input Chained Event Pipeline
Combines multiple input widgets (sliders, checkboxes, text) into a unified calculation function.
Python (event_pipeline.py)
import gradio as gr
fn = lambda base, tax, discount: f"Final Total: $ {(base * (1 + tax/100)) - discount:.2f}"
with gr.Blocks() as demo:
gr.Markdown("### Invoice Discount Calculator")
base_price = gr.Number(value=200, label="Base Price ($)")
tax_rate = gr.Slider(0, 20, value=5, label="Tax Rate (%)")
discount_val = gr.Number(value=10, label="Flat Discount ($)")
calc_btn = gr.Button("Compute Total")
res = gr.Textbox(label="Invoice Summary")
calc_btn.click(fn=fn, inputs=[base_price, tax_rate, discount_val], outputs=res)
if __name__ == "__main__":
demo.launch()
Event Trigger: Button click executing calculation across three distinct input controls.
Example 8: File Upload & Auto-Processing Event (`.upload()`)
Triggers data extraction or image analysis automatically the moment a file is uploaded.
Python (event_upload.py)
import gradio as gr
def get_file_info(file):
if file is None:
return "No file uploaded."
return f"Uploaded File Name: {file.name} | Size: {len(file.read())} bytes"
with gr.Blocks() as demo:
gr.Markdown("### Auto File Inspector")
file_upload = gr.File(label="Upload Document")
info_box = gr.Textbox(label="File Metadata")
# Triggered automatically upon successful file upload
file_upload.upload(fn=get_file_info, inputs=file_upload, outputs=info_box)
if __name__ == "__main__":
demo.launch()
Event Trigger: File upload completion (`.upload()`).
Outputs Mapping: info_box
Outputs Mapping: info_box
Example 9: Clear / Reset Form Event (`.click()` with Reset)
Resets all input fields and outputs back to their default state when a clear button is clicked.
Python (event_clear.py)
import gradio as gr
with gr.Blocks() as demo:
gr.Markdown("### Form Reset Example")
txt_input = gr.Textbox(label="Enter Feedback")
txt_output = gr.Textbox(label="Confirmation")
submit_btn = gr.Button("Submit")
clear_btn = gr.Button("Clear Form")
submit_btn.click(fn=lambda x: f"Submitted: {x}", inputs=txt_input, outputs=txt_output)
# Reset event clearing values
clear_btn.click(fn=lambda: ("", ""), inputs=None, outputs=[txt_input, txt_output])
if __name__ == "__main__":
demo.launch()
Event Trigger: Clear button click returning empty string updates to reset form components.
Example 10: Asynchronous / Non-Blocking Long Tasks (`queue()`)
Handles slow backend operations using Gradio queuing to prevent blocking concurrent users.
Python (event_queue.py)
import gradio as gr
import time
def slow_ai_process(prompt):
time.sleep(3) # Simulate heavy model inference
return f"AI Generated Response for: '{prompt}'"
with gr.Blocks() as demo:
gr.Markdown("### Queued AI Inference Worker")
prompt_box = gr.Textbox(label="Prompt")
run_btn = gr.Button("Generate")
response_box = gr.Textbox(label="Response")
run_btn.click(fn=slow_ai_process, inputs=prompt_box, outputs=response_box)
# Enable queuing for concurrent request handling
demo.queue()
if __name__ == "__main__":
demo.launch()
Event Trigger: Button click managed by `demo.queue()` to handle concurrent user workloads smoothly.