0
# Theme System
1
2
Comprehensive theming system with predefined themes and utilities for customizing visual appearance, branding, and user interface styling across all Gradio components.
3
4
## Capabilities
5
6
### Theme Classes
7
8
Built-in theme classes providing complete visual styling with customizable colors, fonts, spacing, and component appearance.
9
10
```python { .api }
11
class Base:
12
def __init__(
13
self,
14
primary_hue="blue",
15
secondary_hue="gray",
16
neutral_hue="gray",
17
spacing_size="lg",
18
radius_size="lg",
19
text_size="lg",
20
font=None,
21
font_mono=None,
22
**kwargs
23
):
24
"""
25
Base theme class with full customization options.
26
27
Parameters:
28
- primary_hue: Primary color hue (string color name or Color object)
29
- secondary_hue: Secondary color hue
30
- neutral_hue: Neutral color hue for backgrounds
31
- spacing_size: Spacing scale ("sm", "md", "lg", "xl")
32
- radius_size: Border radius scale ("sm", "md", "lg", "xl")
33
- text_size: Text size scale ("sm", "md", "lg", "xl")
34
- font: Primary font (Font object or font stack)
35
- font_mono: Monospace font for code
36
"""
37
38
def set(self, **kwargs):
39
"""Update theme properties."""
40
41
def push_to_hub(self, repo_id, **kwargs):
42
"""Upload theme to Hugging Face Hub."""
43
44
# Alias for Base theme
45
Theme = Base
46
47
class Default(Base):
48
def __init__(self, **kwargs):
49
"""Default Gradio theme with standard styling."""
50
51
class Glass(Base):
52
def __init__(self, **kwargs):
53
"""Glass effect transparency theme with blur effects."""
54
55
class Monochrome(Base):
56
def __init__(self, **kwargs):
57
"""Black and white minimalist theme."""
58
59
class Soft(Base):
60
def __init__(self, **kwargs):
61
"""Soft color palette theme with muted tones."""
62
63
class Origin(Base):
64
def __init__(self, **kwargs):
65
"""Original Gradio branding theme."""
66
67
class Citrus(Base):
68
def __init__(self, **kwargs):
69
"""Citrus-inspired color theme with orange/yellow tones."""
70
71
class Ocean(Base):
72
def __init__(self, **kwargs):
73
"""Ocean blue color theme with aquatic tones."""
74
```
75
76
Usage examples:
77
78
```python
79
import gradio as gr
80
81
# Use predefined theme
82
demo = gr.Interface(
83
fn=my_function,
84
inputs="text",
85
outputs="text",
86
theme=gr.themes.Soft()
87
)
88
89
# Customize existing theme
90
custom_theme = gr.themes.Default(
91
primary_hue="green",
92
secondary_hue="blue",
93
text_size="lg"
94
)
95
96
demo = gr.Blocks(theme=custom_theme)
97
```
98
99
### Color System
100
101
Color definition and manipulation utilities for creating custom color schemes and palettes.
102
103
```python { .api }
104
class Color:
105
def __init__(
106
self,
107
c50="#fafafa",
108
c100="#f4f4f5",
109
c200="#e4e4e7",
110
c300="#d4d4d8",
111
c400="#a1a1aa",
112
c500="#71717a",
113
c600="#52525b",
114
c700="#3f3f46",
115
c800="#27272a",
116
c900="#18181b",
117
c950="#09090b",
118
name=None,
119
**kwargs
120
):
121
"""
122
Color definition with full shade palette.
123
124
Parameters:
125
- c50-c950: Color shades from lightest to darkest
126
- name: Optional color name identifier
127
"""
128
129
@classmethod
130
def from_hex(cls, hex_color):
131
"""Create Color from single hex value, generating shade palette."""
132
133
@classmethod
134
def from_name(cls, color_name):
135
"""Create Color from standard color name."""
136
137
def to_dict(self):
138
"""Convert color to dictionary format."""
139
140
# Predefined color constants
141
colors = {
142
"red": Color(...),
143
"orange": Color(...),
144
"amber": Color(...),
145
"yellow": Color(...),
146
"lime": Color(...),
147
"green": Color(...),
148
"emerald": Color(...),
149
"teal": Color(...),
150
"cyan": Color(...),
151
"sky": Color(...),
152
"blue": Color(...),
153
"indigo": Color(...),
154
"violet": Color(...),
155
"purple": Color(...),
156
"fuchsia": Color(...),
157
"pink": Color(...),
158
"rose": Color(...),
159
"slate": Color(...),
160
"gray": Color(...),
161
"zinc": Color(...),
162
"neutral": Color(...),
163
"stone": Color(...),
164
}
165
```
166
167
Usage examples:
168
169
```python
170
import gradio as gr
171
172
# Use predefined colors
173
theme = gr.themes.Base(
174
primary_hue=gr.themes.colors.green,
175
secondary_hue=gr.themes.colors.blue
176
)
177
178
# Create custom color
179
custom_color = gr.themes.Color.from_hex("#ff6b6b")
180
theme = gr.themes.Base(primary_hue=custom_color)
181
182
# Define full color palette
183
brand_color = gr.themes.Color(
184
c50="#fff1f2",
185
c100="#ffe4e6",
186
c500="#ef4444",
187
c900="#7f1d1d",
188
name="brand"
189
)
190
```
191
192
### Font System
193
194
Font configuration and loading utilities for typography customization with support for web fonts and font stacks.
195
196
```python { .api }
197
class Font:
198
def __init__(
199
self,
200
name,
201
weights=None,
202
**kwargs
203
):
204
"""
205
Font configuration for theme typography.
206
207
Parameters:
208
- name: Font name or font stack
209
- weights: List of font weights to load
210
"""
211
212
def to_css(self):
213
"""Generate CSS font-family declaration."""
214
215
class GoogleFont(Font):
216
def __init__(
217
self,
218
name,
219
weights=None,
220
**kwargs
221
):
222
"""
223
Google Fonts integration for web font loading.
224
225
Parameters:
226
- name: Google Font name
227
- weights: List of weights to load (e.g., [400, 700])
228
"""
229
230
def load_css(self):
231
"""Generate Google Fonts CSS import URL."""
232
233
# Font utilities and presets
234
def font_families():
235
"""Get available system font families."""
236
237
def web_safe_fonts():
238
"""Get web-safe font stack options."""
239
```
240
241
Usage examples:
242
243
```python
244
import gradio as gr
245
246
# Use Google Fonts
247
heading_font = gr.themes.GoogleFont("Roboto", weights=[400, 700])
248
mono_font = gr.themes.GoogleFont("Roboto Mono")
249
250
theme = gr.themes.Base(
251
font=heading_font,
252
font_mono=mono_font
253
)
254
255
# Use system fonts
256
system_font = gr.themes.Font(
257
"system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif"
258
)
259
260
theme = gr.themes.Base(font=system_font)
261
```
262
263
### Size System
264
265
Size definition utilities for consistent spacing, text scaling, and component dimensions across the interface.
266
267
```python { .api }
268
class Size:
269
def __init__(
270
self,
271
xxs=None,
272
xs=None,
273
sm=None,
274
md=None,
275
lg=None,
276
xl=None,
277
xxl=None,
278
**kwargs
279
):
280
"""
281
Size scale definition for spacing and dimensions.
282
283
Parameters:
284
- xxs through xxl: Size values for each scale step
285
"""
286
287
def to_dict(self):
288
"""Convert size scale to dictionary."""
289
290
# Predefined size constants
291
sizes = {
292
"text_xxs": "9px",
293
"text_xs": "10px",
294
"text_sm": "12px",
295
"text_md": "14px",
296
"text_lg": "16px",
297
"text_xl": "20px",
298
"text_xxl": "24px",
299
300
"spacing_xxs": "1px",
301
"spacing_xs": "2px",
302
"spacing_sm": "4px",
303
"spacing_md": "6px",
304
"spacing_lg": "8px",
305
"spacing_xl": "10px",
306
"spacing_xxl": "16px",
307
308
"radius_xxs": "1px",
309
"radius_xs": "2px",
310
"radius_sm": "4px",
311
"radius_md": "6px",
312
"radius_lg": "8px",
313
"radius_xl": "12px",
314
"radius_xxl": "16px",
315
}
316
```
317
318
Usage examples:
319
320
```python
321
import gradio as gr
322
323
# Use predefined size scales
324
theme = gr.themes.Base(
325
spacing_size="xl", # Larger spacing
326
radius_size="sm", # Smaller border radius
327
text_size="lg" # Larger text
328
)
329
330
# Custom size configuration
331
custom_spacing = gr.themes.Size(
332
xs="2px",
333
sm="6px",
334
md="12px",
335
lg="20px",
336
xl="32px"
337
)
338
```
339
340
## Theme Customization Patterns
341
342
### Complete Theme Customization
343
344
Creating fully customized themes with colors, fonts, and spacing:
345
346
```python
347
import gradio as gr
348
349
# Define custom brand colors
350
brand_primary = gr.themes.Color(
351
c50="#f0f9ff",
352
c100="#e0f2fe",
353
c200="#bae6fd",
354
c300="#7dd3fc",
355
c400="#38bdf8",
356
c500="#0ea5e9", # Main brand color
357
c600="#0284c7",
358
c700="#0369a1",
359
c800="#075985",
360
c900="#0c4a6e",
361
name="brand-blue"
362
)
363
364
# Load custom fonts
365
brand_font = gr.themes.GoogleFont("Inter", weights=[400, 500, 600, 700])
366
code_font = gr.themes.GoogleFont("JetBrains Mono", weights=[400, 500])
367
368
# Create comprehensive theme
369
brand_theme = gr.themes.Base(
370
# Colors
371
primary_hue=brand_primary,
372
secondary_hue=gr.themes.colors.slate,
373
neutral_hue=gr.themes.colors.gray,
374
375
# Typography
376
font=brand_font,
377
font_mono=code_font,
378
text_size="md",
379
380
# Spacing and layout
381
spacing_size="lg",
382
radius_size="md"
383
)
384
385
# Apply to interface
386
with gr.Blocks(theme=brand_theme) as demo:
387
gr.Markdown("# Custom Branded Interface")
388
gr.Textbox(label="Input")
389
gr.Button("Submit", variant="primary")
390
```
391
392
### Theme Inheritance and Modification
393
394
Extending existing themes with custom modifications:
395
396
```python
397
import gradio as gr
398
399
# Start with base theme and customize
400
corporate_theme = gr.themes.Soft(
401
primary_hue="blue",
402
secondary_hue="gray"
403
).set(
404
# Override specific properties
405
button_primary_background_fill="#2563eb",
406
button_primary_background_fill_hover="#1d4ed8",
407
block_background_fill="#f8fafc"
408
)
409
410
# Fine-tune component styles
411
corporate_theme.set(
412
# Input components
413
input_background_fill="white",
414
input_border_color="#d1d5db",
415
input_border_width="1px",
416
417
# Layout
418
panel_background_fill="white",
419
panel_border_color="#e5e7eb",
420
panel_border_width="1px"
421
)
422
```
423
424
### Dark Theme Creation
425
426
Creating dark mode themes with appropriate contrast and accessibility:
427
428
```python
429
import gradio as gr
430
431
dark_theme = gr.themes.Base(
432
primary_hue=gr.themes.colors.blue,
433
secondary_hue=gr.themes.colors.slate,
434
neutral_hue=gr.themes.colors.slate
435
).set(
436
# Dark backgrounds
437
background_fill_primary="#0f172a",
438
background_fill_secondary="#1e293b",
439
440
# Dark panels
441
panel_background_fill="#1e293b",
442
panel_border_color="#334155",
443
444
# Input styling
445
input_background_fill="#334155",
446
input_background_fill_focus="#475569",
447
input_border_color="#64748b",
448
449
# Text colors
450
body_text_color="#f1f5f9",
451
body_text_color_subdued="#cbd5e1",
452
453
# Button styling
454
button_secondary_background_fill="#475569",
455
button_secondary_background_fill_hover="#64748b"
456
)
457
```
458
459
### Component-Specific Styling
460
461
Targeting specific component types for detailed customization:
462
463
```python
464
import gradio as gr
465
466
component_theme = gr.themes.Default().set(
467
# Textbox styling
468
input_background_fill="#ffffff",
469
input_border_color="#d1d5db",
470
input_border_color_focus="#3b82f6",
471
input_border_width="2px",
472
input_border_radius="8px",
473
474
# Button styling
475
button_primary_background_fill="#3b82f6",
476
button_primary_background_fill_hover="#2563eb",
477
button_primary_text_color="white",
478
button_border_radius="6px",
479
480
# Gallery styling
481
gallery_border_color="#e5e7eb",
482
gallery_border_radius="8px",
483
484
# Panel styling
485
panel_background_fill="#f9fafb",
486
panel_border_color="#e5e7eb",
487
panel_border_radius="12px"
488
)
489
```
490
491
## Theme Distribution and Sharing
492
493
### Uploading Themes to Hugging Face Hub
494
495
Share custom themes with the community through Hugging Face Hub:
496
497
```python
498
import gradio as gr
499
500
# Create custom theme
501
my_theme = gr.themes.Base(
502
primary_hue="green",
503
secondary_hue="blue"
504
)
505
506
# Upload to Hub
507
my_theme.push_to_hub(
508
repo_id="username/my-gradio-theme",
509
commit_message="Add custom green theme"
510
)
511
```
512
513
### Loading Themes from Hub
514
515
Use community themes in your interfaces:
516
517
```python
518
import gradio as gr
519
520
# Load theme from Hub
521
community_theme = gr.themes.from_hub("username/awesome-theme")
522
523
# Use in interface
524
demo = gr.Interface(
525
fn=my_function,
526
inputs="text",
527
outputs="text",
528
theme=community_theme
529
)
530
```
531
532
### Theme CSS Export
533
534
Export themes as CSS for use in custom applications:
535
536
```python
537
# Export theme CSS
538
css_output = my_theme.to_css()
539
540
# Save to file
541
with open("custom-theme.css", "w") as f:
542
f.write(css_output)
543
544
# Use CSS in Blocks
545
with gr.Blocks(css="custom-theme.css") as demo:
546
# Interface components
547
pass
548
```
549
550
## Advanced Theming
551
552
### CSS Variable Access
553
554
Access and modify CSS variables directly for fine-grained control:
555
556
```python
557
advanced_theme = gr.themes.Base().set(
558
# Typography variables
559
"--text-lg": "18px",
560
"--font-weight-bold": "600",
561
562
# Color variables
563
"--primary-50": "#eff6ff",
564
"--primary-500": "#3b82f6",
565
"--primary-900": "#1e3a8a",
566
567
# Spacing variables
568
"--spacing-lg": "12px",
569
"--radius-md": "8px",
570
571
# Component-specific variables
572
"--button-shadow": "0 1px 3px rgba(0,0,0,0.1)",
573
"--input-shadow-focus": "0 0 0 3px rgba(59,130,246,0.1)"
574
)
575
```
576
577
### Responsive Theme Adjustments
578
579
Themes that adapt to different screen sizes and devices:
580
581
```python
582
responsive_theme = gr.themes.Base(
583
text_size="md" # Base text size
584
).set(
585
# Mobile adjustments
586
"--text-sm-mobile": "14px",
587
"--spacing-lg-mobile": "6px",
588
589
# Tablet adjustments
590
"--text-md-tablet": "16px",
591
"--spacing-lg-tablet": "10px",
592
593
# Desktop optimizations
594
"--text-lg-desktop": "18px",
595
"--spacing-xl-desktop": "16px"
596
)
597
```
598
599
### Theme Performance Optimization
600
601
Optimize themes for better performance and loading:
602
603
```python
604
# Minimize CSS output
605
optimized_theme = gr.themes.Base(
606
# Use fewer color variations
607
primary_hue="blue",
608
secondary_hue="blue", # Reuse primary
609
neutral_hue="gray"
610
).set(
611
# Disable expensive effects
612
"--shadow-drop": "none",
613
"--backdrop-blur": "none",
614
615
# Optimize animations
616
"--transition-duration": "0.1s"
617
)
618
```