#file-explorer #terminal-file #explorer #ratatui #tui #file #terminal

ratatui-explorer

ratatui-explorer is a small, but highly customizable, file explorer widget for ratatui

3 releases

0.1.2 Sep 23, 2024
0.1.1 Feb 20, 2024
0.1.0 Feb 19, 2024

#428 in Command-line interface

Download history 12/week @ 2024-08-03 676/week @ 2024-08-10 62/week @ 2024-08-17 79/week @ 2024-08-24 32/week @ 2024-08-31 7/week @ 2024-09-07 9/week @ 2024-09-14 180/week @ 2024-09-21 93/week @ 2024-09-28 12/week @ 2024-10-05 22/week @ 2024-10-12 234/week @ 2024-10-19 71/week @ 2024-10-26 32/week @ 2024-11-02 55/week @ 2024-11-09 136/week @ 2024-11-16

313 downloads per month
Used in 3 crates

MIT license

1.5MB
457 lines

ratatui-explorer

ratatui-explorer is a simple library for creating file explorers for ratatui.

Features:

  • File explorer functionality.
  • Input handling (from crossterm, termion, termwiz and your own backend).
  • Customizable widget theming.

Examples

Run cargo run --example to try the different example available.

Basic usage

The simplest use of ratatui-explorer with the crossterm backend.

cargo run --example basic

basic usage demonstration


Light and dark theme

Switching custom themes while running.

cargo run --example light_and_dark_theme

theme switching demonstration


File preview

Adapt the interface depending on the selected file.

cargo run --example file_preview

file preview demonstration

Basic usage

Install the libraries in your Cargo.toml file:

cargo add ratatui ratatui-explorer crossterm

Then inside your main.rs file:

use std::io::{self, stdout};

use crossterm::{
    event::{read, Event, KeyCode},
    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
    ExecutableCommand,
};
use ratatui::prelude::*;

use ratatui_explorer::{FileExplorer, Theme};

fn main() -> io::Result<()> {
    enable_raw_mode()?;
    stdout().execute(EnterAlternateScreen)?;

    let mut terminal = Terminal::new(CrosstermBackend::new(stdout()))?;

    // Create a new file explorer with the default theme and title.
    let theme = Theme::default().add_default_title();
    let mut file_explorer = FileExplorer::with_theme(theme)?;

    loop {
        // Render the file explorer widget.
        terminal.draw(|f| {
            f.render_widget(&file_explorer.widget(), f.area());
        })?;

        // Read the next event from the terminal.
        let event = read()?;
        if let Event::Key(key) = event {
            if key.code == KeyCode::Char('q') {
                break;
            }
        }
        // Handle the event in the file explorer.
        file_explorer.handle(&event)?;
    }

    disable_raw_mode()?;
    stdout().execute(LeaveAlternateScreen)?;
    Ok(())
}

Customizing the theme

You can customize the theme of the file explorer widget by using the Theme struct.

use ratatui::{prelude::*, widgets::*};
use ratatui_explorer::Theme;

let theme = Theme::default()
    .add_default_title()
    .with_title_bottom(|fe| format!("[{} files]", fe.files().len()).into())
    .with_block(Block::default().borders(Borders::ALL).border_type(BorderType::Rounded))
    .with_highlight_item_style(Style::default().fg(Color::Yellow).add_modifier(Modifier::BOLD))
    .with_highlight_dir_style(Style::default().fg(Color::Red).add_modifier(Modifier::BOLD))
    .with_highlight_symbol("> ".into());

Bindings

The following bindings are used by default for crossterm, termion and termwiz.

Binding Action
j, <DownArrow> Move the selection down
k, <UpArrow> Move the selection up
h, <LeftArrow>, <Backspace> Go to the parent directory
l, <RightArrow>, <Enter> Go to the child directory*

*if the selected item is a directory

Dependencies

~8–20MB
~314K SLoC