Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 37 ยท State and Events

Event Listeners: click, change, submit, load and more

Learn every common Gradio event: click, change, input, submit, select, load, focus and blur. Understand inputs, outputs, triggers lists, gr.on and per-event options.

Events are how a Blocks app reacts. A component announces that something happened (a click, an edit, a selection, the page loading), and you attach a Python function to that announcement. Getting events right means knowing which one to choose (change and input look similar but are not), how to attach several triggers to one function, and which options (api_name, queue, show_progress) apply. Gradio code is read-only; stand-ins implement an event bus.

The general form

Every event listener has the same shape:

Python
component.event_name(
    fn=my_function,
    inputs=[a, b],          # components whose values are passed in
    outputs=[c],            # components that receive the return value(s)
    api_name="my_endpoint",
    show_progress="full",   # "full", "minimal" or "hidden"
)

inputs are read at the moment the event fires. outputs receive the return values by position. Either may be omitted: an event with no inputs calls the function with no arguments, and one with no outputs is for side effects (writing to a log, calling an API).

The events you will use

Event Fires when Typical component
click The user presses a button Button
change The value changes for any reason, including when another function sets it Textbox, Slider, ...
input The user changes the value (typing, dragging), not code Textbox, Slider
submit The user presses Enter in a single-line Textbox Textbox
select The user picks an item (a Dropdown option, a gallery image, a table cell, a tab) many
focus, blur A field gains or loses focus Textbox
upload, clear A file is added or removed File, Image
load The page loads in a browser (use demo.load) Blocks
tick A gr.Timer fires on its interval Timer

change versus input

This difference causes many loops and surprises. change also fires when your own function updates the component. If a.change updates b and b.change updates a, you create an infinite loop. input reacts to user actions only, so it is the safe choice for "when the user types". For one-way flows (text changes, result updates) either works; use input when your function also writes into the same component.

select with details

select listeners can ask for event data by adding a parameter with the type gr.SelectData:

Python
def on_select(evt: gr.SelectData):
    return f"You picked {evt.value} at index {evt.index}"

dropdown.select(on_select, None, output)

Gradio detects the type hint and fills the argument; it does not need to appear in inputs. Other event data classes exist for likes, key presses and more.

Several triggers, one function

Use gr.on to attach the same function to several triggers:

Python
gr.on(
    triggers=[button.click, textbox.submit],
    fn=search,
    inputs=textbox,
    outputs=results,
)

The search runs when the button is pressed or Enter is pressed. That removes the copy-paste of two listeners. If triggers is omitted, gr.on binds to every change event of the inputs, which gives "live" behaviour for a Blocks app (similar to Interface(live=True)).

Page load

Python
with gr.Blocks() as demo:
    greeting = gr.Markdown()
    demo.load(lambda: "Welcome back!", None, greeting)

demo.load runs each time a user opens the page (not once per server start), which makes it the place to fetch fresh data or set per-user defaults. Expensive work belongs elsewhere or behind a cache.

Useful per-event options

  • api_name: the endpoint name; False hides it from the API.
  • queue=False: skip the queue for a tiny, instant function.
  • show_progress: "hidden" removes the spinner, useful for tiny updates.
  • trigger_mode: "once" ignores new triggers while the event runs, "always_last" runs only the latest after the current finishes, and "multiple" allows overlap. It is the best fix for a change handler that is too slow for typing.
  • concurrency_limit and concurrency_id: limit simultaneous runs (see queue and concurrency).
  • scroll_to_output=True and preprocess=False / postprocess=False for special cases.
  • js="...": run a JavaScript snippet in the browser instead of (or before) Python.

Stand-in 1: an event bus

This stand-in is our own code. It stores listeners per trigger and shows the difference between change and input.

Python Stand-in: events, listeners and change vs input

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The code-driven update fires only change. A change handler that sets its own source component would loop forever; input avoids this.

Stand-in 2: one function, several triggers

Python Stand-in: gr.on with multiple triggers

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Both triggers share one implementation, so fixing a bug in search fixes both.

Common mistakes

  • Using change for a handler that updates its own source: infinite loops.
  • Returning the wrong number of values for the outputs list.
  • Reading outputs components in the function body (they are not passed unless also listed in inputs).
  • Expecting load to run once per server start; it runs per page view.
  • Doing slow work in input: add trigger_mode="always_last" or use a button.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which event fires only for user edits, not for changes made by code?

    input reacts to user actions. change also fires when a function sets the value.
  2. 2. How do you run one function for a button click and an Enter key press?

    gr.on accepts a list of triggers.
  3. 3. When does demo.load run?

    It is a page-load event for every visitor.
  4. 4. Which trigger_mode makes a slow change handler run only the latest request after the current one ends?

    always_last skips the intermediate triggers and runs the newest one when free.

Summary

  • Events follow component.event(fn, inputs, outputs).
  • click, change, input, submit, select, load and tick cover most needs.
  • change also fires on programmatic updates; input does not.
  • gr.on attaches several triggers; SelectData type hints provide event details.
  • Tune events with api_name, trigger_mode, queue and show_progress.

Next: Event Chaining with then, success and Timers