Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 37 ยท Blocks and Layouts

Themes and Custom CSS

Style a Gradio app: built-in themes, theme builder variables, light and dark mode, custom CSS with elem_id and elem_classes, and custom JavaScript. Includes a version note.

A Gradio app looks decent out of the box, but branding, readability and accessibility often need adjustments: a company colour, larger text, a different font, a hidden footer. Gradio offers three levels of styling, from one argument to full CSS. This lesson goes from easy to powerful, and ends with a version caveat that matters: where you pass theme, css and js has changed between major versions. The Gradio code is read-only; stand-ins generate and inspect CSS so you can test the ideas.

Level 1: built-in themes

Python
import gradio as gr

with gr.Blocks(theme=gr.themes.Soft()) as demo:
    gr.Markdown("# Styled")
    gr.Button("Go", variant="primary")

The page switches to rounded corners, softer colours and an indigo primary button. Built-in themes include Default, Soft, Monochrome, Glass, Base, Citrus and Ocean. Other themes can be loaded by name from the Hugging Face Hub (for example theme="gstaff/xkcd"), which downloads a small configuration file on first use.

Version note: in Gradio 5 you pass theme=, css= and js= to gr.Blocks(...) (or gr.Interface(...)). Newer major versions move these to launch(): demo.launch(theme=..., css=...). If you see a deprecation warning or an unexpected keyword error, check your version with gradio.__version__ and read the release notes. The examples in this lesson use the Blocks form; adapt as needed.

Level 2: customize a theme

Start from a base theme and change colours, fonts and sizes with .set() and the constructor arguments:

Python
theme = gr.themes.Soft(
    primary_hue="emerald",        # buttons and accents
    secondary_hue="teal",
    neutral_hue="slate",          # backgrounds and borders
    font=[gr.themes.GoogleFont("Inter"), "ui-sans-serif", "sans-serif"],
    radius_size="lg",
    text_size="md",
).set(
    button_primary_background_fill="*primary_600",
    button_primary_background_fill_hover="*primary_700",
    body_background_fill_dark="*neutral_950",
)

Hues are named colour scales with shades 50 to 950. Variables such as button_primary_background_fill refer to those shades with the *primary_600 syntax. Variables ending in _dark apply in dark mode, so one theme defines both. There are hundreds of variables; you can browse them with gr.themes.builder(), an interactive theme builder that opens in a browser and exports Python code.

Dark mode: Gradio follows the operating system by default. A URL with ?__theme=dark forces dark mode, and ?__theme=light forces light. Test both, especially custom colours: a bright blue on white may fail contrast on black.

Level 3: custom CSS

Pass a CSS string. Targeting components needs hooks:

Python
css = """
#title h1 { text-align: center; color: #0f766e; }
.big-input textarea { font-size: 1.25rem; }
footer { display: none !important; }
"""

with gr.Blocks(css=css) as demo:
    gr.Markdown("# Notes", elem_id="title")
    gr.Textbox(label="Note", lines=4, elem_classes=["big-input"])
  • elem_id="title" gives an element a unique HTML id (target it with #title).
  • elem_classes=["big-input"] adds class names (target with .big-input).
  • Use the browser's developer tools to find the inner element (textarea, input, label) because components wrap several elements.
  • Gradio's own CSS has high specificity. If your rule does not apply, make the selector more specific or add !important.
  • You can load a file instead: css_paths="styles.css" in versions that support it, or read the file into the string yourself.

Hiding the footer removes the "Use via API" links. Do it only if you do not want people to find the API; it is not a security measure because the API still exists.

Level 4: custom JavaScript and head

Python
js = "() => { document.title = 'My Notes'; }"
with gr.Blocks(js=js) as demo: ...

js runs once on page load, which is handy for small tweaks such as the title or a keyboard shortcut. head= injects HTML into the page head (analytics, fonts). Avoid heavy scripting: it runs in your users' browsers and ties your app to Gradio's internal structure, which changes between versions.

Accessibility reminders

  • Keep text contrast at least 4.5:1 in both themes.
  • Do not rely on colour alone; keep labels on components.
  • Leave label on every input (screen readers read it); hide it visually with show_label=False only when a nearby heading does the job.
  • Test at 200% zoom and on a phone-width window.

Stand-in 1: from a theme to CSS variables

A Gradio theme is ultimately a set of CSS variables. This stand-in turns a small dictionary into the CSS block a theme produces, including a dark variant.

Python Stand-in: theme tokens to CSS variables

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 _dark suffix maps to a second block that applies under the dark class, which is the same idea as the body_background_fill_dark setting above.

Stand-in 2: contrast checker

Accessibility is easy to test with arithmetic. This stand-in computes the WCAG contrast ratio of two colours so you can check a theme before shipping.

Python Stand-in: WCAG contrast ratio

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 darker green passes and the light grey fails, which is the kind of mistake that a theme tweak can introduce without anyone noticing.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does elem_id do?

    elem_id becomes the element's id attribute, so #name works in CSS. elem_classes adds class names.
  2. 2. How do you start from the Soft theme and change the primary colour to emerald?

    Theme constructors take hue arguments; .set() adjusts individual variables.
  3. 3. Why test dark mode?

    Gradio follows the OS setting, so both themes must work.
  4. 4. Where do theme and css arguments go in newer major versions?

    Check your installed version: Gradio 5 uses Blocks arguments, newer versions use launch() arguments.

Summary

  • Use a built-in theme first, then customize hues, fonts and variables with .set().
  • Use elem_id and elem_classes with custom CSS; inspect the DOM for inner elements.
  • js and head allow small scripts but tie you to internals.
  • Test light and dark mode and check contrast.
  • The place to pass theme, css and js depends on the major version.

Next: Dynamic UI: Visibility, Updates and render