0
# Themes and Customization
1

2
Theme system providing visual customization including colors, icons, and styling for inquirer prompts. Includes built-in themes and support for custom theme creation from JSON or dictionaries with comprehensive color and symbol customization.
3

4
## Capabilities
5

6
### Built-in Themes
7

8
Four pre-designed themes with different color schemes and visual styles for various use cases and preferences.
9

10
```python { .api }
11
class Default:
12
    """Default inquirer theme with standard colors and symbols."""
13
    
14
    def __init__(self):
15
        """Initialize default theme with cyan selections and yellow marks."""
16

17
class GreenPassion:
18
    """Green-themed color scheme with nature-inspired styling."""
19
    
20
    def __init__(self):
21
        """Initialize green theme with bold green selections and nature symbols."""
22

23
class RedSolace:
24
    """Red-themed color scheme with warm, energetic styling."""
25
    
26
    def __init__(self):
27
        """Initialize red theme with bright red selections and fire symbols."""
28

29
class BlueComposure:
30
    """Blue-themed color scheme with calm, professional styling."""
31
    
32
    def __init__(self):
33
        """Initialize blue theme with blue selections and geometric symbols."""
34
```
35

36
**Usage Examples:**
37

38
```python
39
import inquirer
40
from inquirer.themes import Default, GreenPassion, RedSolace, BlueComposure
41

42
# Using built-in themes
43
questions = [
44
    inquirer.List('color', message="Pick a color", choices=['Red', 'Green', 'Blue'])
45
]
46

47
# Default theme (automatic)
48
answers = inquirer.prompt(questions)
49

50
# Explicit theme selection
51
answers = inquirer.prompt(questions, theme=GreenPassion())
52
answers = inquirer.prompt(questions, theme=RedSolace())  
53
answers = inquirer.prompt(questions, theme=BlueComposure())
54

55
# Using themes with shortcuts
56
name = inquirer.text("Your name?", render=inquirer.render.console.ConsoleRender(theme=GreenPassion()))
57
```
58

59
### Custom Theme Creation from JSON
60

61
Load custom themes from JSON configuration, enabling theme sharing and version control.
62

63
```python { .api }
64
def load_theme_from_json(json_theme: str):
65
    """
66
    Load a custom theme from JSON string.
67
    
68
    Args:
69
        json_theme: JSON string with theme configuration
70
        
71
    Returns:
72
        Custom theme instance based on Default theme
73
        
74
    Raises:
75
        ThemeError: If theme configuration is invalid
76
        json.JSONDecodeError: If JSON is malformed
77
    """
78
```
79

80
**Usage Examples:**
81

82
```python
83
import inquirer
84
from inquirer.themes import load_theme_from_json
85

86
# Define custom theme in JSON
87
custom_theme_json = '''
88
{
89
    "Question": {
90
        "mark_color": "bright_magenta",
91
        "brackets_color": "cyan",
92
        "default_color": "white"
93
    },
94
    "List": {
95
        "selection_color": "bold_yellow_on_black",
96
        "selection_cursor": "→",
97
        "unselected_color": "gray"
98
    },
99
    "Checkbox": {
100
        "selection_color": "bold_yellow_on_black", 
101
        "selection_icon": "►",
102
        "selected_icon": "✓",
103
        "unselected_icon": "◯",
104
        "selected_color": "green",
105
        "unselected_color": "gray",
106
        "locked_option_color": "dim_white"
107
    }
108
}
109
'''
110

111
# Load and use custom theme
112
custom_theme = load_theme_from_json(custom_theme_json)
113

114
questions = [
115
    inquirer.Text('name', message="Your name?"),
116
    inquirer.List('color', message="Favorite color?", choices=['Red', 'Blue', 'Green']),
117
    inquirer.Checkbox('features', message="Select features", 
118
                     choices=['Feature A', 'Feature B', 'Feature C'])
119
]
120

121
answers = inquirer.prompt(questions, theme=custom_theme)
122

123
# Loading from file
124
with open('my_theme.json', 'r') as f:
125
    file_theme = load_theme_from_json(f.read())
126
```
127

128
### Custom Theme Creation from Dictionary
129

130
Create custom themes programmatically using dictionary configuration for dynamic theme generation.
131

132
```python { .api }
133
def load_theme_from_dict(dict_theme: dict):
134
    """
135
    Load a custom theme from dictionary configuration.
136
    
137
    Args:
138
        dict_theme: Dictionary with theme configuration
139
        
140
    Returns:
141
        Custom theme instance based on Default theme
142
        
143
    Raises:
144
        ThemeError: If theme configuration is invalid
145
    """
146
```
147

148
**Usage Examples:**
149

150
```python
151
import inquirer
152
from inquirer.themes import load_theme_from_dict
153

154
# Define theme programmatically
155
corporate_theme = {
156
    "Question": {
157
        "mark_color": "blue",
158
        "brackets_color": "bright_blue",
159
        "default_color": "cyan"
160
    },
161
    "List": {
162
        "selection_color": "bold_white_on_blue",
163
        "selection_cursor": "▶",
164
        "unselected_color": "bright_black"
165
    },
166
    "Checkbox": {
167
        "selection_color": "bold_white_on_blue",
168
        "selection_icon": "▶",
169
        "selected_icon": "[✓]",
170
        "unselected_icon": "[ ]", 
171
        "selected_color": "bright_blue",
172
        "unselected_color": "bright_black",
173
        "locked_option_color": "dim_blue"
174
    }
175
}
176

177
theme = load_theme_from_dict(corporate_theme)
178

179
# Use with prompt
180
answers = inquirer.prompt(questions, theme=theme)
181

182
# Dynamic theme generation
183
def create_theme_for_user(user_preferences):
184
    base_color = user_preferences.get('color', 'cyan')
185
    return load_theme_from_dict({
186
        "Question": {"mark_color": base_color},
187
        "List": {"selection_color": f"bold_{base_color}"},
188
        "Checkbox": {"selected_color": base_color}
189
    })
190

191
user_theme = create_theme_for_user({'color': 'green'})
192
```
193

194
## Theme Configuration Reference
195

196
### Question Element Styling
197

198
Controls the appearance of question prompts and markers.
199

200
```python
201
"Question": {
202
    "mark_color": "yellow",        # Color of the [?] marker
203
    "brackets_color": "normal",    # Color of the brackets around marker
204
    "default_color": "normal"      # Color of default value display
205
}
206
```
207

208
### List Selection Styling
209

210
Controls the appearance of list-type questions (List and autocomplete).
211

212
```python
213
"List": {
214
    "selection_color": "cyan",     # Color of selected/highlighted item
215
    "selection_cursor": ">",       # Symbol for current selection
216
    "unselected_color": "normal"   # Color of non-selected items
217
}
218
```
219

220
### Checkbox Styling
221

222
Controls the appearance of checkbox questions with multiple selection options.
223

224
```python
225
"Checkbox": {
226
    "selection_color": "cyan",           # Color of currently highlighted item
227
    "selection_icon": ">",               # Symbol for current highlight cursor
228
    "selected_icon": "[X]",              # Symbol for checked items
229
    "unselected_icon": "[ ]",            # Symbol for unchecked items
230
    "selected_color": "yellow_bold",     # Color of checked items
231
    "unselected_color": "normal",        # Color of unchecked items
232
    "locked_option_color": "gray50"      # Color of locked (unchangeable) items
233
}
234
```
235

236
### Editor Styling
237

238
Controls the appearance of editor question prompts.
239

240
```python
241
"Editor": {
242
    "opening_prompt_color": "bright_black"  # Color of the "Press <enter> to launch editor" text
243
}
244
```
245

246
## Available Colors and Styles
247

248
Inquirer uses the `blessed` terminal library for colors. Available color names include:
249

250
### Basic Colors
251
- `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`
252

253
### Bright Colors  
254
- `bright_black`, `bright_red`, `bright_green`, `bright_yellow`
255
- `bright_blue`, `bright_magenta`, `bright_cyan`, `bright_white`
256

257
### Styles
258
- `bold`, `dim`, `italic`, `underline`, `blink`, `reverse`
259
- Combine with colors: `bold_red`, `dim_blue`, `underline_green`
260

261
### Background Colors
262
- Format: `color_on_background`
263
- Examples: `white_on_blue`, `bold_yellow_on_black`, `red_on_white`
264

265
### Extended Colors
266
- 256-color support: `color1` through `color255`
267
- Named colors: `gray0` through `gray100`, `darkred`, `lightblue`, etc.
268

269
**Color Examples:**
270

271
```python
272
theme_config = {
273
    "Question": {
274
        "mark_color": "bold_bright_yellow",
275
        "brackets_color": "dim_white",
276
        "default_color": "italic_cyan"
277
    },
278
    "List": {
279
        "selection_color": "bold_white_on_blue",
280
        "selection_cursor": "❯",
281
        "unselected_color": "gray70"
282
    }
283
}
284
```
285

286
## Advanced Theme Customization
287

288
### Theme Inheritance and Extension
289

290
```python
291
from inquirer.themes import Default, load_theme_from_dict
292

293
# Start with default theme and modify specific elements
294
base_theme = Default()
295

296
# Extend with custom modifications
297
custom_modifications = {
298
    "Question": {
299
        "mark_color": "bright_magenta"  # Only change the question mark color
300
    },
301
    "Checkbox": {
302
        "selected_icon": "●",           # Use filled circle for selected
303
        "unselected_icon": "○"          # Use empty circle for unselected
304
    }
305
}
306

307
extended_theme = load_theme_from_dict(custom_modifications)
308
```
309

310
### Conditional Theme Selection
311

312
```python
313
import os
314
from inquirer.themes import Default, GreenPassion, RedSolace
315

316
def get_theme_for_environment():
317
    env = os.getenv('APP_ENV', 'development')
318
    if env == 'production':
319
        return RedSolace()  # Red for production warnings
320
    elif env == 'staging':
321
        return Default()    # Standard for staging
322
    else:
323
        return GreenPassion()  # Green for development
324

325
questions = [
326
    inquirer.Confirm('deploy', message="Deploy to {env}?".format(env=os.getenv('APP_ENV')))
327
]
328

329
answers = inquirer.prompt(questions, theme=get_theme_for_environment())
330
```
331

332
### Theme Validation and Error Handling
333

334
```python
335
from inquirer.themes import load_theme_from_dict
336
from inquirer.errors import ThemeError
337

338
def safe_load_theme(theme_config):
339
    try:
340
        return load_theme_from_dict(theme_config)
341
    except ThemeError as e:
342
        print(f"Theme error: {e}")
343
        print("Falling back to default theme")
344
        return Default()
345

346
# Potentially invalid theme config
347
theme_config = {
348
    "InvalidQuestionType": {  # This will cause ThemeError
349
        "mark_color": "red"
350
    }
351
}
352

353
safe_theme = safe_load_theme(theme_config)
354
```
355

356
## Base Theme Class
357

358
For advanced customization, you can create themes by extending the base Theme class:
359

360
```python { .api }
361
class Theme:
362
    """Base theme class defining theme structure."""
363
    
364
    def __init__(self):
365
        """
366
        Initialize theme with namedtuple definitions for each component.
367
        
368
        Creates namedtuple attributes for:
369
        - Question: mark_color, brackets_color, default_color
370
        - Editor: opening_prompt_color
371
        - Checkbox: selection_color, selection_icon, selected_color, unselected_color,
372
                   selected_icon, unselected_icon, locked_option_color
373
        - List: selection_color, selection_cursor, unselected_color
374
        """
375
        
376
    @property
377
    def Question(self):
378
        """Question styling namedtuple with mark_color, brackets_color, default_color."""
379
        
380
    @property  
381
    def Editor(self):
382
        """Editor styling namedtuple with opening_prompt_color."""
383
        
384
    @property
385
    def Checkbox(self):
386
        """Checkbox styling namedtuple with selection_color, selection_icon, selected_color, 
387
        unselected_color, selected_icon, unselected_icon, locked_option_color."""
388
        
389
    @property
390
    def List(self):
391
        """List styling namedtuple with selection_color, selection_cursor, unselected_color."""
392
```
393

394
**Custom Theme Class Example:**
395

396
```python
397
from inquirer.themes import Theme
398
from blessed import Terminal
399

400
term = Terminal()
401

402
class CustomTheme(Theme):
403
    def __init__(self):
404
        super().__init__()
405
        # Customize question appearance
406
        self.Question.mark_color = term.bold_magenta
407
        self.Question.brackets_color = term.bright_blue
408
        self.Question.default_color = term.cyan
409
        
410
        # Customize list appearance
411
        self.List.selection_color = term.bold_white_on_magenta
412
        self.List.selection_cursor = "❯"
413
        self.List.unselected_color = term.bright_black
414
        
415
        # Customize checkbox appearance
416
        self.Checkbox.selection_color = term.bold_white_on_magenta
417
        self.Checkbox.selected_icon = "✓"
418
        self.Checkbox.unselected_icon = "◯"
419
        self.Checkbox.selected_color = term.bold_green
420
        self.Checkbox.unselected_color = term.bright_black
421

422
# Use custom theme
423
custom_theme = CustomTheme()
424
answers = inquirer.prompt(questions, theme=custom_theme)
425
```