Event Listeners

Gradio provides several event listener functions that can be used to attach multiple events to a single function.

on

gr.on(
    triggers,
    fn,
    inputs=None,
    outputs=None,
    api_visibility="public",
    api_name=None,
    api_description=None,
    scroll_to_output=False,
    show_progress="full",
    queue=True,
    batch=False,
    max_batch_size=4,
    preprocess=True,
    postprocess=True,
    cancels=None,
    trigger_mode=None,
    js=None,
    concurrency_limit="default",
    concurrency_id=None,
    validator=None
)

Sets up an event listener that triggers a function when the specified event(s) occur. This is especially useful when the same function should be triggered by multiple events. Only a single API endpoint is generated for all events in the triggers list.

Parameters

Sequence[EventListenerCallable] | EventListenerCallable | None

default:"None"

List of triggers to listen to, e.g. [btn.click, number.change]. If None, will run on app load and changes to any inputs.

Callable | None

default:"None"

The function to call when this event is triggered.

Component | Sequence[Component] | None

default:"None"

List of gradio components to use as inputs.

Component | Sequence[Component] | None

default:"None"

List of gradio components to use as outputs.

Example

import gradio as gr

with gr.Blocks() as demo:
    with gr.Row():
        input = gr.Textbox()
        button = gr.Button("Submit")
    output = gr.Textbox()
    
    gr.on(
        triggers=[button.click, input.submit],
        fn=lambda x: x,
        inputs=[input],
        outputs=[output]
    )

demo.launch()

api

gr.api(
    fn,
    api_name=None,
    api_description=None,
    queue=True,
    batch=False,
    max_batch_size=4,
    concurrency_limit="default",
    concurrency_id=None,
    api_visibility="public"
)

Sets up an API or MCP endpoint for a generic function without needing to define event listeners or components. Derives its typing from type hints in the provided function’s signature rather than the components.

Parameters

Callable

required

The function to call when this event is triggered. The function should be fully typed, and the type hints will be used to derive the typing information for the API/MCP endpoint.

str | None

default:"None"

Defines how the endpoint appears in the API docs.

str | None

default:"None"

Description of the API endpoint.

bool

default:"True"

If True, will place the request on the queue.

bool

default:"False"

If True, then the function should process a batch of inputs.

int

default:"4"

Maximum number of inputs to batch together.

int | None | Literal['default']

default:"'default'"

If set, this is the maximum number of this event that can be running simultaneously.

str | None

default:"None"

If set, this is the id of the concurrency group.

Literal['public', 'private', 'undocumented']

default:"'public'"

Controls the visibility and accessibility of this endpoint.

Example

import gradio as gr

with gr.Blocks() as demo:
    def add_and_slice(a: int, b: int, c: list[str]) -> tuple[int, str]:
        return a + b, c[a:b]
    
    gr.api(add_and_slice, api_name="add_and_slice")

demo.launch()

Core Classes

Events

Helpers

Themes

Event Listeners

on

Parameters

Example

api

Parameters

Example

​on

​Parameters

​Example

​api

​Parameters

​Example

on

Parameters

Example

api

Parameters

Example