Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 37 ยท Interfaces and Components

The Interface Class in Depth

Understand gr.Interface fully: fn, inputs, outputs, multiple values, return tuples, titles, articles, buttons, live mode and how to choose between Interface and Blocks.

gr.Interface is Gradio's high-level class. You give it a function and lists of input and output components, and it builds the whole page: a form on the left (or top), a result area, buttons, examples, flagging and an API. For a large share of real demos it is all you need. This lesson covers every important argument, how multiple inputs and outputs work, and when to move on to Blocks.

Gradio code is read-only here; stand-ins show the mapping rules in plain Python.

The three required ideas

Python
import gradio as gr

def bmi(weight_kg, height_cm):
    height_m = height_cm / 100
    value = weight_kg / (height_m ** 2)
    if value < 18.5:
        label = "Under"
    elif value < 25:
        label = "Normal"
    else:
        label = "Over"
    return round(value, 1), label

demo = gr.Interface(
    fn=bmi,
    inputs=[gr.Number(label="Weight (kg)"), gr.Number(label="Height (cm)")],
    outputs=[gr.Number(label="BMI"), gr.Textbox(label="Category")],
    title="BMI calculator",
)
demo.launch()
  1. fn is the function.
  2. inputs is one component or a list. A list means "one value per parameter, in order".
  3. outputs works the same way for return values. Returning a tuple fills several output components in order.

The page shows two number boxes, a Submit button, and two output components. Entering 70 and 175 shows 22.9 and Normal.

If you give a single component, you can leave out the list brackets. A function that returns one value pairs with one output component. A function that returns a tuple must pair with a list of components of the same length, or Gradio reports a mismatch.

The most useful arguments

Argument Purpose
title, description, article Heading, intro text and longer text below the app (Markdown supported)
examples Clickable sample inputs (see examples and flagging)
submit_btn, clear_btn, stop_btn Rename or replace buttons
live Run the function on every change, with no Submit button
flagging_mode "never", "auto" or "manual" (collect user reports)
api_name Name of the API endpoint (default /predict)
batch, max_batch_size Process several requests in one call for models that benefit
cache_examples Pre-compute example outputs
concurrency_limit How many runs may go at once

Exact argument names move between major versions (for example, flagging options and button arguments have been renamed in the past), so check the docs of your installed version when something is rejected with a "no such argument" error.

Live mode

Python
demo = gr.Interface(fn=bmi, inputs=[...], outputs=[...], live=True)

With live=True the page has no Submit button. Each time an input changes, the function runs. Use it only for quick functions, because a slow function runs for every keystroke or slider step. Live mode feels great for a unit converter and terrible for a 10-second model.

Function arguments with defaults and types

Gradio does not read your type hints (it uses the components), but defaults matter: if the user leaves a component empty, you get the component's empty value (None for a number, "" for a textbox), not your default. Write code that handles empties:

Python
def safe_bmi(weight_kg, height_cm):
    if not weight_kg or not height_cm:
        raise gr.Error("Please enter both weight and height.")
    ...

gr.Error shows a red message in the UI with exactly your text, without a traceback. Use gr.Warning and gr.Info for non-blocking pop-ups. Validating inputs and raising clear messages is the best usability upgrade you can make to a demo.

Choosing Interface or Blocks

flowchart TD
    Q["How many functions<br/>does the page need?"] -->|"One function,<br/>standard layout"| I["gr.Interface"]
    Q -->|"Several functions<br/>or custom layout"| B["gr.Blocks"]
    I -->|"Need more later"| B

Interface is a ready-made Blocks app; moving up is straightforward.

Choose Interface for one function with a form-and-result layout. Choose Blocks for several functions, custom layouts, outputs that feed other inputs, or chatbots with side panels. Two helpers connect them: gr.TabbedInterface([a, b], ["A", "B"]) puts several Interfaces in tabs, and an Interface can be placed inside a Blocks with demo.render().

Stand-in 1: matching components to parameters

This stand-in (our own code) checks the same rules Gradio applies: counts must agree, and tuples spread across outputs.

Python Stand-in: inputs and outputs by position

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 second call fails because the function returns two values but only one output component exists, which is the most common mistake with multiple outputs.

Stand-in 2: handling empty values

Python Stand-in: friendly validation

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.

In real Gradio, raise gr.Error("...") gives the same result: your text appears in a red banner and no traceback is shown to the user.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A function returns two values. What must outputs be?

    Returning a tuple fills output components in order, so the list length must match.
  2. 2. What does live=True do?

    Live mode reacts to changes, which suits only fast functions.
  3. 3. How do you show a clean error message to the user?

    gr.Error displays your text in a banner without a traceback.
  4. 4. When is Blocks the better choice?

    Blocks gives control over layout and events; Interface is the quick one-function shortcut.

Summary

  • Interface(fn, inputs, outputs) builds a complete app; components map by position.
  • Tuples returned from the function fill several outputs.
  • title, description, article, examples, live and flagging_mode shape the page.
  • Handle empty values and raise gr.Error for friendly messages.
  • Move to Blocks for several functions or custom layouts.

Next: Text and Number Inputs