Struct FileExplorer 

pub struct FileExplorer {

    pub current_dir: PathBuf,
    pub theme_name: String,
    pub editor_name: String,
    pub entries: Vec<FsEntry>,
    pub cursor: usize,
    pub extension_filter: Vec<String>,
    pub show_hidden: bool,
    pub sort_mode: SortMode,
    pub search_query: String,
    pub search_active: bool,
    pub marked: HashSet<PathBuf>,
    pub mkdir_active: bool,
    pub mkdir_input: String,
    pub touch_active: bool,
    pub touch_input: String,
    pub rename_active: bool,
    pub rename_input: String,
    /* private fields */
}

State for the file-explorer widget.

Keep one instance in your application state and pass a mutable reference to [crate::render] and FileExplorer::handle_key on every frame / key event.

Example

use tui_file_explorer::{FileExplorer, ExplorerOutcome};
use crossterm::event::{KeyCode, KeyEvent, KeyModifiers};

let mut explorer = FileExplorer::new(
    std::env::current_dir().unwrap(),
    vec!["iso".into(), "img".into()],
);

match explorer.handle_key(key) {
    ExplorerOutcome::Selected(path) => println!("chosen: {}", path.display()),
    ExplorerOutcome::Dismissed      => println!("closed"),
    _                               => {}
}

Fields

current_dir: PathBuf

The directory currently being browsed.

theme_name: String

The name of the currently active theme (used in the header display).

editor_name: String

The label of the currently configured editor (used in the header display).

entries: Vec<FsEntry>

Sorted, search-filtered list of visible entries (dirs first, then files).

cursor: usize

Index of the highlighted entry.

extension_filter: Vec<String>

Only files whose extension is in this list are selectable. Directories are always shown and always navigable. An empty Vec means all files are selectable.

show_hidden: bool

Whether to show dotfiles / hidden entries.

sort_mode: SortMode

Current sort order for directory entries.

search_query: String

Current incremental-search query (empty = no search active).

search_active: bool

Whether the explorer is currently capturing keystrokes for search input.

marked: HashSet<PathBuf>

Paths that have been space-marked for a multi-item operation.

mkdir_active: bool

Whether the explorer is currently capturing keystrokes for a new folder name.

mkdir_input: String

The folder name being typed when mkdir_active is true.

touch_active: bool

Whether the explorer is currently capturing keystrokes for a new file name.

touch_input: String

The file name being typed when touch_active is true.

rename_active: bool

Whether the explorer is currently capturing keystrokes for a rename operation.

rename_input: String

The new name being typed when rename_active is true.

Implementations

impl FileExplorer

pub fn new(initial_dir: PathBuf, extension_filter: Vec<String>) -> FileExplorer

Create a new explorer starting at initial_dir.

extension_filter is a list of lower-case extensions without the leading dot (e.g. vec!["iso".into(), "img".into()]). Pass an empty Vec to allow all files.

For more configuration options use FileExplorer::builder instead.

pub fn builder(initial_dir: PathBuf) -> FileExplorerBuilder

Return a FileExplorerBuilder for constructing an explorer with fine-grained configuration.

Example

use tui_file_explorer::{FileExplorer, SortMode};

let explorer = FileExplorer::builder(std::env::current_dir().unwrap())
    .extension_filter(vec!["rs".into(), "toml".into()])
    .show_hidden(true)
    .sort_mode(SortMode::SizeDesc)
    .build();

pub fn navigate_to(&mut self, path: impl Into<PathBuf>)

Navigate to path, resetting cursor, scroll, and any active search.

Accepts anything that converts into a PathBuf — a PathBuf, &Path, &str, or String all work.

use tui_file_explorer::FileExplorer;

let mut explorer = FileExplorer::new(std::env::current_dir().unwrap(), vec![]);
explorer.navigate_to("/tmp");
explorer.navigate_to(std::path::Path::new("/home"));

pub fn marked_paths(&self) -> &HashSet<PathBuf>

Process a single keyboard event and return the ExplorerOutcome.

Call this from your application’s key-handling function and act on ExplorerOutcome::Selected / ExplorerOutcome::Dismissed. Return the set of currently marked paths (for multi-item operations).

pub fn toggle_mark(&mut self)

Toggle the space-mark on the currently highlighted entry and move the cursor down by one.

pub fn clear_marks(&mut self)

Clear all space-marks (called after a multi-delete or on navigation).

pub fn handle_key(&mut self, key: KeyEvent) -> ExplorerOutcome

pub fn current_entry(&self) -> Option<&FsEntry>

The currently highlighted FsEntry, or None if the list is empty.

pub fn is_mkdir_active(&self) -> bool

Whether the explorer is in mkdir (new-folder input) mode.

pub fn mkdir_input(&self) -> &str

The folder name being typed when mkdir mode is active.

pub fn is_touch_active(&self) -> bool

Whether the explorer is in touch (new-file input) mode.

pub fn touch_input(&self) -> &str

The file name being typed when touch mode is active.

pub fn is_rename_active(&self) -> bool

Whether the explorer is in rename (entry-rename input) mode.

pub fn rename_input(&self) -> &str

The new name being typed when rename mode is active.

pub fn is_at_root(&self) -> bool

Returns true when the explorer is at the filesystem root and cannot ascend any further.

use tui_file_explorer::FileExplorer;

let mut explorer = FileExplorer::new(std::path::PathBuf::from("/"), vec![]);
assert!(explorer.is_at_root());

pub fn is_empty(&self) -> bool

Returns true when the current directory contains no visible entries.

This reflects the filtered, visible set — hidden files are excluded unless show_hidden is true, and an active search query narrows the set further.

pub fn entry_count(&self) -> usize

The number of visible entries in the current directory.

Equivalent to explorer.entries.len() but reads more naturally in condition checks.

pub fn status(&self) -> &str

The current human-readable status message.

The status is set by the widget when an error occurs (e.g. attempting to select a file that does not match the extension filter) and is cleared on the next successful navigation. Returns an empty string when there is nothing to report.

pub fn sort_mode(&self) -> SortMode

The current sort mode.

use tui_file_explorer::{FileExplorer, SortMode};

let explorer = FileExplorer::new(std::path::PathBuf::from("/tmp"), vec![]);
assert_eq!(explorer.sort_mode(), SortMode::Name);

pub fn search_query(&self) -> &str

The current incremental-search query string.

Returns an empty string when no search is active.

pub fn is_searching(&self) -> bool

Returns true when the explorer is actively capturing keystrokes for incremental search input.

pub fn set_show_hidden(&mut self, show: bool)

Set whether hidden (dot-file) entries are visible and reload the directory listing immediately.

The user can also toggle this at runtime with the . key.

use tui_file_explorer::FileExplorer;

let mut explorer = FileExplorer::new(std::env::current_dir().unwrap(), vec![]);
explorer.set_show_hidden(true);
assert!(explorer.show_hidden);

pub fn set_extension_filter<I, S>(&mut self, filter: I)

where I: IntoIterator<Item = S>, S: Into<String>,

Replace the extension filter and reload the directory listing immediately.

Accepts any iterable of values that convert to String — plain &str slices, String values, and arrays all work:

use tui_file_explorer::FileExplorer;

let mut explorer = FileExplorer::new(std::env::current_dir().unwrap(), vec![]);

// Array of &str — no .into() needed
explorer.set_extension_filter(["rs", "toml"]);

// Vec<String>
explorer.set_extension_filter(vec!["iso".to_string(), "img".to_string()]);

// Empty — allow all files
explorer.set_extension_filter([] as [&str; 0]);

pub fn set_sort_mode(&mut self, mode: SortMode)

Change the sort mode and reload the directory listing immediately.

The user can also cycle through modes at runtime with the s key.

use tui_file_explorer::{FileExplorer, SortMode};

let mut explorer = FileExplorer::new(std::env::current_dir().unwrap(), vec![]);
explorer.set_sort_mode(SortMode::SizeDesc);
assert_eq!(explorer.sort_mode(), SortMode::SizeDesc);

pub fn reload(&mut self)

Re-read the current directory from the filesystem.

Called automatically after every navigation action or configuration change. Callers can invoke it manually after external filesystem mutations (e.g. a file was created or deleted in the watched directory).

Trait Implementations

impl Debug for FileExplorer

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.