# Tui-Logger Smart Widget Keyboard Shortcuts: Complete Reference Guide

> Master tui-logger smart widget keyboard shortcuts for efficient navigation and control. Explore a complete guide covering all 12 essential commands for enhanced productivity.

- Repository: [gin66/tui-logger](https://github.com/gin66/tui-logger)
- Tags: api-reference
- Published: 2026-03-02

---

**The tui-logger smart widget provides 12 distinct keyboard commands—including arrow keys for navigation, h/f for visibility toggles, and Page Up/Down for history scrolling—that are processed as `TuiWidgetEvent` variants via the `TuiWidgetState::transition()` method.**

The smart widget in the gin66/tui-logger repository combines a log viewer with an interactive target selector, enabling real-time log level adjustments and filtering directly in the terminal. Mastering these keyboard shortcuts allows developers to build intuitive TUI applications where users can dynamically control log output without leaving the keyboard.

## Complete Keyboard Shortcut Reference

The smart widget recognizes the following keyboard inputs, which are documented in the crate’s README section within [`src/lib.rs`](https://github.com/gin66/tui-logger/blob/main/src/lib.rs)【72†L72-L88】:

- **h** — Toggle the target selector widget between hidden and visible
- **f** — Switch focus to the currently selected target only
- **↑ (UP)** — Move the selection to the previous target in the selector
- **↓ (DOWN)** — Move the selection to the next target in the selector
- **← (LEFT)** — Decrease the *shown* log level (one step down)
- **→ (RIGHT)** — Increase the *shown* log level (one step up)
- **-** — Decrease the *captured* log level (one step down)
- **+** — Increase the *captured* log level (one step up)
- **PageUp** — Enter *page mode* and scroll roughly half a page up in the log history
- **PageDown** — In *page mode* only: scroll ten events down in the log history
- **Esc** — Leave *page mode* and return to normal scrolling
- **Space** — Toggle hiding of targets that have their log filter set to **Off**

## Internal Event Handling Architecture

Each keyboard shortcut maps to a variant of the `TuiWidgetEvent` enum defined in [`src/widget/inner.rs`](https://github.com/gin66/tui-logger/blob/main/src/widget/inner.rs)【45†L45-L58】. When the application receives a key press, it calls `TuiWidgetState::transition(event)`, which forwards the event to `TuiWidgetInnerState::transition`【83†L83-L138】.

This state machine updates shared internal state including:

- Selection indices for target navigation
- Visibility flags such as `hide_target` and `focus_selected`
- Log level thresholds for both *shown* and *captured* filters
- Paging pointers like `opt_line_pointer_center` for history navigation

The smart widget’s `render` method in [`src/widget/smart.rs`](https://github.com/gin66/tui-logger/blob/main/src/widget/smart.rs)【29†L29-L115】 reads these state values to determine whether to draw the target selector, which log level indicators to highlight, and how to apply paging offsets during terminal drawing.

## Implementing Keyboard Navigation in Your Application

To integrate these shortcuts into your terminal application, map your input library’s key events to `TuiWidgetEvent` variants and pass them to the shared state:

```rust
use tui_logger::{TuiWidgetState, TuiWidgetEvent};
use crossterm::event::{KeyCode, KeyEvent};

fn handle_input(state: &TuiWidgetState, key_event: KeyEvent) {
    match key_event.code {
        KeyCode::Char('h') => state.transition(TuiWidgetEvent::HideKey),
        KeyCode::Char('f') => state.transition(TuiWidgetEvent::FocusKey),
        KeyCode::Up       => state.transition(TuiWidgetEvent::UpKey),
        KeyCode::Down     => state.transition(TuiWidgetEvent::DownKey),
        KeyCode::Left     => state.transition(TuiWidgetEvent::LeftKey),
        KeyCode::Right    => state.transition(TuiWidgetEvent::RightKey),
        KeyCode::Char('-')=> state.transition(TuiWidgetEvent::MinusKey),
        KeyCode::Char('+')=> state.transition(TuiWidgetEvent::PlusKey),
        KeyCode::PageUp   => state.transition(TuiWidgetEvent::PrevPageKey),
        KeyCode::PageDown => state.transition(TuiWidgetEvent::NextPageKey),
        KeyCode::Esc      => state.transition(TuiWidgetEvent::EscapeKey),
        KeyCode::Char(' ')=> state.transition(TuiWidgetEvent::SpaceKey),
        _ => {}
    }
}

```

You can also programmatically simulate key events for testing or automation:

```rust
use tui_logger::TuiWidgetEvent::{UpKey, DownKey, LeftKey, RightKey, SpaceKey};

let state = TuiWidgetState::new();
state.transition(UpKey);        // Move selection up
state.transition(DownKey);      // Move selection down
state.transition(LeftKey);      // Decrease shown log level
state.transition(RightKey);     // Increase shown log level
state.transition(SpaceKey);     // Toggle hiding of Off-filtered targets

```

## Summary

- The tui-logger smart widget provides **12 keyboard shortcuts** for controlling visibility, navigation, log levels, and history paging.
- All shortcuts are represented by the **`TuiWidgetEvent` enum** in [`src/widget/inner.rs`](https://github.com/gin66/tui-logger/blob/main/src/widget/inner.rs).
- Input handling requires calling **`TuiWidgetState::transition()`**, which updates the internal state machine.
- The **`render`** method in [`src/widget/smart.rs`](https://github.com/gin66/tui-logger/blob/main/src/widget/smart.rs) reflects these state changes in the terminal interface.
- Application developers must bridge their input library (e.g., crossterm) to the `TuiWidgetEvent` variants to enable user interaction.

## Frequently Asked Questions

### What is the difference between "shown" and "captured" log levels?

The **shown** log level (adjusted with ←/→ arrow keys) controls which severity levels are visible in the widget display, letting you hide debug output without discarding it. The **captured** log level (adjusted with -/+ keys) controls which records the logger actually processes and stores internally. This dual-filtering system allows you to capture verbose logs for debugging while keeping the display focused on errors.

### How does page mode work for scrolling history?

Pressing **PageUp** enters a frozen *page mode* that scrolls roughly half a page up through historical log entries. While active, **PageDown** scrolls ten events downward, and **Esc** exits page mode to resume live scrolling. This prevents new incoming log messages from interrupting your review of past events.

### Can I remap the default keyboard shortcuts?

The current implementation uses fixed key mappings in the `TuiWidgetEvent` enum. To use different physical keys, map your preferred inputs to the standard `TuiWidgetEvent` variants in your application’s input handler, as demonstrated in the implementation example above. The library does not currently support runtime configuration of the event variants themselves.

### Why does the target selector not appear when the widget first renders?

The target selector starts in a hidden state by default. Press **h** to toggle its visibility. If the selector appears empty, press **Space** to ensure targets filtered to **Off** are not being hidden from the list.