🎨 ratatui-themes

Beautiful, consistent color themes for ratatui terminal UI applications.

Features • Installation • Quick Start • Themes • API • Examples

✨ Features

• 🎨 15+ Popular Themes — Dracula, Nord, Catppuccin, Gruvbox, Tokyo Night, and more
• 🔄 Easy Theme Cycling — Built-in next()/prev() methods for theme switchers
• 📦 Serde Support — Optional serialization for saving theme preferences
• 🌗 Light/Dark Detection — Programmatically determine if a theme is light or dark
• 🎯 Semantic Colors — Consistent error, warning, success, info across all themes
• ⚡ Zero Dependencies — Only requires ratatui (and optionally serde)

📦 Installation

Add to your Cargo.toml:

[dependencies]
ratatui-themes = "0.1"

With serde support for configuration files:

[dependencies]
ratatui-themes = { version = "0.1", features = ["serde"] }

🚀 Quick Start

use ratatui_themes::{Theme, ThemeName};
use ratatui::style::Style;

// Create a theme
let theme = Theme::new(ThemeName::Dracula);

// Access the color palette
let palette = theme.palette();

// Apply colors to styles
let title_style = Style::default()
    .fg(palette.accent)
    .bg(palette.bg);

let error_style = Style::default()
    .fg(palette.error);

let muted_text = Style::default()
    .fg(palette.muted);

🎨 Available Themes

🔧 API Reference

ThemePalette

Every theme provides a consistent color palette with semantic meaning:

pub struct ThemePalette {
    // Core colors
    pub accent: Color,      // Primary accent for highlights, selections
    pub secondary: Color,   // Secondary accent for less prominent elements
    pub bg: Color,          // Main background color
    pub fg: Color,          // Primary foreground/text color
    pub muted: Color,       // Dimmed text, comments, placeholders
    pub selection: Color,   // Selection/highlight background
    
    // Semantic colors
    pub error: Color,       // Errors, deletions, critical alerts
    pub warning: Color,     // Warnings, cautions, pending states
    pub success: Color,     // Success, additions, confirmations
    pub info: Color,        // Information, links, neutral highlights
}

Theme Cycling

Build theme switchers with ease:

use ratatui_themes::ThemeName;

let mut current = ThemeName::Dracula;

// Cycle forward through all themes
current = current.next();  // -> OneDarkPro

// Cycle backward
current = current.prev();  // -> Dracula

// Get all available themes
let all_themes = ThemeName::all();

Light/Dark Detection

use ratatui_themes::{Theme, ThemeName};

let theme = Theme::new(ThemeName::CatppuccinLatte);

if theme.is_light() {
    // Adjust UI for light theme
}

if theme.is_dark() {
    // Adjust UI for dark theme
}

Serde Integration

Save and load theme preferences (requires serde feature):

use ratatui_themes::ThemeName;
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize)]
struct AppConfig {
    theme: ThemeName,
    // ... other settings
}

// Serializes as: { "theme": "tokyo-night" }
// Theme names use kebab-case for human readability

📖 Examples

Complete TUI App Example

use ratatui::{
    prelude::*,
    widgets::{Block, Borders, Paragraph},
};
use ratatui_themes::{Theme, ThemeName};

struct App {
    theme: Theme,
}

impl App {
    fn new() -> Self {
        Self {
            theme: Theme::new(ThemeName::TokyoNight),
        }
    }

    fn render(&self, frame: &mut Frame) {
        let palette = self.theme.palette();
        
        // Create styled block
        let block = Block::default()
            .title(" My App ")
            .borders(Borders::ALL)
            .border_style(Style::default().fg(palette.muted))
            .title_style(Style::default().fg(palette.accent).bold());

        // Create paragraph with theme colors
        let text = Paragraph::new("Welcome!")
            .style(Style::default().fg(palette.fg).bg(palette.bg))
            .block(block);

        frame.render_widget(text, frame.area());
    }

    fn cycle_theme(&mut self) {
        let next_name = self.theme.name().next();
        self.theme = Theme::new(next_name);
    }
}

Status Bar with Semantic Colors

use ratatui_themes::{Theme, ThemeName};

fn render_status_bar(theme: &Theme, status: &str) -> Style {
    let palette = theme.palette();
    
    match status {
        "error" => Style::default().fg(palette.error).bold(),
        "warning" => Style::default().fg(palette.warning),
        "success" => Style::default().fg(palette.success),
        _ => Style::default().fg(palette.info),
    }
}

🤝 Contributing

Contributions are welcome! Here's how you can help:

• 🐛 Report bugs — Open an issue describing the problem
• 💡 Suggest themes — Request popular themes to be added
• 🔧 Submit PRs — Add new themes or improve existing ones

Adding a New Theme

1. Add the theme variant to ThemeName enum in src/theme.rs
2. Implement the palette in ThemePalette::from_name()
3. Add to ThemeName::all() list
4. Update the README theme table
5. Add tests

📄 License

MIT License — see LICENSE for details.

Made with ❤️ for the ratatui community