Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 37 ยท Testing and Patterns

Structuring Larger Gradio Apps

Organize a growing Gradio project: separate logic from UI, build tabs from functions, use gr.render, TabbedInterface, mount in FastAPI and share config, with runnable registry stand-ins.

Every Gradio app starts as one file. It stays comfortable until you have six tabs, three models, a database and a teammate. Then the single file turns into a maze where logic, layout and wiring are tangled together, and nobody dares edit it. A few structural habits keep growth manageable.

Real Gradio is not available on this site, so the framework code is read-only. The runnable blocks demonstrate the organizing ideas (registries, dependency injection, separation of logic from layout) in plain Python, labelled stand-ins.

Separate logic from layout

Split the project into three kinds of file:

TEXT
myapp/
  app.py            # builds the demo and launches it (thin)
  ui/
    chat_tab.py     # one function per tab: builds components and events
    settings_tab.py
  core/
    models.py       # loading and calling models
    prompts.py
    storage.py      # database or files
  tests/

The rule is core code never imports Gradio. Functions in core/ take plain values and return plain values, so you can test them without a UI (see testing) and reuse them in a command-line script or an API. The ui/ modules adapt those functions to components.

One function per tab

Each tab is a function that creates components inside the active Blocks context:

Python
# ui/chat_tab.py
import gradio as gr
from core.models import answer

def build(settings):
    with gr.Row():
        box = gr.Textbox(label="Question", scale=4)
        send = gr.Button("Ask", scale=1)
    out = gr.Markdown()
    send.click(lambda q: answer(q, settings), box, out)
Python
# app.py
import gradio as gr
from ui import chat_tab, settings_tab

def make_demo(settings):
    with gr.Blocks(title="My app") as demo:
        with gr.Tab("Chat"):
            chat_tab.build(settings)
        with gr.Tab("Settings"):
            settings_tab.build(settings)
    return demo

if __name__ == "__main__":
    make_demo(load_settings()).launch()

Components created inside build() belong to the enclosing with block, because Gradio tracks the current context. Passing shared objects as parameters (the settings argument) is called dependency injection: it avoids globals and lets tests pass in fake settings.

A factory such as make_demo is also kinder to tests, which can build one demo with fake services per test.

Gradio offers shortcuts when your tabs are already Interface objects: gr.TabbedInterface([app1, app2], ["Summarize", "Translate"]) creates a tab bar and one tab per interface, and an Interface or Blocks can be nested inside another with .render().

Plug-in style registries

When there are many similar things (models, tools, report types) a registry keeps the UI generic: add one entry and a new option appears. This stand-in shows the pattern with a decorator.

Python A registry of tools (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Adding a fourth tool is one decorated function; the dropdown and the dispatch code do not change. In Gradio the dropdown is gr.Dropdown(choices=list(TOOLS)) and one event handler calls TOOLS[name]["fn"](text).

Dynamic layouts with gr.render

Sometimes the layout itself depends on data: one card per search result, one input row per column in an uploaded CSV. @gr.render re-runs a function whenever its inputs change and rebuilds a part of the page:

Python
with gr.Blocks() as demo:
    n = gr.Slider(1, 5, step=1, value=2, label="How many boxes?")

    @gr.render(inputs=n)
    def boxes(count):
        for i in range(int(count)):
            gr.Textbox(label=f"Box {i + 1}")

Moving the slider to 4 makes four text boxes appear. Use it sparingly: every re-render sends new layout to the browser, and event handlers defined inside need care with the state they use. A short list of items is fine; a table of 10,000 rows is not (use gr.Dataframe).

Configuration and services

Read configuration once, in one place, from environment variables, and pass it down:

Python Config object and dependency injection

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The production service prints a model-tagged answer, and the test service returns FAKE. Swapping the backend without touching the logic is the whole point.

Mounting inside another web app

When Gradio is one page of a bigger site, mount it in FastAPI:

Python
from fastapi import FastAPI
import gradio as gr

app = FastAPI()

@app.get("/health")
def health():
    return {"ok": True}

demo = make_demo(load_settings())
app = gr.mount_gradio_app(app, demo, path="/ui")
# run with: uvicorn main:app --port 8000

The site now serves your own API routes (for example /health) and the Gradio UI at /ui. You get FastAPI's dependency system, middleware, and a place for your own authentication, while Gradio handles the interface. This also lets one process host several demos on different paths.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the main rule for the core/ folder?

    Plain functions are easy to test and reuse outside a UI.
  2. 2. How do tab-building functions add components to the right place?

    Gradio tracks the current with-block context, so components attach to it.
  3. 3. What does gr.mount_gradio_app do?

    It mounts the demo as a sub-application of the FastAPI server.
  4. 4. When is @gr.render useful?

    It rebuilds part of the layout when its inputs change.

Summary

  • Keep logic in Gradio-free modules; use thin UI modules and a thin app.py.
  • Build tabs with functions and inject shared services and settings.
  • Use registries for plug-in-style lists and @gr.render for data-driven layout.
  • Mount in FastAPI when Gradio is part of a larger site.

Next: Errors, Notifications and Performance