Struct Model

pub struct Model {
    pub columns: Vec<Column>,
    pub rows: Vec<Row>,
    pub selected: usize,
    pub width: i32,
    pub height: i32,
    pub keymap: TableKeyMap,
    pub styles: Styles,
    pub focus: bool,
    pub help: Model,
    /* private fields */
}

Interactive table model containing data, styling, navigation state, and a viewport for efficient rendering and scrolling.

Fields

columns: Vec<Column>

Column definitions controlling headers and widths.

rows: Vec<Row>

Row data; each row contains one string per column.

selected: usize

Index of the currently selected row (0-based).

width: i32

Rendered width of the table in characters.

height: i32

Rendered height of the table in lines.

keymap: TableKeyMap

Key bindings for navigation and movement.

styles: Styles

Styles used when rendering the table.

focus: bool

Whether this table currently has keyboard focus.

help: Model

Help model used to render key binding help.

Implementations

impl Model

pub fn new(columns: Vec<Column>) -> Self

Creates a new table with the given columns and sensible defaults.

Defaults: height 20, focused, empty rows, and default styles/keymap.

pub fn with_rows(self, rows: Vec<Row>) -> Self

Sets the table rows on construction and returns self for chaining.

pub fn set_width(&mut self, w: i32)

Sets the table width in characters and rebuilds the viewport content.

pub fn set_height(&mut self, h: i32)

Sets the table height in lines and rebuilds the viewport content.

pub fn add_row(&mut self, row: Row)

Appends a row to the table and refreshes the rendered content.

pub fn selected_row(&self) -> Option<&Row>

Returns a reference to the currently selected row, if any.

pub fn select_next(&mut self)

Moves the selection down by one row.

pub fn select_prev(&mut self)

Moves the selection up by one row.

pub fn view(&self) -> String

Renders the table as a string.

pub fn focus(&mut self)

Gives keyboard focus to the table.

pub fn blur(&mut self)

Removes keyboard focus from the table.

pub fn help_view(&self) -> String

Renders the help view for the table’s key bindings.

Trait Implementations

impl Clone for Model

fn clone(&self) -> Model

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Model

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

Formats the value using the given formatter.

impl KeyMap for Model

Help system integration for displaying table navigation keys.

This implementation provides the help system with information about the table’s key bindings, enabling automatic generation of help text that documents the available navigation commands.

fn short_help(&self) -> Vec<&Binding>

Returns the most commonly used key bindings for short help display.

This method provides a concise list of the most essential navigation keys that users need to know for basic table operation. It’s used when displaying compact help information.

Returns

A vector of key binding references for row and page navigation

Examples

use bubbletea_widgets::table::{Model, Column};
use bubbletea_widgets::help::KeyMap;

let table = Model::new(vec![Column::new("Data", 20)]);
let short_bindings = table.short_help();

// Returns bindings for: up, down, page up, page down
assert_eq!(short_bindings.len(), 4);

Help Content

The short help includes:

• Row Up: Move selection up one row
• Row Down: Move selection down one row
• Page Up: Move up one page of rows
• Page Down: Move down one page of rows

fn full_help(&self) -> Vec<Vec<&Binding>>

Returns all key bindings organized by category for full help display.

This method provides a comprehensive list of all available navigation keys, organized into logical groups for clear presentation in detailed help displays. Each group contains related navigation commands.

Returns

A vector of groups, where each group is a vector of related key bindings

Examples

use bubbletea_widgets::table::{Model, Column};
use bubbletea_widgets::help::KeyMap;

let table = Model::new(vec![Column::new("Data", 20)]);
let full_bindings = table.full_help();

// Returns 4 groups of key bindings
assert_eq!(full_bindings.len(), 4);

// First group: row navigation (up/down)
assert_eq!(full_bindings[0].len(), 2);

Help Organization

The full help is organized into these groups:

1. Row Navigation: Single row up/down movement
2. Page Navigation: Full page up/down scrolling
3. Half Page Navigation: Half page up/down movement
4. Jump Navigation: Go to start/end positions

Display Integration

This grouped format allows help displays to show related commands together with appropriate spacing and categorization for better user comprehension.

impl Model for Model

fn init() -> (Self, Option<Cmd>)

Creates a new empty table model for Bubble Tea applications.

This initialization method creates a table with no columns or data, suitable for applications that will configure the table structure after initialization. The table starts focused and ready to receive keyboard input.

Returns

A tuple containing the new table model and no initial command

Examples

use bubbletea_widgets::table::Model;
use bubbletea_rs::Model as BubbleTeaModel;

// This is typically called by the Bubble Tea framework
let (mut table, cmd) = Model::init();
assert_eq!(table.columns.len(), 0);
assert_eq!(table.rows.len(), 0);
assert!(cmd.is_none());

Note

Most applications will want to use Model::new(columns) directly instead of this init method, as it allows specifying the table structure immediately.

fn update(&mut self, msg: Msg) -> Option<Cmd>

Processes messages and updates table state with keyboard navigation.

This method handles all keyboard navigation for the table, including row selection, page scrolling, and jumping to start/end positions. It only processes messages when the table is focused, ensuring proper behavior in multi-component applications.

Arguments

• msg - The message to process, typically a KeyMsg for keyboard input

Returns

An optional Cmd that may need to be executed (currently always None)

Key Handling

The following keys are processed based on the table’s key map configuration:

• Row Navigation: Up/Down arrows, k/j keys
• Page Navigation: Page Up/Down, b/f keys
• Half Page: u/d keys for half-page scrolling
• Jump Navigation: Home/End, g/G keys for start/end

Examples

use bubbletea_widgets::table::{Model, Column};
use bubbletea_rs::{KeyMsg, Model as BubbleTeaModel};
use crossterm::event::{KeyCode, KeyModifiers};

let mut table = Model::new(vec![Column::new("Data", 20)]);

// Simulate down arrow key press
let key_msg = Box::new(KeyMsg {
    key: KeyCode::Down,
    modifiers: KeyModifiers::NONE,
});
let cmd = table.update(key_msg);
// Table selection moves down (if there are rows)

Focus Handling

If the table is not focused (self.focus == false), this method returns immediately without processing the message. This allows multiple components to coexist without interference.

Performance Optimization

After any navigation that changes the selection, the viewport content is automatically rebuilt to ensure the selected row remains visible and the display is updated correctly.

fn view(&self) -> String

Renders the table for display in a Bubble Tea application.

This method delegates to the table’s own view() method to generate the formatted string representation. It’s called by the Bubble Tea framework during the render cycle.

Returns

A multi-line string containing the formatted table with headers, data rows, selection highlighting, and applied styling

Examples

use bubbletea_widgets::table::{Model, Column, Row};
use bubbletea_rs::Model as BubbleTeaModel;

let mut table = Model::new(vec![Column::new("Name", 15)]);
table.add_row(Row::new(vec!["Alice".into()]));

let output = table.view();
// Contains formatted table ready for terminal display

Integration Pattern

This method is typically called from your application’s main view() method:

use bubbletea_widgets::table::Model as TableModel;
use bubbletea_rs::Model as BubbleTeaModel;

struct App {
    table: TableModel,
}

impl BubbleTeaModel for App {
     
    fn view(&self) -> String {
        format!("My Application\n\n{}", self.table.view())
    }
}