Gradio

Patterns and quirks specific to running Gradio inside a Space. Assumes you're already comfortable with stock Gradio components and gr.Blocks / gr.Interface.

For deeper Gradio API guidance — components, layouts, event listeners, chatbots, the Gradio 5→6 migration — use the dedicated huggingface-gradio skill. Install it with hf skills add huggingface-gradio (add --claude --global to also install for Claude Code, user-level).

For ZeroGPU-specific decorator + worker semantics, see zerogpu.md.

Themes and layout

• Default theme preference: gr.themes.Citrus(). Alternatives: gr.themes.Soft() or no theme. Pick once and don't over-style.
• For apps that don't need full-width, constrain with CSS so they're readable on 4K displays:

  CSS = """
  #col-container { max-width: 1100px; margin: 0 auto; }
  .dark .gradio-container { color: var(--body-text-color); }
  """
  with gr.Blocks(theme=gr.themes.Citrus(), css=CSS) as demo: ...

Always include the .dark .gradio-container override with gr.themes.Citrus() — without it Citrus's dark mode renders dark text on a dark background (text inherits unset colors). The same fix is harmless (and worth keeping) under other themes.

• Width-cap with !important if Gradio 6's own breakpoints fight you — target main, .gradio-container, and the inner fillable wrapper, otherwise the width caps but goes flush-left.

Minimal layout most demos converge to

with gr.Row():
    prompt = gr.Textbox(show_label=False, placeholder="…", container=False, scale=4)
    run = gr.Button("Run", variant="primary", scale=1)
output = gr.Image(...)
with gr.Accordion("Advanced settings", open=False):
    ...

container=False on the inline Textbox removes the default outer border for a tighter look.

gr.Markdown for the intro

Be succinct. Title, one-line description, a links section. Don't over-explain how it works — that's what the model card is for.

gr.Examples

Add gr.Examples whenever it makes sense (the app takes user input and representative inputs exist). It's the first thing a visitor clicks and it doubles as an instant smoke test. Prefer examples that mirror the official examples from the original repo / model card — the prompts, images, and settings the authors showcase — over inventing your own.

Keep each example row to the few variables a user actually changes (the prompt, the input image). Give the handler default values for everything else (steps, guidance, seed, …) so an example row is ["a cat on a windowsill"], not a wall of knobs. Design the signature so the interesting inputs come first and the rest default:

@spaces.GPU(duration=60)
def generate(prompt, seed=42, steps=28, guidance=5.0):   # only `prompt` varies in examples
    ...

gr.Examples(
    examples=[
        ["a cat sitting on a windowsill"],
        ["mountains at sunset, photorealistic"],
    ],
    inputs=[prompt],          # just the varied inputs; the rest use the handler defaults
    outputs=output,
    fn=generate,
    cache_examples=True,
    cache_mode="lazy",
)

Why these flags:

• cache_examples=True makes example clicks instant (no re-inference per visitor).
• cache_mode="lazy" — caches on first user click for each example. Required on ZeroGPU (Gradio's default on ZeroGPU is already lazy via GRADIO_CACHE_MODE=lazy). Eager would pre-run every example at app startup, but ZeroGPU has no GPU attached at startup — it'd fail and burn the creator's daily quota.
• cache_examples=True silently disables run_on_click / run_examples_on_click. If your app relies on click-only behavior, set cache_examples=False.

The cache key is the example row's file path, not a content hash. Regenerating an asset in place serves the stale cached output forever. If you replace example files, bump a cache_version marker or wipe .gradio/cached_examples/ /.