Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 37 ยท Custom Components

Themes, CSS and JavaScript

Restyle a Gradio app with built-in themes, theme.set variables, elem_id and elem_classes, custom CSS and head scripts, plus a runnable contrast checker and CSS generator.

Gradio's default look is clean but generic. You can change it at three levels: pick a ready-made theme, override individual theme variables, or write your own CSS and JavaScript. Start at the top of this list and only go further when you need to, because each level costs more maintenance.

The real Gradio is not available on this site, so its code is read-only. The runnable blocks do the color math and CSS generation in plain Python, labelled stand-ins, so you can see what a theme actually produces.

Built-in themes

Python
import gradio as gr

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

The page shows rounded corners, softer borders and a blue accent. Other ready-made themes include gr.themes.Default(), Base() (a plain starting point), Monochrome(), Glass() and Ocean(). Each theme can also be parameterized:

Python
theme = gr.themes.Soft(
    primary_hue="emerald",      # main accent: buttons, sliders
    secondary_hue="amber",
    neutral_hue="slate",        # grays: backgrounds, borders
    font=[gr.themes.GoogleFont("Inter"), "system-ui", "sans-serif"],
    radius_size="lg",
    text_size="md",
    spacing_size="md",
)

Hues are names of color ramps (blue, emerald, rose, slate...), each with 11 shades from 50 (very light) to 950 (nearly black). Browse them with the official theme gallery, which also lets you try and copy themes made by the community.

In recent releases, theme= and css= may be passed to launch() as well as to gr.Blocks(...); check the documentation for your installed version to see where it expects them.

Dark mode

Gradio follows the visitor's system light or dark setting. Visitors can force it with ?__theme=dark on the URL. Theme variables have separate dark twins (names ending in _dark), so a custom theme should set both or it will look odd in dark mode.

Overriding variables with .set()

Every visual detail is a theme variable, such as button_primary_background_fill or block_title_text_color. Override just the ones you care about:

Python
theme = gr.themes.Base(primary_hue="indigo").set(
    button_primary_background_fill="*primary_600",
    button_primary_background_fill_hover="*primary_700",
    body_background_fill="#f8fafc",
    block_radius="12px",
    button_large_radius="999px",
)

A value starting with * refers to another variable in the theme, so *primary_600 means "shade 600 of the primary hue". Behind the scenes Gradio turns the theme into CSS variables such as --button-primary-background-fill and injects them into the page.

Accessible colors

A beautiful theme with unreadable text is a bad theme. The WCAG guideline asks for a contrast ratio of at least 4.5 to 1 between normal text and its background. The block below computes the ratio so you can test your button colors before you ship them.

Python Contrast ratio checker

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.

White on indigo passes, but white on amber fails (it is too light), while black on amber passes comfortably. A theme can set the text color of primary buttons separately with button_primary_text_color for this reason.

elem_id, elem_classes and custom CSS

To restyle one component, give it a handle and target it from CSS:

Python
css = """
#title { text-align: center; }
.big-button { font-size: 1.4rem; padding: 1rem; }
footer { display: none !important; }      /* hide the Gradio footer */
"""

with gr.Blocks(css=css) as demo:
    gr.Markdown("# My demo", elem_id="title")
    btn = gr.Button("Run", elem_classes=["big-button"])

After launching, the heading is centered and the button is larger. Use elem_id for one-off elements and elem_classes for groups. Gradio's internal class names change between versions, so rely on your own ids and classes and on theme variables, not on selectors like .svelte-abc123, which are unstable. Using !important is sometimes needed to beat built-in styles.

You can also load CSS from a file: css_paths=["style.css"].

Generating CSS from a theme dictionary

Themes are just data turned into CSS custom properties. This stand-in generates the CSS a small theme would produce, which is a good way to understand the variable names.

Python Theme dictionary 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 output is a :root block with four custom properties, with underscores turned into hyphens. This is how Gradio's own CSS sees your theme; its components read var(--button-primary-background-fill) and so on.

JavaScript and head scripts

Two hooks run your own JavaScript:

Python
js = """
function() {
  document.title = "My Gradio demo";
}
"""

with gr.Blocks(js=js, head='<script async src="https://example.com/analytics.js"></script>') as demo:
    ...
  • js= runs a function once when the page loads.
  • head= inserts raw HTML into the page head (analytics tags, fonts, meta tags).
  • Per event, btn.click(fn, inputs, outputs, js="(x) => x + '!'") runs a JavaScript function in the browser before or instead of Python, useful for instant client-side tweaks with no server round trip.

Only add scripts you trust and understand; they run in your visitors' browsers.

Beyond styling: gr.HTML

gr.HTML("<div class='card'>...</div>") puts any markup in a layout. Combine it with css= for custom cards, badges or dashboards. If you need the markup to be interactive (its own value and events), that is the point where a custom component makes sense.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does a theme value like "*primary_600" mean?

    A leading * refers to another theme variable.
  2. 2. What is the minimum WCAG AA contrast ratio for normal text?

    AA asks for 4.5:1 for normal-size text.
  3. 3. How do you target one component from custom CSS?

    elem_id and elem_classes add stable handles that you can select in CSS.
  4. 4. Why avoid selectors like .svelte-abc123?

    Generated class names are unstable; rely on your own ids and theme variables.

Summary

  • Start with a built-in theme, adjust hues and sizes, then override single variables with .set().
  • Check contrast; set dark-mode variants too.
  • Use elem_id, elem_classes and css= for local styling; js= and head= for scripts.
  • Move to a custom component only when you need a new interactive widget.

Next: Testing Gradio Apps