21 releases (5 breaking)

0.6.0 Oct 25, 2024
0.5.0 Aug 12, 2024
0.4.4 Jul 25, 2024
0.2.3 Mar 12, 2024
0.2.1 Dec 31, 2023

#407 in Command-line interface

Download history 37/week @ 2024-08-19 107/week @ 2024-08-26 15/week @ 2024-09-02 1124/week @ 2024-09-09 537/week @ 2024-09-16 275/week @ 2024-09-23 949/week @ 2024-09-30 761/week @ 2024-10-07 656/week @ 2024-10-14 658/week @ 2024-10-21 496/week @ 2024-10-28 318/week @ 2024-11-04 344/week @ 2024-11-11 239/week @ 2024-11-18 302/week @ 2024-11-25 481/week @ 2024-12-02

1,396 downloads per month
Used in 6 crates (5 directly)

MIT/Apache

21KB
206 lines

tui-popup

Crates.io badge License badge Docs.rs badge Deps.rs badge Discord badge

A popup widget for Ratatui

The popup widget is a simple widget that renders a popup in the center of the screen.

Example

use ratatui::prelude::*;
use tui_popup::Popup;

fn render_popup(frame: &mut Frame) {
    let popup = Popup::new("tui-popup demo", "Press any key to exit")
       .style(Style::new().white().on_blue());
    frame.render_widget(&popup, frame.size());
}

demo

State

The widget supports storing the position of the popup in PopupState. This is experimental and the exact api for this will likely change.

use ratatui::prelude::*;
use tui_popup::Popup;

fn render_stateful_popup(frame: &mut Frame, popup_state: &mut PopupState) {
    let popup = Popup::new("tui-popup demo", "Press any key to exit")
       .style(Style::new().white().on_blue());
    frame.render_stateful_widget_ref(popup, frame.size(), popup_state);
}

fn move_up(popup_state: &mut PopupState) {
    popup_state.move_by(0, -1);
}

The popup can automatically handle being moved around by the mouse, by passing in the column and row of Mouse Up / Down / Drag events. The current implemntation of this checks whether the click is in the first row of the popup, otherwise ignores the event.

match event.read()? {
    Event::Mouse(event) => {
        match event.kind {
            event::MouseEventKind::Down(MouseButton::Left) => {
                popup_state.mouse_down(event.column, event.row)
            }
            event::MouseEventKind::Up(MouseButton::Left) => {
                popup_state.mouse_up(event.column, event.row);
            }
            event::MouseEventKind::Drag(MouseButton::Left) => {
                popup_state.mouse_drag(event.column, event.row);
            }
            _ => {}
        };
    }
    // -- snip --
}

state demo

The popup also supports rendering arbitrary widgets by implementing SizedWidgetRef (or wrapping them with the provided SizedWrapper). This makes it possible to support wrapping and scrolling in using a Paragraph widget, or scrolling any amount of widgets using tui-scrollview.

let lines: Text = (0..10).map(|i| Span::raw(format!("Line {}", i))).collect();
let paragraph = Paragraph::new(lines).scroll((scroll, 0));
let sized_paragraph = SizedWrapper {
    inner: paragraph,
    width: 21,
    height: 5,
};
let popup = Popup::new("scroll: ↑/↓ quit: Esc", sized_paragraph)
    .style(Style::new().white().on_blue());
frame.render_widget_ref(popup, area);

paragraph example

Features

  • automatically centers
  • automatically sizes to content
  • style popup
  • move the popup (using state)
  • handle mouse events for dragging
  • move to position
  • resize
  • set border set / style
  • add close button
  • add nicer styling of header etc.
  • configure text wrapping in body to conform to a specific size

License

Copyright (c) Josh McKinney

This project is licensed under either of:

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

See CONTRIBUTING.md.

Dependencies

~5–14MB
~169K SLoC