> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/gradio-app/gradio/llms.txt
> Use this file to discover all available pages before exploring further.

# Working with examples

> Learn how to provide example inputs for your Gradio demos to help users understand your models

Providing examples makes it easier for users to try your demo and understand the types of inputs your model expects. Examples appear below the UI components and can be clicked to populate the interface.

## Basic usage

Add examples to an Interface by providing a list of lists to the `examples` keyword argument:

```python theme={null}
import gradio as gr

def calculator(num1, operation, num2):
    if operation == "add":
        return num1 + num2
    elif operation == "subtract":
        return num1 - num2
    elif operation == "multiply":
        return num1 * num2
    elif operation == "divide":
        if num2 == 0:
            raise gr.Error("Cannot divide by zero!")
        return num1 / num2

demo = gr.Interface(
    calculator,
    [
        "number",
        gr.Radio(["add", "subtract", "multiply", "divide"]),
        "number"
    ],
    "number",
    examples=[
        [45, "add", 3],
        [3.14, "divide", 2],
        [144, "multiply", 2.5],
        [0, "subtract", 1.2],
    ],
    title="Toy Calculator",
    description="Here's a sample toy calculator."
)

demo.launch()
```

## Example format

Each sublist within the outer list represents a data sample, and each element within the sublist represents an input for each input component:

* The inputs must be ordered in the same order as the prediction function expects them
* Each element corresponds to one input component
* If your interface only has one input component, you can provide examples as a regular list instead of a list of lists

<CodeGroup>
  ```python Single input theme={null}
  # For a single input, you can use a simple list
  examples=["Hello", "Good morning", "Hi there"]
  ```

  ```python Multiple inputs theme={null}
  # For multiple inputs, use nested lists
  examples=[
      ["John", 25, True],
      ["Jane", 30, False],
      ["Bob", 35, True],
  ]
  ```
</CodeGroup>

## Loading from a directory

You can specify a path to a directory containing your examples:

<Steps>
  <Step title="Single file-type input">
    If your Interface takes only a single file-type input (e.g., an image classifier), simply pass a directory filepath:

    ```python theme={null}
    gr.Interface(
        fn=image_classifier,
        inputs="image",
        outputs="label",
        examples="/path/to/images/"
    )
    ```

    The Interface will load all images in the directory as examples.
  </Step>

  <Step title="Multiple inputs with log.csv">
    For multiple inputs, the directory must contain a `log.csv` file with example values:

    ```csv theme={null}
    num,operation,num2
    5,"add",3
    4,"divide",2
    5,"multiply",3
    ```

    Then reference the directory:

    ```python theme={null}
    gr.Interface(
        fn=calculator,
        inputs=[...],
        outputs=[...],
        examples="/demo/calculator/examples"
    )
    ```
  </Step>

  <Step title="Loading flagged data">
    This approach is helpful when browsing flagged data. Simply point to the flagged directory:

    ```python theme={null}
    examples="./flagged"
    ```
  </Step>
</Steps>

## Partial examples

Sometimes your app has many input components, but you only want to provide examples for a subset of them. Pass `None` for data samples corresponding to components you want to exclude:

```python theme={null}
import gradio as gr

def generate_image(prompt, negative_prompt, seed, steps):
    # Generation logic here
    pass

demo = gr.Interface(
    generate_image,
    inputs=[
        gr.Textbox(label="Prompt"),
        gr.Textbox(label="Negative Prompt"),
        gr.Number(label="Seed"),
        gr.Slider(1, 100, label="Steps")
    ],
    outputs="image",
    examples=[
        ["A sunset over mountains", None, None, None],
        ["A cat in space", "blurry, low quality", 42, None],
        ["Abstract art", None, 123, 50],
    ]
)

demo.launch()
```

## Pagination

Examples are automatically paginated when you have many of them. Control the number per page:

```python theme={null}
gr.Interface(
    fn=model,
    inputs=[...],
    outputs=[...],
    examples=large_dataset,
    examples_per_page=10  # Default is 10
)
```

This is useful for browsing and interacting with large datasets through Gradio.

## Caching examples

You may want to cache example outputs so users can quickly try them without waiting for your model to run.

<Accordion title="cache_examples=True">
  When set to `True`, your Gradio app runs all examples and saves outputs when you call `launch()`:

  ```python theme={null}
  demo = gr.Interface(
      fn=slow_model,
      inputs=[...],
      outputs=[...],
      examples=[[...]],
      cache_examples=True
  )

  demo.launch()  # Examples are cached during launch
  ```

  <Note>
    The cache is saved in a `gradio_cached_examples` directory by default. Set the `GRADIO_EXAMPLES_CACHE` environment variable to use a custom directory path.
  </Note>
</Accordion>

<Accordion title="Lazy caching">
  With lazy caching, each example is cached only after first use by any user:

  ```python theme={null}
  demo = gr.Interface(
      fn=slow_model,
      inputs=[...],
      outputs=[...],
      examples=[[...]],
      cache_examples="lazy"
  )

  demo.launch()  # App starts immediately
  ```

  This is helpful if your prediction function is long-running and you don't want to wait during app startup.
</Accordion>

<Accordion title="Cache mode configuration">
  Control when caching happens with `cache_mode`:

  ```python theme={null}
  demo = gr.Interface(
      fn=model,
      inputs=[...],
      outputs=[...],
      examples=[[...]],
      cache_examples=True,
      cache_mode="eager"  # or "lazy"
  )
  ```

  * `"eager"` - All examples cached at app launch (default)
  * `"lazy"` - Examples cached after first use

  On HuggingFace Spaces, eager mode is default except for ZeroGPU Spaces which use lazy mode.
</Accordion>

<Warning>
  Once the cache is generated, it won't update automatically in future launches. If examples or function logic change, delete the cache folder to rebuild it.

  Cached examples don't support certain features like `gr.Progress()`, `gr.Info()`, or `gr.Warning()` in the UI.
</Warning>

## Example labels

Instead of rendering example values, you can provide custom labels:

```python theme={null}
gr.Interface(
    fn=model,
    inputs="image",
    outputs="label",
    examples=[
        ["image1.jpg"],
        ["image2.jpg"],
        ["image3.jpg"],
    ],
    example_labels=[
        "Mountain landscape",
        "City skyline",
        "Ocean sunset"
    ]
)
```

The length of `example_labels` should match the number of examples.

## Preloading examples

You can preload a specific example when the app first loads:

```python theme={null}
gr.Interface(
    fn=model,
    inputs=[...],
    outputs=[...],
    examples=[[...]],
    cache_examples=True,
    preload_example=0  # Preload the first example (0-indexed)
)
```

<Note>
  Preloading only works when:

  * Examples are cached eagerly (`cache_examples=True` and `cache_mode="eager"`)
  * None of the input components have a developer-provided `value`
</Note>

Set to `False` to disable preloading:

```python theme={null}
preload_example=False
```

## Examples with state

<Warning>
  Cache examples cannot be used with state inputs and outputs. Gradio automatically sets `cache_examples=False` when state components are detected.
</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="Interface class" icon="cube" href="/guides/interface-class">
    Learn more about the Interface class
  </Card>

  <Card title="Flagging" icon="flag" href="/guides/flagging">
    Allow users to flag interesting outputs
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.