run.py

import os
import gradio as gr


with gr.Blocks() as demo:
    gr.Markdown("""
    # Simple HTML usecase
    This is the classic `gr.HTML` usecase where we just want to render some static HTML.
    """)
    simple_html = gr.HTML("<h1 style='color:purple;' id='simple'>Hello, World!</h1>")

    gr.Markdown("""
    # 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.
    """)
    with gr.Row():
        name1 = gr.Textbox(label="Name")
        templated_html = gr.HTML(
            "",
            html_template="<h1>Hello, {{value}}! ${value.length} letters</h1>",
            elem_id="templated",
        )
        name1.change(lambda x: x, inputs=name1, outputs=templated_html)

    gr.Markdown("""
    # 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.
    """)
    with gr.Row():
        templated_html_props = gr.HTML(
            "John",
            html_template="""
                <h1 style="font-size: ${fontSize}px;">Hello, ${value}!</h1>
            """,
            fontSize=30,
            elem_id="props",
        )
        slider = gr.Slider(10, 100, value=30, label="Font Size")
        slider.change(
            lambda x: gr.HTML(fontSize=x), inputs=slider, outputs=templated_html_props
        )

    gr.Markdown("""
    # CSS Templating
    We can also template CSS, which is automatically scoped to the component.
    """)
    with gr.Row():
        name2 = gr.Textbox(label="Person")
        color = gr.ColorPicker(label="Text Color", value="#00ff00")
        bold = gr.Checkbox(label="Bold Text", value=True)
        templated_html_css = gr.HTML(
            ["J", "o", "h", "n"],
            html_template="""
                <h1>Hello, ${value.join('')}!</h1>
                <ul>
                    {{#each value}}
                    <li>{{this}}</li>
                    {{/each}}
                </ul>
            """,
            css_template="""
                h1, li {
                    color: ${color};
                    font-weight: ${bold ? 'bold' : 'normal'};
                }
            """,
            color="green",
            bold=True,
            elem_id="css",
        )
    with gr.Row():
        btn = gr.Button("Update HTML")
        btn_blue = gr.Button("Make HTML Blue")

    def update_templated_html_css(name, color, bold):
        return gr.HTML(value=list(name), color=color, bold=bold)

    btn.click(
        update_templated_html_css,
        inputs=[name2, color, bold],
        outputs=templated_html_css,
    )
    btn_blue.click(lambda: gr.HTML(color="blue"), outputs=templated_html_css)

    gr.Markdown("""
    # 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.
    """)

    button_set = gr.HTML(
        html_template="""
        <button id='A'>A</button>
        <button id='B'>B</button>
        <button id='C'>C</button>
        """,
        css_template="""
        button {
            padding: 10px;
            background-color: red;
        }
        """,
        js_on_load="""
        const buttons = element.querySelectorAll('button');
        buttons.forEach(button => {
            button.addEventListener('click', () => {
                trigger('click', {clicked: button.innerText});
            });
        });
        """,
        elem_id="button_set",
    )
    clicked_box = gr.Textbox(label="Clicked")

    def on_button_click(evt: gr.EventData):
        return evt.clicked

    button_set.click(on_button_click, outputs=clicked_box)

    gr.Markdown("""
    # 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.
    """)
    form = gr.HTML(
        html_template="""
        <input type="text" value="${value}" id="text-input" />
        <p>${value.length} letters</p>
        <button class="submit" style="display: ${valid ? 'block' : 'none'};">submit</button>
        <button class="clear">clear</button>
        """,
        js_on_load="""
        const input = element.querySelector('input');
        const submit_button = element.querySelector('button.submit');
        const clear_button = element.querySelector('button.clear');
        input.addEventListener('input', () => {
            props.valid = input.value.length > 5;
            props.value = input.value;
        });
        submit_button.addEventListener('click', () => {
            trigger('submit');
        });
        clear_button.addEventListener('click', () => {
            props.value = "";
            props.valid = false;
            trigger('clear');
        });
    """,
        valid=False,
        elem_id="form",
    )
    output_box = gr.Textbox(label="Output Box")
    form.submit(lambda x: x, form, outputs=output_box)
    output_box.submit(lambda x: x, output_box, outputs=form)

    gr.Markdown("""
    # 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_html = gr.HTML(
        value=0,
        html_template="""
        <div>
            <div>value: ${value}</div>
        </div>
        """,
        js_on_load="""
        watch('value', () => {
            if (props.value >= 3) {
                trigger('submit');
            }
        });
        """,
        elem_id="watch_demo",
    )
    watch_output = gr.Textbox(label="Watch Output")
    watch_inc_btn = gr.Button("Increment")
    watch_inc_btn.click(lambda x: (x or 0) + 1, watch_html, outputs=watch_html)
    watch_html.submit(lambda x: x, watch_html, outputs=watch_output)

    gr.Markdown("""
    # Extending gr.HTML for new Components
    You can create your own Components by extending the gr.HTML class.
    """)

    class ListComponent(gr.HTML):
        def __init__(self, container=True, label="List", ordered=False, **kwargs):
            self.ordered = ordered
            super().__init__(
                html_template="""
                <h2>${label}</h2>
                ${ordered ? `<ol>` : `<ul>`}
                    ${value.map(item => `<li>${item}</li>`).join('')}
                ${ordered ? `</ol>` : `</ul>`}
                """,
                container=container,
                label=label,
                ordered=ordered,
                **kwargs,
            )

    l1 = ListComponent(
        label="Fruits", value=["Apple", "Banana", "Cherry"], elem_id="fruits"
    )
    l2 = ListComponent(
        label="Vegetables",
        value=["Carrot", "Broccoli", "Spinach"],
        elem_id="vegetables",
    )

    make_ordered_btn = gr.Button("Make Ordered")
    make_unordered_btn = gr.Button("Make Unordered")

    make_ordered_btn.click(
        lambda: [ListComponent(ordered=True), ListComponent(ordered=True)],
        outputs=[l1, l2],
    )
    make_unordered_btn.click(
        lambda: [ListComponent(ordered=False), ListComponent(ordered=False)],
        outputs=[l1, l2],
    )

    failed_template = gr.HTML(
        value=None,
        html_template="""
          ${Zalue}
        """,
    )

    gr.Markdown("""
    # 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_html = gr.HTML(
        html_template="""
        <div>
            <input type="file" id="html-file-input" />
            <button id="html-upload-btn" style="margin-left: 8px; padding: 4px 8px;">Upload</button>
            <p id="html-upload-status">No file uploaded yet.</p>
        </div>
        """,
        js_on_load="""
        const input = element.querySelector('#html-file-input');
        const btn = element.querySelector('#html-upload-btn');
        const status = element.querySelector('#html-upload-status');

        btn.addEventListener('click', async () => {
            const file = input.files[0];
            if (!file) {
                status.textContent = 'Please select a file first.';
                return;
            }
            status.textContent = 'Uploading...';
            try {
                const { path, url } = await upload(file);
                status.textContent = 'Uploaded: ' + path;
                trigger('upload', { path: path, url: url, name: file.name });
            } catch (e) {
                status.textContent = 'Upload failed: ' + e.message;
            }
        });
        """,
        elem_id="upload_html"
    )
    upload_result = gr.Textbox(label="Upload Result", elem_id="upload_result")

    def on_html_upload(evt: gr.EventData):
        return evt.path

    upload_html.upload(on_html_upload, outputs=upload_result)

    class TodoList(gr.HTML):
        def __init__(
            self,
            value: list[str] | None = None,
            completed: list[int] | None = None,
            **kwargs,
        ):
            self.completed = completed or []
            super().__init__(
                html_template="""
                <h2>Todo List</h2>
                <ul>
                    ${value.map((item, index) => `
                        <li style="text-decoration: ${completed.includes(index) ? 'line-through' : 'none'};">
                            <input type="checkbox" ${completed.includes(index) ? 'checked' : ''} data-index="${index}" />
                            ${item}
                        </li>
                    `).join('')}
                </ul>
                """,
                js_on_load="""
                const checkboxes = element.querySelectorAll('input[type="checkbox"]');
                checkboxes.forEach(checkbox => {
                    checkbox.addEventListener('change', () => {
                        const index = parseInt(checkbox.getAttribute('data-index'));
                        let completed = props.completed || [];
                        if (checkbox.checked) {
                            if (!completed.includes(index)) {
                                completed.push(index);
                            }
                        } else {
                            completed = completed.filter(i => i !== index);
                        }
                        props.completed = [...completed];
                        console.log(JSON.stringify(props.completed))
                    });
                });
                """,
                completed=self.completed,
                value=value,
                **kwargs,
            )

    todo_list = TodoList(
        value=["Buy groceries", "Walk the dog", "Read a book"],
        completed=[1],
        elem_id="todo",
    )

    gr.Markdown("""
    # HTML Children
    Use `@children` in `html_template` to render child components inside the HTML wrapper.
    """)
    with gr.HTML(
        html_template="""
        <h2>${title}</h2>
        @children
        <button class="send">Send</button>
    """,
        css_template="""
        border: 2px solid gray;
        border-radius: 8px;
        padding: 16px;
    """,
        js_on_load="""
        element.querySelector('.send').addEventListener('click', () => {
            trigger('submit');
        });
    """,
        title="Contact Form",
        elem_id="children_form",
    ) as children_form:
        children_name = gr.Textbox(label="Your Name")
        children_email = gr.Textbox(label="Your Email")

    children_output = gr.Textbox(label="Children Output")
    children_form.submit(
        lambda name, email: f"Name: {name}, Email: {email}",
        inputs=[children_name, children_email],
        outputs=children_output,
    )

    gr.Markdown("""
    # 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.
    """)

    def list_directory(path):
        try:
            items = sorted(os.listdir(path))
            return [
                {"name": item, "is_dir": os.path.isdir(os.path.join(path, item))}
                for item in items[:20]
            ]
        except (FileNotFoundError, PermissionError):
            return []

    server_fn_html = gr.HTML(
        value=os.path.dirname(__file__),
        html_template="""
            <div>
                <p>Directory: <strong>${value}</strong></p>
                <div id='server-fn-tree'></div>
                <button id='server-fn-load'>Load Files</button>
            </div>
        """,
        js_on_load="""
            const loadBtn = element.querySelector('#server-fn-load');
            const tree = element.querySelector('#server-fn-tree');
            loadBtn.addEventListener('click', async () => {
                tree.innerHTML = '<em>Loading...</em>';
                const items = await server.list_directory(props.value);
                tree.innerHTML = '';
                items.forEach(item => {
                    const el = document.createElement('div');
                    el.textContent = (item.is_dir ? '📁 ' : '📄 ') + item.name;
                    el.className = 'server-fn-item';
                    tree.appendChild(el);
                });
            });
        """,
        css_template="""
            #server-fn-tree { padding: 8px; min-height: 20px; }
            .server-fn-item { padding: 2px 8px; }
            #server-fn-load { padding: 6px 12px; margin-top: 8px; }
        """,
        server_functions=[list_directory],
        elem_id="server_fns",
    )

    gr.Markdown("""
    # 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, ...)`.
    """)

    keyboard = gr.HTML(
        html_template="<p>Press any key...</p>",
        js_on_load="""
        document.addEventListener('keydown', (e) => {
            trigger('keypress', {key: e.key});
        });
        """,
        elem_id="custom_event",
    )

    key_output = gr.Textbox(label="Key Pressed", elem_id="key_output")

    def get_key(evt_data: gr.EventData):
        return evt_data.key

    keyboard.keypress(get_key, None, key_output)

    gr.Markdown("""
    # 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.
    """)

    head_html = gr.HTML(
        value=[30, 70, 45, 90, 60],
        html_template="""
        <canvas id="head-chart" width="300" height="200"></canvas>
        """,
        js_on_load="""
        const canvas = element.querySelector('#head-chart');
        new Chart(canvas, {
            type: 'bar',
            data: {
                labels: props.value.map((_, i) => 'Item ' + (i + 1)),
                datasets: [{
                    label: 'Values',
                    data: props.value,
                    backgroundColor: 'rgba(99, 132, 255, 0.5)',
                }]
            },
            options: { responsive: false }
        });
        """,
        head='<script src="https://cdn.jsdelivr.net/npm/chart.js@4.4.7/dist/chart.umd.min.js"></script>',
        elem_id="head_demo",
    )

if __name__ == "__main__":
    demo.launch()