gradio

Gradio

Gradio is a Python library for building interactive web UIs and ML demos. This skill covers the core API, patterns, and examples.

Guides

Detailed guides on specific topics (read these when relevant):

Quickstart
The Interface Class
Blocks and Event Listeners
Controlling Layout
More Blocks Features
Custom CSS and JS
Streaming Outputs
Streaming Inputs
Sharing Your App
Custom HTML Components
Getting Started with the Python Client
Getting Started with the JS Client

Core Patterns

Interface (high-level): wraps a function with input/output components.

import gradio as gr

def greet(name): return f"Hello {name}!"

gr.Interface(fn=greet, inputs="text", outputs="text").launch()

Blocks (low-level): flexible layout with explicit event wiring.

import gradio as gr

with gr.Blocks() as demo: name = gr.Textbox(label="Name") output = gr.Textbox(label="Greeting") btn = gr.Button("Greet") btn.click(fn=lambda n: f"Hello {n}!", inputs=name, outputs=output)

demo.launch()

ChatInterface: high-level wrapper for chatbot UIs.

import gradio as gr

def respond(message, history): return f"You said: {message}"

gr.ChatInterface(fn=respond).launch()

Key Component Signatures

Creates a textarea for user to enter string input or display string output..

Creates a numeric field for user to enter numbers as input or display numeric output..

Creates a slider that ranges from {minimum} to {maximum} with a step size of {step}..

Creates a checkbox that can be set to True or False .

Creates a dropdown of choices from which a single entry or multiple entries can be selected (as an input component) or displayed (as an output component)..

Creates a set of (string or numeric type) radio buttons of which only one can be selected..

Creates an image component that can be used to upload images (as an input) or display images (as an output)..

Creates an audio component that can be used to upload/record audio (as an input) or display audio (as an output)..

Creates a video component that can be used to upload/record videos (as an input) or display videos (as an output).

Creates a file component that allows uploading one or more generic files (when used as an input) or displaying generic files or URLs for download (as output).

Creates a chatbot that displays user-submitted messages and responses.

Creates a button that can be assigned arbitrary .click() events.

Used to render arbitrary Markdown output.

HTML(value: Any | Callable | None = None, label: str | I18nData | None = None, html_template: str = "${value}", css_template: str = "", js_on_load: str | None = "element.addEventListener('click', function() { trigger('click') });", apply_default_css: bool = True, every: Timer | float | None = None, inputs: Component | Sequence[Component] | set[Component] | None = None, show_label: bool = False, visible: bool | Literal['hidden'] = True, elem_id: str | None = None, elem_classes: list[str] | str | None = None, render: bool = True, key: int | str | tuple[int | str, ...] | None = None, preserved_by_key: list[str] | str | None = "value", min_height: int | None = None, max_height: int | None = None, container: bool = False, padding: bool = False, autoscroll: bool = False, buttons: list[Button] | None = None, props: Any)

Creates a component with arbitrary HTML.

Custom HTML Components

If a task requires significant customization of an existing component or a component that doesn't exist in Gradio, you can create one with gr.HTML . It supports html_template (with ${} JS expressions and {{}} Handlebars syntax), css_template for scoped styles, and js_on_load for interactivity — where props.value updates the component value and trigger('event_name') fires Gradio events. For reuse, subclass gr.HTML and define api_info() for API/MCP support. See the full guide.

Here's an example that shows how to create and use these kinds of components:

import gradio as gr

class StarRating(gr.HTML): def init(self, label, value=0, **kwargs): html_template = """ <h2>${label} rating:</h2> ${Array.from({length: 5}, (_, i) => <img class='${i < value ? '' : 'faded'}' src='https://upload.wikimedia.org/wikipedia/commons/d/df/Award-star-gold-3d.svg'>).join('')} """ css_template = """ img { height: 50px; display: inline-block; cursor: pointer; } .faded { filter: grayscale(100%); opacity: 0.3; } """ js_on_load = """ const imgs = element.querySelectorAll('img'); imgs.forEach((img, index) => { img.addEventListener('click', () => { props.value = index + 1; }); }); """ super().init(value=value, label=label, html_template=html_template, css_template=css_template, js_on_load=js_on_load, **kwargs)

def api_info(self):
    return {"type": "integer", "minimum": 0, "maximum": 5}

with gr.Blocks() as demo: gr.Markdown("# Restaurant Review") food_rating = StarRating(label="Food", value=3) service_rating = StarRating(label="Service", value=3) ambience_rating = StarRating(label="Ambience", value=3) average_btn = gr.Button("Calculate Average Rating") rating_output = StarRating(label="Average", value=3) def calculate_average(food, service, ambience): return round((food + service + ambience) / 3) average_btn.click( fn=calculate_average, inputs=[food_rating, service_rating, ambience_rating], outputs=rating_output )

demo.launch()

Event Listeners

All event listeners share the same signature:

Supported events per component:

AnnotatedImage: select
Audio: stream, change, clear, play, pause, stop, pause, start_recording, pause_recording, stop_recording, upload, input
BarPlot: select, double_click
BrowserState: change
Button: click
Chatbot: change, select, like, retry, undo, example_select, option_select, clear, copy, edit
Checkbox: change, input, select
CheckboxGroup: change, input, select
ClearButton: click
Code: change, input, focus, blur
ColorPicker: change, input, submit, focus, blur
Dataframe: change, input, select, edit
Dataset: click, select
DateTime: change, submit
DeepLinkButton: click
Dialogue: change, input, submit
DownloadButton: click
Dropdown: change, input, select, focus, blur, key_up
DuplicateButton: click
File: change, select, clear, upload, delete, download
FileExplorer: change, input, select
Gallery: select, upload, change, delete, preview_close, preview_open
HTML: change, input, click, double_click, submit, stop, edit, clear, play, pause, end, start_recording, pause_recording, stop_recording, focus, blur, upload, release, select, stream, like, example_select, option_select, load, key_up, apply, delete, tick, undo, retry, expand, collapse, download, copy
HighlightedText: change, select
Image: clear, change, stream, select, upload, input
ImageEditor: clear, change, input, select, upload, apply
ImageSlider: clear, change, stream, select, upload, input
JSON: change
Label: change, select
LinePlot: select, double_click
LoginButton: click
Markdown: change, copy
Model3D: change, upload, edit, clear
MultimodalTextbox: change, input, select, submit, focus, blur, stop
Navbar: change
Number: change, input, submit, focus, blur
ParamViewer: change, upload
Plot: change
Radio: select, change, input
ScatterPlot: select, double_click
SimpleImage: clear, change, upload
Slider: change, input, release
State: change
Textbox: change, input, select, submit, focus, blur, stop, copy
Timer: tick
UploadButton: click, upload
Video: change, clear, start_recording, stop_recording, stop, play, pause, end, upload, input

Additional Reference

End-to-End Examples — complete working apps

Safety Notice

Copy this and send it to your AI assistant to learn

Source Transparency

Related Skills

hugging-face-cli

hf-cli

hugging-face-model-trainer