tui-lipandocsv0.18.1
GitHub ↗

Patterns & Anti-Patterns ​

Common Patterns ​

1. View Function Extraction (Mockup → App Workflow) ​

Extract reusable view functions so the same code works in both mockup previews and real components:

rust
// View functions take plain data, return Element
fn sidebar(items: &[&str], selected: usize) -> Element {
    Frame::new()
        .header_left("Nav").border(true).width(Length::Px(28))
        .child(List::new().items(items.iter().map(|s| ListItem::new(*s))).selected(selected))
        .into()
}

// Step 1: preview with zero boilerplate
fn main() -> tui_lipan::Result<()> {
    let items = vec!["Home", "Settings"];
    mockup!("Preview", { sidebar(&items, 0) })
}

// Step 2: reuse in real component - no changes needed
fn view(&self, ctx: &Context<Self>) -> Element {
    sidebar(&ctx.state.items, ctx.state.selected)
}

2. Reusable Panel Shells (Parameterized UI) ​

When multiple panels share the same chrome but differ in header/footer labels or body, extract the shared shell into plain Rust helpers. The parameters come from Rust, while rsx! stays focused on composition.

rust
fn app_panel(title: impl Into<Arc<str>>, child: impl Into<Element>) -> Element {
    Frame::new()
        .header_left(title)
        .border(true)
        .padding(1)
        .child(child)
        .into()
}

fn stats_panel(title: &str, value: &str) -> Element {
    app_panel(
        title,
        rsx! {
            Text {
                content: value,
            }
        },
    )
}

fn view(&self, _ctx: &Context<Self>) -> Element {
    rsx! {
        HStack {
            stats_panel("CPU", "42%"),
            stats_panel("Memory", "1.2 GB"),
        }
    }
}

This is the preferred pattern when:

  • the reusable piece is mostly view/chrome
  • there is no local state or message handling
  • you want to share the same UI between mockups, examples, and real components

If you want a more structured API, wrap the same idea in a small composite widget:

Composite widget recipe:

  • define a #[derive(Clone)] props/builder struct;
  • store child Elements where the composite accepts arbitrary content;
  • implement From<MyComposite> for Element;
  • build the returned tree from existing primitives such as Frame, VStack, HStack, Text, and Button.
rust
#[derive(Clone)]
struct AppPanel {
    title: Arc<str>,
    child: Element,
}

impl AppPanel {
    fn new(title: impl Into<Arc<str>>, child: impl Into<Element>) -> Self {
        Self {
            title: title.into(),
            child: child.into(),
        }
    }
}

impl From<AppPanel> for Element {
    fn from(panel: AppPanel) -> Element {
        Frame::new()
            .header_left(panel.title)
            .border(true)
            .padding(1)
            .child(panel.child)
            .into()
    }
}

Use this when the same shell needs a named, reusable API such as AppPanel::new(...), .footer_left(...), .header(...), and .footer(...).

Choose the abstraction level by behavior:

  • Helper function returning Element - best for simple reusable shells
  • Composite widget struct - best for reusable builder-style UI with several options
  • Component with Properties - best when the reusable panel has its own state or events

3. Numbered List Rows ​

Prefer ListItem::numbered(...) or ListItem::bulleted(...) instead of embedding the prefix in the label string yourself. Extra lines automatically indent under the label text.

rust
List::new().items([
    ListItem::new("Alpha")
        .numbered(1)
        .line(ListItemLine::new("first option")),
    ListItem::new("Beta")
        .numbered(2)
        .line(ListItemLine::new("second option")),
])

4. Background Command Pattern ​

Offload blocking I/O to a background thread:

rust
fn update(&mut self, msg: Msg, ctx: &mut Context<Self>) -> Update {
    match msg {
        Msg::LoadUser(id) => {
            ctx.state.loading = true;
            let cmd = ctx.link().command(move |link| {
                let user = db::get_user(id);   // blocking
                link.send(Msg::UserLoaded(user));
            });
            Update::with_command(cmd)
        }
        Msg::UserLoaded(user) => {
            ctx.state.loading = false;
            ctx.state.user = Some(user);
            Update::full()
        }
    }
}

If the blocking work is an interactive subprocess that needs the real TTY ($EDITOR, a pager), do not use link.command / Command::spawn for that phase: use Command::new on the UI thread with terminal_handoff, then request_full_repaint() as needed. See External programs.

4. Keyed Coalescing (Filter-as-You-Type) ​

Avoid stale search results by using TaskPolicy::LatestOnly:

rust
Msg::QueryChanged(q) => {
    ctx.state.query = q.clone();
    let cmd = ctx.link().command_keyed(
        "search",
        TaskPolicy::LatestOnly,
        move |link| {
            let results = search_items(&q);
            link.send(Msg::SearchDone(results));
        },
    );
    Update::with_command(cmd)  // Redraw to show query immediately
}

5. Controlled Scroll with Synced State ​

For high-frequency scroll callbacks, separate widget-owned runtime state from visual state. Mirroring the latest offset usually should not rebuild the parent view.

rust
// Controlled list with parent-managed offset
List::new()
    .items(self.items.clone())
    .selected(self.selected)
    .on_scroll_to(ctx.link().callback(Msg::Scrolled))

// In update:
Msg::Scrolled(offset) => {
    ctx.state.scroll_offset = offset;
    Update::none()
}

For ScrollView::on_viewport_change, return Update::none() when only the stored offset changed. Return Update::layout() only when visible metadata changes the emitting component's view or subtree, such as a sticky header label. Reserve Update::full() for state that affects other scopes or root-level composition.

5a. Read-only list with no selection ​

Pass .selected(None) when a list should show rows without a current-row highlight (for example a directory preview pane). Keyboard navigation still adopts the first/last selectable row on Down/Up so the list is not inert.

rust
List::new()
    .items(preview_entries.iter().map(|e| ListItem::new(e.name.clone())))
    .selected(None)
    .focusable(false)

6. Memoized Heavy Child Components ​

When a parent rerenders often but some child panels/rows are expensive to rebuild, move those children into their own Component and give them a stable memo_key():

rust
impl Component for MessageRow {
    type Message = RowMsg;
    type Properties = MessageRowProps;
    type State = ();

    fn create_state(&self, _props: &Self::Properties) -> Self::State {}

    fn memo_key(&self, props: &Self::Properties, _ctx: &Context<Self>) -> Option<u64> {
        Some(props.revision)
    }

    fn view(&self, ctx: &Context<Self>) -> Element {
        render_message_row(ctx.props)
    }

    fn update(&mut self, _msg: RowMsg, _ctx: &mut Context<Self>) -> Update {
        Update::none()
    }
}

Use this when:

  • the subtree is expensive to build
  • parent updates are frequent but mostly unrelated to the child
  • the child's visual output is driven by a clear semantic revision key

Avoid using memo_key() as a manual diff cache for everything. If the subtree is cheap, a plain view helper is simpler.

7. Focus Routing ​

Use stable keys and explicit requests for pane-level navigation. This works under every FocusPolicy, including Manual:

rust
fn update(&mut self, msg: Msg, ctx: &mut Context<Self>) -> Update {
    match msg {
        Msg::FocusSidebar => { ctx.request_focus("sidebar"); Update::none() }
        Msg::FocusEditor  => { ctx.request_focus("editor");  Update::none() }
    }
}

fn on_key(&mut self, key: KeyEvent, ctx: &mut Context<Self>) -> KeyUpdate {
    match key.code {
        KeyCode::Char('1') if key.mods.ctrl => {
            ctx.request_focus("sidebar");
            KeyUpdate::handled(Update::none())
        }
        KeyCode::Char('2') if key.mods.ctrl => {
            ctx.request_focus("editor");
            KeyUpdate::handled(Update::none())
        }
        _ => KeyUpdate::unhandled(Update::none())
    }
}

Use .tab_stop(false) when a target should remain pointer/programmatically focusable but should not lengthen the global Tab ring. Wrap editor groups in FocusScope::Contain when Tab should cycle inside the group, and use pane-switch commands to leave it. Use FocusScope::Exclude for a subtree that should be absent from automatic and pointer focus while retaining request_focus(key) as an escape hatch.

Key dynamic focus targets. Under OnDemand, a temporarily unmounted focused key is retained and focus returns when that key remounts. Call ctx.blur() to forget it. Stable keys also suppress spurious widget on_blur/on_focus pairs across remounts.

Capturing overlays also make app-level focus handoff safe: ctx.request_focus may target content mounted behind a modal without first checking whether a modal is open. The framework keeps the latest outside target and applies it after the capture closes. Requests for fields inside the modal still resolve immediately, and ctx.blur() explicitly cancels both retained destinations.

Arrow Navigation Across a Group of Widgets ​

Framework traversal is linear: Tab and Shift-Tab walk one ring. Arrow keys belong to the focused widget — Tabs moves its active tab, List moves its selection — and only reach the component when the focused widget ignores them, which is exactly the case for a row of Buttons. That bubbling on_key is where grid-style navigation lives:

rust
const ROWS: [&[&str]; 2] = [&["cut", "copy", "paste"], &["undo", "redo"]];

fn on_key(&mut self, key: KeyEvent, ctx: &mut Context<Self>) -> KeyUpdate {
    let Some((row, col)) = ROWS.iter().enumerate().find_map(|(row, keys)| {
        keys.iter()
            .position(|key| ctx.has_focus_within_key(*key))
            .map(|col| (row, col))
    }) else {
        return KeyUpdate::unhandled(Update::none());
    };

    // Rows differ in length, so a vertical move clamps onto the shorter row.
    let in_row = |row: usize, col: usize| ROWS[row][col.min(ROWS[row].len() - 1)];
    let target = match key.code {
        KeyCode::Left => col.checked_sub(1).map(|col| in_row(row, col)),
        KeyCode::Right => (col + 1 < ROWS[row].len()).then(|| in_row(row, col + 1)),
        KeyCode::Up => row.checked_sub(1).map(|row| in_row(row, col)),
        KeyCode::Down => (row + 1 < ROWS.len()).then(|| in_row(row + 1, col)),
        _ => None,
    };

    match target {
        Some(target) => {
            ctx.request_focus(target);
            KeyUpdate::handled(Update::full())
        }
        // Unhandled at the edges, so the key still reaches app and framework bindings.
        None => KeyUpdate::unhandled(Update::none()),
    }
}

examples/widgets.rs runs this over two button rows. Composite widgets that own a group — Radio, DatePicker — already implement the same idea internally as one tab stop plus arrows; follow that shape when a group is really one control, and keep the group's members out of the Tab ring with .tab_stop(false).

8. Conditional Overlay Pattern ​

Show modals/overlays via state flags (not routing):

rust
// State
struct State {
    show_delete_confirm: bool,
    selected_item: usize,
}

// View
fn view(&self, ctx: &Context<Self>) -> Element {
    rsx! {
        VStack {
            List { items: ..., selected: ctx.state.selected_item }

            if ctx.state.show_delete_confirm {
                Modal {
                    title: "Confirm Delete",
                    VStack {
                        gap: 1,
                        Text { content: "This cannot be undone." }
                        HStack {
                            gap: 1,
                            Button {
                                label: "Cancel",
                                on_click: ctx.link().callback(|_| Msg::CancelDelete),
                            }
                            Button {
                                label: "Delete",
                                on_click: ctx.link().callback(|_| Msg::ConfirmDelete),
                            }
                        }
                    }
                }
            }
        }
    }
}

9. Toast from Update ​

rust
Msg::SaveSuccess => {
    ctx.toast().push(Toast::new("File saved!"));
    Update::none()
}
Msg::SaveError(e) => {
    ctx.toast().push(Toast::new(format!("Error: {e}")).title("Error"));
    Update::none()
}

10. Dynamic Tab Management ​

rust
struct State {
    tabs: Vec<String>,
    active: usize,
}

// In update:
Msg::OpenFile(path) => {
    ctx.state.tabs.push(path);
    ctx.state.active = ctx.state.tabs.len() - 1;
    Update::full()
}
Msg::CloseTab(idx) => {
    ctx.state.tabs.remove(idx);
    ctx.state.active = ctx.state.active.min(ctx.state.tabs.len().saturating_sub(1));
    Update::full()
}
Msg::ReorderTabs(e) => {
    ctx.state.tabs.swap(e.from, e.to);
    ctx.state.active = if ctx.state.active == e.from { e.to } else { ctx.state.active };
    Update::full()
}

11. Markdown Editor + Live Preview ​

Use TextArea for editing and DocumentView for display transforms. Keep the source in one state field and feed both widgets from the same value.

rust
HStack::new()
    .gap(1)
    .child(
        TextArea::new(ctx.state.markdown.clone())
            .language("markdown")
            .on_change(ctx.link().callback(|ev| Msg::SetMarkdown(ev.value))),
    )
    .child(
        DocumentView::new(ctx.state.markdown.clone())
            .markdown()          // requires feature "markdown"
            .line_numbers(true)
            .wrap(true),
    )

For scroll-sync, emit source-line metrics from editor/preview and set DocumentView::scroll_to_source_line(...).

11a. TextArea inline sentinels (@mentions, file tokens) ​

Store app data on TextAreaSentinel::payload(your_type) and rely on SentinelId + on_sentinel_event for deletes instead of mirroring index → metadata maps. Use TextAreaSnapshot::capture / apply for stash–restore. See widgets/input.md.

12. Choosing the Right Container ​

NeedUseDon't use
Stack children verticallyVStackFrame (unless you need border/labels)
Stack children horizontallyHStackFrame (unless you need border/labels)
Border + header/footer labelsFramebare VStack with manual border
Overlay children on top of each otherZStack-
Center a single childCenterVStack with align + justify hacks
Scrollable contentScrollView-
Resizable split panesSplitter-

Frame is for visual chrome, not layout. Use Frame only when you need one or more of: border, header/footer labels, tab titles, join_frame, clipping, or FrameDecoration. If you just need to group children, use VStack or HStack directly.

Anti-Patterns (Common Mistakes) ​

❌ Returning Update::full() when nothing changed ​

rust
// BAD: triggers unnecessary re-render
Msg::SomeEvent => Update::full()

// GOOD: only redraw if state actually changed
Msg::SomeEvent => {
    if self.process(msg) {
        Update::full()
    } else {
        Update::none()
    }
}

This is especially expensive for high-frequency widget callbacks. Avoid full root rebuilds when callbacks only synchronize runtime metadata:

rust
// BAD: rebuilds the whole component tree on every wheel/drag event
Msg::ViewportChanged(event) => {
    ctx.state.scroll_offset = event.offset;
    Update::full()
}

// GOOD: the ScrollView already moved; just remember the settled offset
Msg::ViewportChanged(event) => {
    ctx.state.scroll_offset = event.offset;
    Update::none()
}

❌ Missing .key(...) on list items or dynamic children ​

rust
// BAD: reconciliation uses position - breaks on insert/remove
rsx! {
    VStack {
        for item in &items {
            ItemWidget { data: item.clone() }
        }
    }
}

// GOOD: stable key for each child
rsx! {
    VStack {
        for item in &items {
            ItemWidget { key: item.id.to_string(), data: item.clone() }
        }
    }
}

❌ Blocking the main thread in update() or view() ​

rust
// BAD: blocks the render loop
Msg::LoadData => {
    let data = std::fs::read_to_string("data.json").unwrap();  // BLOCKS
    ctx.state.data = data;
    Update::full()
}

// GOOD: use a command
Msg::LoadData => {
    Update::with_command(ctx.link().command(|link| {
        let data = std::fs::read_to_string("data.json").unwrap();
        link.send(Msg::DataLoaded(data));
    }))
}

❌ Using TaskPolicy::QueueAll for search/filter ​

rust
// BAD: stale results pile up; each keystroke queues a new search
ctx.link().command_keyed("search", TaskPolicy::QueueAll, ...)

// GOOD: drop old pending searches
ctx.link().command_keyed("search", TaskPolicy::LatestOnly, ...)

❌ Forgetting to drain screen.drain_responses() ​

TUI apps like fzf, vim, and lazygit query terminal capabilities. Not forwarding responses causes them to hang or malfunction.

rust
// BAD: missing response forwarding
screen.process_bytes(&bytes);
let snapshot = screen.render_snapshot();

// GOOD: always drain and forward
screen.process_bytes(&bytes);
if let Some(pty) = &self.pty {
    for response in screen.drain_responses() {
        let _ = pty.write(&response);
    }
}
let snapshot = screen.render_snapshot();

❌ Setting scroll offset before resize in inline mode ​

rust
// BAD: corrupts ratatui's internal cursor offset calculation
terminal.set_cursor_position((0, 0));  // before draw on resize
terminal.draw(...);

// GOOD: use backend_mut() for operations that must NOT touch ratatui state
terminal.backend_mut().execute(cursor_op)?;

❌ Missing PartialEq on Properties ​

Properties must implement Clone + PartialEq for reconciliation to work. Without PartialEq, props changes may not trigger on_props_changed.

rust
// BAD
#[derive(Clone)]
struct Props { value: String }

// GOOD
#[derive(Clone, PartialEq)]
struct Props { value: String }

❌ Accessing image clipboard without image feature ​

rust
// BAD: will not compile without feature "image"
use tui_lipan::ImageContent;  // Only available with feature "image"

// Check Cargo.toml: features = ["image"]

❌ Using Color::named() for precise contrast ​

rust
// BAD: Color::Gray varies between terminal palettes
Button::new("Click").focus_style(Style::new().bg(Color::Gray))

// GOOD: use explicit RGB for predictable contrast behavior
Button::new("Click").focus_style(Style::new().bg(Color::rgb(80, 80, 80)))

❌ Setting default values explicitly ​

Don't set properties that are already the default - it adds noise and signals misunderstanding of the framework. Common offenders:

rust
// BAD: explicit framework defaults add noise
Input::new(query.clone())
    .focusable(true)                   // interactive widgets are focusable by default

VStack::new()
    .width(Length::Flex(1))            // containers default to Flex(1)
    .height(Length::Flex(1))           // containers default to Flex(1)
    .align(Align::Start)              // Start is the default
    .justify(Justify::Start)          // Start is the default

App::new()
    .mouse(true)                      // true in fullscreen mode by default
    .contrast_policy(ContrastPolicy::Wcag)  // Wcag is the default

// GOOD: Let the theme provide the shared caret, or explicitly override it when needed
Input::new(query.clone())                    // inherits the active theme caret
Input::new(query.clone())
    .caret_shape(CaretShape::Bar)     // explicit per-input override

VStack::new()
    .align(Align::Center)             // Center is NOT the default - this IS meaningful

❌ Setting background color on every widget and style variant ​

Background color inherits from the nearest ancestor. Don't repeat it on every child or sub-style:

rust
// BAD: Repeating bg on every widget and sub-style
Frame::new()
    .style(Style::new().bg(Color::indexed(235)))
    .child(
        Input::new(query.clone())
            .style(Style::new().fg(Color::White).bg(Color::indexed(235)))
            .focus_style(Style::new().fg(Color::White).bg(Color::indexed(235)).bold())
    )
    .child(
        List::new()
            .items(items)
            .selection_style(Style::new().fg(Color::Cyan).bg(Color::indexed(235)))
    )

// GOOD: Set bg once on the parent; children inherit it.
// Only set bg when you want a DIFFERENT background.
Frame::new()
    .style(Style::new().bg(Color::indexed(235)))
    .child(
        Input::new(query.clone())
            .style(Style::new().fg(Color::White))
            .focus_style(Style::new().fg(Color::White).bold())
    )
    .child(
        List::new()
            .items(items)
            .selection_style(Style::new().fg(Color::Cyan).bold())
    )

See styling.md for the full style inheritance rules.

Note: Only bg inherits this way. fg does not inherit - each widget resolves its own foreground color independently.

❌ Wrapping containers in Frame unnecessarily ​

Frame is for visual chrome (border, header/footer labels, clipping). If you just need layout, use VStack/HStack directly:

rust
// BAD: Frame adds no value here - no border or labels used
Frame::new()
    .child(
        VStack::new()
            .child(Text::new("Hello"))
            .child(Button::new("Click"))
    )

// GOOD: VStack alone provides the same layout
VStack::new()
    .child(Text::new("Hello"))
    .child(Button::new("Click"))

// GOOD: Frame is justified when you use its features
Frame::new()
    .header_left("Settings")
    .border(true)
    .footer_right("v1.2")
    .child(
        VStack::new()
            .gap(1)
            .child(Text::new("Hello"))
            .child(Button::new("Click"))
    )

MPL-2.0

© Adam Mikołajczyk