🍞 tui-breadcrumb

A customizable, responsive, and interactive hierarchical navigation trail widget for Ratatui.

┌─────────────────────────────────────────────────────────────────────────────┐
│ 📁 Home ❯ 📂 Projects ❯ 📦 ratatui ▾ ❯ 📄 sparkline.rs                     │
│    ▲          ▲             ▲                ▲                              │
│  Root      Parent      Ancestor with       Active                           │
│  Segment   Segment     Dropdown            Item                             │
└─────────────────────────────────────────────────────────────────────────────┘

📖 Overview

Terminal user interfaces—such as file managers, cloud resource consoles, database browsers, and nested configuration screens—frequently require breadcrumb navigation paths. Without a dedicated widget, developers often manually assemble Line and Span collections and write custom string truncations that break on Unicode characters or fail to support mouse interaction.

tui-breadcrumb solves this by providing:

• Built-in Separator Presets: Slash (/), Chevron (❯), Angle (›), Arrow (→), Pipe (|), Backslash (\\), Double Angle (»), or custom glyphs.
• Smart Responsive Truncation: Intelligently fits breadcrumbs to any terminal column width using strategies like Middle, Start, ShortenNames, End, or None.
• Full Interactivity (BreadcrumbState): Keyboard focus navigation (Left/Right arrows) and pixel-accurate mouse hit testing for segment clicks and ancestor dropdown triggers (▾).
• Filesystem Path Integration: Seamless conversions from standard std::path::Path.
• Zero Panics & Unicode Safe: Built with unicode-width to prevent column drift across emojis, CJK characters, and combining glyphs.

📦 Installation

Add tui-breadcrumb to your Cargo.toml:

cargo add tui-breadcrumb

Or manually:

[dependencies]
tui-breadcrumb = "0.1.0"
ratatui = "0.30"

🚀 Quick Start

1. Simple Stateless Breadcrumb

use ratatui::prelude::*;
use tui_breadcrumb::{Breadcrumb, BreadcrumbSeparator, TruncateStrategy};

fn render_trail(frame: &mut Frame, area: Rect) {
    let widget = Breadcrumb::new(["Home", "Projects", "ratatui", "src", "sparkline.rs"])
        .separator(BreadcrumbSeparator::chevron())
        .strategy(TruncateStrategy::middle())
        .item_style(Style::default().fg(Color::Gray))
        .active_style(Style::default().fg(Color::Yellow).bold());

    frame.render_widget(widget, area);
}

2. Interactive Stateful Breadcrumb (Keyboard & Mouse Support)

use ratatui::prelude::*;
use ratatui::crossterm::event::{Event, KeyCode, MouseEventKind, MouseButton};
use tui_breadcrumb::{Breadcrumb, BreadcrumbItem, BreadcrumbSeparator, BreadcrumbState, TruncateStrategy};

struct App {
    state: BreadcrumbState,
    items: Vec<BreadcrumbItem<'static>>,
}

impl App {
    fn new() -> Self {
        let mut state = BreadcrumbState::default();
        state.select(Some(2)); // Focus 3rd segment

        let items = vec![
            BreadcrumbItem::new("Home"),
            BreadcrumbItem::with_dropdown("Projects"),
            BreadcrumbItem::with_dropdown("ratatui"),
            BreadcrumbItem::new("src"),
            BreadcrumbItem::new("main.rs"),
        ];

        Self { state, items }
    }

    fn handle_event(&mut self, event: Event) {
        match event {
            Event::Key(key) => match key.code {
                KeyCode::Left => self.state.select_previous(self.items.len()),
                KeyCode::Right => self.state.select_next(self.items.len()),
                KeyCode::Home => self.state.select_first(),
                KeyCode::End => self.state.select_last(self.items.len()),
                _ => {}
            },
            Event::Mouse(mouse) if mouse.kind == MouseEventKind::Down(MouseButton::Left) => {
                let (col, row) = (mouse.column, mouse.row);
                // Check if user clicked an ancestor dropdown arrow (▾)
                if let Some(drop_idx) = self.state.dropdown_at(col, row) {
                    println!("Clicked dropdown for item index {}", drop_idx);
                }
                // Check if user clicked a crumb label
                else if let Some(item_idx) = self.state.item_at(col, row) {
                    self.state.select(Some(item_idx));
                }
            }
            _ => {}
        }
    }

    fn render(&mut self, frame: &mut Frame, area: Rect) {
        let widget = Breadcrumb::new(self.items.clone())
            .separator(BreadcrumbSeparator::chevron())
            .strategy(TruncateStrategy::middle())
            .selected_style(Style::default().bg(Color::DarkGray).fg(Color::White).bold());

        frame.render_stateful_widget(widget, area, &mut self.state);
    }
}

📐 Truncation Strategies

When a breadcrumb trail exceeds available terminal width, [TruncateStrategy] determines how segments are condensed:

// Examples of configuring strategies:
let middle = TruncateStrategy::middle_with(1, 2, "...");
let start = TruncateStrategy::start_with(2, "…");
let shorten = TruncateStrategy::shorten_names_with(1, 2, "...");

🎨 Separator Presets

BreadcrumbSeparator includes built-in glyph presets with configurable spacing and styling:

// Customize separator styling and spacing:
let sep = BreadcrumbSeparator::chevron()
    .spacing(1)
    .style(Style::default().fg(Color::DarkGray));

📂 Filesystem Path Integration

Easily initialize a breadcrumb navigation trail directly from a [std::path::Path]:

use std::path::Path;
use tui_breadcrumb::Breadcrumb;

let path = Path::new("/var/log/nginx/access.log");
let widget = Breadcrumb::from_path(path);

🎮 Examples & Demos

The examples/ directory includes multiple practical applications showcasing different integration patterns:

Example Highlights:

• Interactive Showcase (demo.rs): Navigate crumbs with ←/→/h/l, cycle separators with Tab, toggle strategies with 1–5, and click ▾ dropdown triggers.
• Minimal Quickstart (simple.rs): Minimal template for quick integration into existing projects.
• Filesystem Navigation (file_explorer.rs): Browse directories with Enter/Backspace, or click any parent breadcrumb segment to jump immediately to that directory.
• Theming & Powerline Gallery (custom_styling.rs): Inspect 4 visual themes: Powerline pill styling (), CI/CD status badges ([✔ Build] ❯ [⚡ Tests]), Retro green phosphor (//), and Minimal dots (•).
• Deep Hierarchies & Dropdowns (dropdown_menus.rs): Click ▾ on any resource level to open a floating modal of alternate sibling branches.
• Truncation & Width Caliper (responsive_resize.rs): Adjust container width in real time ([/] or arrow keys) to observe and compare all 5 truncation strategies on emoji-rich paths.

🧪 Testing & Verification

tui-breadcrumb includes a comprehensive verification suite:

# Run unit tests
cargo test --lib

# Run documentation tests
cargo test --doc

# Run property-based invariant tests (QuickCheck)
cargo test --test property_test

# Run visual regression snapshot tests (Insta)
cargo test --test snapshots

# Run linter and formatting checks
cargo clippy --all-targets --all-features -- -D warnings
cargo fmt --all -- --check

🤝 Contributing

Contributions are welcome! Please check out CONTRIBUTING.md for guidelines on development setup, running tests, code standards, and submitting pull requests.

📄 License

This project is dual-licensed under:

• MIT License (LICENSE-MIT or https://opensource.org/licenses/MIT)
• Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)

You may choose either license at your option.