Gradio Theme

Gradio Theme provides essential CSS and JavaScript utilities for theming Gradio UI components. It offers a comprehensive color system with predefined palettes, CSS reset styles, global styling rules, typography definitions, and theme tokens for building consistent Gradio web interfaces.

Package Information

• Package Name: @gradio/theme
• Package Type: npm
• Language: TypeScript/JavaScript with CSS
• Installation: npm install @gradio/theme

Core Imports

JavaScript/TypeScript color utilities:

import { colors, ordered_colors, color_values } from "@gradio/theme";

CSS imports for styling:

@import "@gradio/theme/reset.css";
@import "@gradio/theme/global.css";
@import "@gradio/theme/typography.css";
@import "@gradio/theme/pollen.css";

Individual token imports:

import "@gradio/theme/tokens";

Basic Usage

import { colors, ordered_colors } from "@gradio/theme";
import "@gradio/theme/reset.css";
import "@gradio/theme/global.css";

// Use predefined theme colors
const primaryBlue = colors.blue.primary; // "#2563eb"
const secondaryBlue = colors.blue.secondary; // "#dbeafe"

// Iterate through available colors
ordered_colors.forEach(colorName => {
  console.log(`${colorName}: ${colors[colorName].primary}`);
});

// Access color configuration
console.log(color_values); // Array of color configurations

Architecture

Gradio Theme is built around several key components:

• Color System: TypeScript exports providing programmatic access to theme colors
• CSS Reset: Normalization and base styles for consistent rendering
• Global Styles: Utility classes and component-specific styling
• Typography: Text styling with CSS custom properties
• Design Tokens: Responsive breakpoints and media queries
• Pollen Integration: Generated CSS from Pollen configuration with custom design tokens

Capabilities

Color System

Provides programmatic access to a consistent color palette with primary and secondary variants for each theme color.

/**
 * Ordered array of available theme color names
 */
const ordered_colors: readonly [
  "red", "green", "blue", "yellow", "purple", 
  "teal", "orange", "cyan", "lime", "pink"
];

/**
 * Color configuration array with primary/secondary tone mappings
 */
const color_values: readonly {
  color: string;
  primary: number;
  secondary: number;
}[];

/**
 * Main color palette object with computed hex values
 */
const colors: Colors;

interface ColorPair {
  primary: string;
  secondary: string;
}

interface Colors {
  red: ColorPair;
  green: ColorPair;
  blue: ColorPair;
  yellow: ColorPair;
  purple: ColorPair;
  teal: ColorPair;
  orange: ColorPair;
  cyan: ColorPair;
  lime: ColorPair;
  pink: ColorPair;
}

Usage Examples:

import { colors, ordered_colors, color_values } from "@gradio/theme";

// Get specific color values
const redPrimary = colors.red.primary;     // "#dc2626"
const redSecondary = colors.red.secondary; // "#fee2e2"

// Iterate through all colors
ordered_colors.forEach(colorName => {
  const colorPair = colors[colorName];
  console.log(`${colorName}: ${colorPair.primary}, ${colorPair.secondary}`);
});

// Access configuration metadata
const blueConfig = color_values.find(c => c.color === "blue");
// { color: "blue", primary: 600, secondary: 100 }

CSS Reset Styles

Provides CSS reset and normalization styles for consistent cross-browser rendering.

Import:

@import "@gradio/theme/reset.css";

Key Features:

• Box-sizing reset for .gradio-container and all elements (box-sizing: border-box)
• HTML base styles with IBM Plex Sans font family
• Heading (h1-h6) and link normalization
• Form element and input styling reset
• Consistent line-height and font rendering

Global Utility Styles

Provides global utility classes and component-specific styles for Gradio applications.

Import:

@import "@gradio/theme/global.css";

Key Utility Classes:

• .scroll-hide - Hides scrollbars across browsers
• .sr-only - Screen reader only content (visually hidden)
• .gradio-container - Base container styling
• .cropper-container - Image cropper component styling

Custom Element Support:

• gradio-lite element styling with FOUC prevention
• Display flex layout for gradio-lite elements

Typography Styles

Provides comprehensive typography styling with CSS custom properties for flexible theming.

Import:

@import "@gradio/theme/typography.css";

Key Classes:

• .prose - Main typography class for content areas
• Hierarchical heading styles (h1-h5) with consistent spacing
• Paragraph, list, and text formatting
• Uses CSS custom properties for flexible theming:
  • --prose-text-weight
  • --prose-header-text-weight
  • --body-text-color
  • --text-* size variables
  • --spacing-* variables

Design Tokens

Provides responsive breakpoint definitions as CSS custom media queries.

Import:

import "@gradio/theme/tokens";

Available Breakpoints:

@custom-media --screen-sm (min-width: 640px);
@custom-media --screen-md (min-width: 768px);
@custom-media --screen-lg (min-width: 1024px);
@custom-media --screen-xl (min-width: 1280px);
@custom-media --screen-xxl (min-width: 1536px);
@custom-media --screen-xxxl (min-width: 1920px);

Pollen CSS Integration

Provides generated CSS from Pollen configuration with custom design tokens including colors, typography, spacing, and border radius values.

Import:

@import "@gradio/theme/pollen.css";

Generated from Pollen configuration including:

• Custom line heights (sm: 1.4)
• IBM Plex Sans and IBM Plex Mono font stacks
• Border radius scale (xs: 2px to 3xl: 22px)
• Comprehensive spacing and sizing system
• Extended color palette with tonal variations (10, 50-950 scale)
• Blue, grey, red, green, orange, yellow color systems

Key Design Tokens Available:

• Font families: --font-sans, --font-mono
• Border radius: --radius-xs through --radius-3xl
• Spacing: --size-* variables including fractional sizes
• Colors: Extensive color palette with numbered variants

Configuration

Pollen Configuration

The package includes a Pollen CSS configuration file that generates the design system CSS. This configuration extends the default Pollen modules with Gradio-specific customizations:

Key Configuration Areas:

• Line Heights: Custom line height scale
• Typography: IBM Plex font families
• Border Radius: Consistent radius scale
• Spacing: Extended sizing system
• Colors: Comprehensive color palette with brand-specific values

The configuration outputs to src/pollen.css and provides CSS custom properties for all design tokens.