Custom Themes

Custom Themes & Styling Guide

Mastui features a flexible theming engine built on top of Textual's Theme system. You can choose from pre-installed color themes, toggle between dark and light modes with a single keypress, or define completely custom color schemes in JSON.

---

🎨 Built-In Themes

Mastui includes standard Textual palettes as well as popular terminal color schemes:

• textual-dark (Default modern dark palette)
• textual-light (Clean light theme)
• retro-green (Classic monochrome phosphor terminal look)
• tokyo-night (Vibrant deep blue/purple aesthetic)
• dracula (Popular high-contrast vampire palette)
• nord (Arctic, north-bluish clean palette)
• gruvbox (Warm retro groove colors)
• solarized-dark / solarized-light (Precision low-contrast palettes)

---

🌓 Dark / Light Mode Switching (d)

Pressing d instantly toggles between your preferred dark and light themes without opening menus. You can configure which themes are bound to the toggle in your ~/.config/mastui/profiles/<profile>/.env file:

PREFERRED_DARK_THEME=tokyo-night
PREFERRED_LIGHT_THEME=textual-light

---

🛠️ Creating Custom Themes (custom-themes.json)

Custom themes are loaded globally from:

~/.config/mastui/custom-themes.json

If the file does not exist, Mastui automatically creates a starter template containing the retro-green theme.

JSON Structure

custom-themes.json contains a JSON array of theme objects. Each theme defines:

1. name: Unique string identifier used in THEME=name.
2. palettes: High-level semantic color roles.
3. styles: Textual CSS styling rules mapped to Mastui UI components.

[
    {
        "name": "my-custom-theme",
        "palettes": {
            "primary": "#3B82F6",
            "secondary": "#1D4ED8",
            "accent": "#60A5FA",
            "foreground": "#E2E8F0",
            "background": "#0F172A",
            "surface": "#1E293B",
            "panel": "#1E293B",
            "success": "#22C55E",
            "warning": "#EAB308",
            "error": "#EF4444",
            "dark": true
        },
        "styles": {
            "app": "bg: #0F172A text: #E2E8F0",
            "header": "bg: #1E293B text: #F8FAFC",
            "footer": "bg: #1E293B text: #94A3B8",
            "timeline_title": "text: #3B82F6 bold",
            "timeline-item.selected": "bg: #334155",
            "timeline-item.favourited": "text: #F43F5E",
            "timeline-item.reblogged": "text: #10B981",
            "post-footer": "text: #64748B",
            "boost-header": "text: #10B981",
            "poll-header": "text: #38BDF8",
            "poll-total-votes": "text: #94A3B8",
            "poll-expiry": "text: #64748B",
            "button": "bg: #334155 text: #F8FAFC",
            "button.primary": "bg: #2563EB text: #FFFFFF",
            "input": "bg: #1E293B text: #F8FAFC",
            "select": "bg: #1E293B text: #F8FAFC",
            "switch": "bg: #334155",
            "switch--on": "bg: #2563EB"
        }
    }
]

---

🌈 Ready-to-Use Custom Theme Examples

1. Catppuccin Mocha

{
    "name": "catppuccin-mocha",
    "palettes": {
        "primary": "#89B4FA",
        "secondary": "#B4BEFE",
        "accent": "#F5C2E7",
        "foreground": "#CDD6F4",
        "background": "#1E1E2E",
        "surface": "#313244",
        "panel": "#313244",
        "success": "#A6E3A1",
        "warning": "#F9E2AF",
        "error": "#F38BA8",
        "dark": true
    },
    "styles": {
        "app": "bg: #1E1E2E text: #CDD6F4",
        "header": "bg: #181825 text: #CDD6F4",
        "footer": "bg: #181825 text: #A6ADC8",
        "timeline_title": "text: #89B4FA bold",
        "timeline-item.selected": "bg: #313244",
        "timeline-item.favourited": "text: #F38BA8",
        "timeline-item.reblogged": "text: #A6E3A1",
        "post-footer": "text: #6C7086",
        "boost-header": "text: #A6E3A1",
        "poll-header": "text: #89B4FA",
        "poll-total-votes": "text: #A6ADC8",
        "poll-expiry": "text: #6C7086",
        "button": "bg: #313244 text: #CDD6F4",
        "button.primary": "bg: #89B4FA text: #11111B",
        "input": "bg: #313244 text: #CDD6F4",
        "select": "bg: #313244 text: #CDD6F4",
        "switch": "bg: #313244",
        "switch--on": "bg: #A6E3A1"
    }
}

2. Cyberpunk Neon

{
    "name": "cyberpunk-neon",
    "palettes": {
        "primary": "#00FFFF",
        "secondary": "#FF007F",
        "accent": "#FFE600",
        "foreground": "#EEEEEE",
        "background": "#080812",
        "surface": "#14142B",
        "panel": "#14142B",
        "success": "#00FF66",
        "warning": "#FFE600",
        "error": "#FF0055",
        "dark": true
    },
    "styles": {
        "app": "bg: #080812 text: #EEEEEE",
        "header": "bg: #14142B text: #00FFFF",
        "footer": "bg: #14142B text: #FF007F",
        "timeline_title": "text: #FFE600 bold",
        "timeline-item.selected": "bg: #261D45",
        "timeline-item.favourited": "text: #FF007F",
        "timeline-item.reblogged": "text: #00FF66",
        "post-footer": "text: #707090",
        "boost-header": "text: #00FF66",
        "poll-header": "text: #00FFFF",
        "poll-total-votes": "text: #EEEEEE",
        "poll-expiry": "text: #707090",
        "button": "bg: #261D45 text: #EEEEEE",
        "button.primary": "bg: #FF007F text: #FFFFFF",
        "input": "bg: #14142B text: #00FFFF",
        "select": "bg: #14142B text: #00FFFF",
        "switch": "bg: #261D45",
        "switch--on": "bg: #00FF66"
    }
}

---

🚀 Activating Your Custom Theme

Once added to ~/.config/mastui/custom-themes.json:

1. Set THEME=catppuccin-mocha in your ~/.config/mastui/profiles/<profile>/.env, or
2. Open Mastui and switch themes using the in-app options menu.