Simple HTML usecase

This is the classic gr.HTML usecase where we just want to render some static HTML.

Templated HTML usecase

'value' can now be anything, and it can be used inside the html_template using ${value} syntax. Note that when used as output or input, value is just this specific value rather than the entire HTML.

Name

Additional Props

You are not limited to using ${value} in the templates, you can add any number of custom tags to the template, and pass them to the component as keyword arguments. These props can be updated via python event listeners as well.

Font Size

10 100

CSS Templating

We can also template CSS, which is automatically scoped to the component.

Person

Text Color

Bold Text

JS Prop Updates

We can now trigger events from gr.HTML using event listeners in js_on_load. This script has access to element which refers to the parent element, and trigger(event_name) or trigger(event_name, event_data), which can be used to dispatch events.

Clicked

JS Prop Changes

You can also update value or any other prop of the component from JS using props, e.g., props.value = "new value" will update the value prop and re-render the HTML template.

Output Box

Watch API

Use watch inside js_on_load to run a callback after the template re-renders whenever specific props are changed from the backend (Python event listener). The callback is NOT triggered by frontend (JavaScript) changes to props. The callback takes no arguments — read current values from props directly.

Watch Output

Extending gr.HTML for new Components

You can create your own Components by extending the gr.HTML class.

File Upload via gr.HTML

The upload async function is available in js_on_load. It takes a JavaScript File object, uploads it to the Gradio server, and returns the server-side file path as a string.

Upload Result

HTML Children

Use @children in html_template to render child components inside the HTML wrapper.

Your Name

Your Email

Children Output

Server Functions

You can call Python functions from js_on_load using the server object. Pass a list of functions via server_functions and they become available as async methods on the server object in your JavaScript code.

Custom Events

You can trigger custom events (not in the standard event list) from js_on_load using trigger('custom_event_name', data). As long as the event name appears in quotes in js_on_load, you can attach a Python listener using component.custom_event_name(fn, ...).

Key Pressed

Head / Third-Party Scripts

The head parameter lets you load third-party JS/CSS libraries directly on the component. Scripts are deduplicated by src, so multiple components sharing the same library only load it once.