Skip to main content
Gradio events allow you to attach event listeners to components, triggering functions when specific user interactions occur.

​
Common Event Methods

Most Gradio components support the following event listeners:

​
change

Triggered when the value of the component changes either because of user input OR because of a function update. 
component.change(fn, inputs, outputs)

​
input

Triggered when the user changes the value of the component. 
component.input(fn, inputs, outputs)

​
click

Triggered when the component is clicked. 
component.click(fn, inputs, outputs)

​
submit

Triggered when the user presses enter in a textbox or clicks the submit button. 
component.submit(fn, inputs, outputs)

​
select

Triggered when the user selects an item in the component. 
component.select(fn, inputs, outputs)

​
Event Parameters

All event methods accept the following parameters:
​
fn
Callable | None
default:"None"
The function to call when this event is triggered. Each parameter of the function corresponds to one input component, and the function should return a single value or a tuple of values, with each element in the tuple corresponding to one output component.
​
inputs
Component | Sequence[Component] | None
default:"None"
List of gradio components to use as inputs. If the function takes no inputs, this should be an empty list.
​
outputs
Component | Sequence[Component] | None
default:"None"
List of gradio components to use as outputs. If the function returns no outputs, this should be an empty list.
​
api_name
str | None
default:"None"
Defines how the endpoint appears in the API docs. Can be a string or None. If set to a string, the endpoint will be exposed in the API docs with the given name.
​
api_description
str | None | Literal[False]
default:"None"
Description of the API endpoint. Can be a string, None, or False.
​
scroll_to_output
bool
default:"False"
If True, will scroll to output component on completion.
​
show_progress
Literal['full', 'minimal', 'hidden']
default:"'full'"
How to show the progress animation while event is running: “full” shows a spinner which covers the output component area as well as a runtime display in the upper right corner, “minimal” only shows the runtime display, “hidden” shows no progress animation at all.
​
queue
bool
default:"True"
If True, will place the request on the queue, if the queue has been enabled. If False, will not put this event on the queue, even if the queue has been enabled.
​
batch
bool
default:"False"
If True, then the function should process a batch of inputs, meaning that it should accept a list of input values for each parameter.
​
max_batch_size
int
default:"4"
Maximum number of inputs to batch together if this is called from the queue (only relevant if batch=True).
​
preprocess
bool
default:"True"
If False, will not run preprocessing of component data before running ‘fn’.
​
postprocess
bool
default:"True"
If False, will not run postprocessing of component data before returning ‘fn’ output to the browser.
​
cancels
dict | list[dict] | None
default:"None"
A list of other events to cancel when this listener is triggered. For example, setting cancels=[click_event] will cancel the click_event.
​
trigger_mode
Literal['once', 'multiple', 'always_last'] | None
default:"None"
If “once” (default for all events except .change()) would not allow any submissions while an event is pending. If set to “multiple”, unlimited submissions are allowed while pending, and “always_last” (default for .change() and .key_up() events) would allow a second submission after the pending event is complete.
​
js
str | Literal[True] | None
default:"None"
Optional frontend js method to run before running ‘fn’. Input arguments for js method are values of ‘inputs’ and ‘outputs’, return should be a list of values for output components.
​
concurrency_limit
int | None | Literal['default']
default:"'default'"
If set, this is the maximum number of this event that can be running simultaneously. Can be set to None to mean no concurrency_limit.
​
concurrency_id
str | None
default:"None"
If set, this is the id of the concurrency group. Events with the same concurrency_id will be limited by the lowest set concurrency_limit.
​
api_visibility
Literal['public', 'private', 'undocumented']
default:"'public'"
Controls the visibility and accessibility of this endpoint. Can be “public” (shown in API docs and callable), “private” (hidden from API docs and not callable), or “undocumented” (hidden from API docs but callable).
​
validator
Callable | None
default:"None"
Optional validation function to run before the main function. If provided, this function will be executed first with queue=False, and only if it completes successfully will the main function be called.

​
Dependency Object

Event methods return a Dependency object that can be used to chain events:

​
then

Triggered after directly preceding event is completed, regardless of success or failure. 
dependency.then(fn, inputs, outputs)

​
success

Triggered after directly preceding event is completed, if it was successful. 
dependency.success(fn, inputs, outputs)

​
failure

Triggered after directly preceding event is completed, if it failed. 
dependency.failure(fn, inputs, outputs)

​
Example

import gradio as gr

with gr.Blocks() as demo:
    first_textbox = gr.Textbox()
    second_textbox = gr.Textbox()
    button = gr.Button("Submit")
    
    dependency = button.click(
        lambda x: "Hello, " + x,
        first_textbox,
        second_textbox
    )
    dependency.success(
        lambda: gr.Info("Greeting successful"),
        None,
        None
    )
    dependency.failure(
        lambda: gr.Warning("Greeting failed"),
        None,
        None
    )

demo.launch()

Build docs developers (and LLMs) love

Get started for freeTalk to us