components

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 23, 2025 License: MIT Imports: 5 Imported by: 2

Documentation

Overview

Package components provides Bubble Tea integration for BubbleTable.

This package contains the high-level components that integrate the headless table core with the Bubble Tea framework, providing a complete TUI table experience with minimal setup required.

Core Types

  • Model: Main Bubble Tea model that implements the table interface
  • KeyBindings: Configurable key binding system
  • Builder: Fluent API for table configuration

Key Features

  • Complete Bubble Tea model implementation
  • Fluent builder API for easy configuration
  • Multiple key binding presets (Default, Vim, Emacs)
  • Custom callback system for user interactions
  • Built-in search mode with visual feedback
  • Automatic state management and persistence
  • Responsive design that adapts to terminal changes

Usage Examples

Basic table with struct data: 

type Employee struct {
    ID     int    `table:"ID,sortable,width:5"`
    Name   string `table:"Name,sortable,width:20"`
    Salary float64 `table:"Salary,sortable,width:12,format:currency"`
}

employees := []Employee{
    {1, "Alice Johnson", 75000},
    {2, "Bob Smith", 65000},
}

model := components.NewTable(employees).
    WithPageSize(10).
    WithSorting(true).
    WithSearch(true).
    WithTheme(renderer.DraculaTheme)

program := tea.NewProgram(model, tea.WithAltScreen())
if _, err := program.Run(); err != nil {
    log.Fatal(err)
}

Table with custom columns and callbacks: 

columns := []table.Column{
    *table.NewColumn("name", "Employee").WithWidth(25),
    *table.NewColumn("salary", "Salary").WithFormatter(table.CurrencyFormatter),
}

data := []map[string]interface{}{
    {"name": "Alice", "salary": 75000.0},
    {"name": "Bob", "salary": 65000.0},
}

model := components.NewTableWithColumns(data, columns).
    WithOnSelect(func(row map[string]interface{}) {
        fmt.Printf("Selected: %v\n", row)
    }).
    WithOnSort(func(column string, ascending bool) {
        fmt.Printf("Sorted by %s (asc: %t)\n", column, ascending)
    }).
    WithKeyBindings(components.VimKeyBindings())

Builder API

The fluent builder API allows for easy configuration: 

model := components.NewTable(data).
    WithTitle("Employee Directory").
    WithPageSize(15).
    WithSorting(true).
    WithSearch(true).
    WithTheme(renderer.MonokaiTheme).
    WithKeyBindings(components.VimKeyBindings()).
    WithOnSelect(handleSelection).
    WithOnSort(handleSort).
    WithOnSearch(handleSearch).
    WithOnRefresh(handleRefresh)

All builder methods return the model for chaining, and most are optional with sensible defaults.

Key Bindings

Three key binding presets are available:

Default key bindings:

  • ↑/↓: Navigate rows
  • ←/→: Navigate pages
  • Home/End: First/last page
  • 1-9: Sort by column number
  • /: Enter search mode
  • +/-: Adjust page size
  • ?: Toggle help
  • q/Esc: Quit

Vim key bindings (components.VimKeyBindings()):

  • j/k: Navigate rows
  • h/l: Navigate pages
  • gg/G: First/last page
  • 1-9: Sort by column number
  • /: Enter search mode
  • +/-: Adjust page size
  • ?: Toggle help
  • q/Esc: Quit

Emacs key bindings (components.EmacsKeyBindings()):

  • C-n/C-p: Navigate rows
  • C-f/C-b: Navigate pages
  • C-a/C-e: First/last page
  • 1-9: Sort by column number
  • C-s: Enter search mode
  • +/-: Adjust page size
  • C-h: Toggle help
  • C-g/Esc: Quit

Custom key bindings can be created by implementing the KeyBindings interface.

Callbacks

The component system provides callbacks for user interactions:

  • OnSelect: Called when a row is selected (Enter key)
  • OnSort: Called when column sorting changes
  • OnSearch: Called when search query changes
  • OnRefresh: Called when refresh is requested (F5)
  • OnPageChange: Called when page navigation occurs

Callbacks receive relevant data and can be used to integrate with external systems or trigger additional actions.

State Management

The Model maintains internal state including:

  • Current page and selected row
  • Search query and active search mode
  • Sort column and direction
  • Theme and key binding configuration
  • Window dimensions and layout

State is automatically managed and persists across renders and updates.

Search Mode

Search functionality includes:

  • Real-time filtering as user types
  • Case-insensitive search across all searchable columns
  • Visual indication of search mode
  • Escape to exit search mode
  • Automatic pagination adjustment for filtered results

Integration

The components integrate seamlessly with Bubble Tea applications: 

type AppModel struct {
    table components.Model
    // ... other components
}

func (m AppModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    var cmd tea.Cmd
    m.table, cmd = m.table.Update(msg)
    // ... handle other updates
    return m, cmd
}

func (m AppModel) View() string {
    return lipgloss.JoinVertical(
        lipgloss.Left,
        "My Application",
        m.table.View(),
        // ... other views
    )
}

Performance

The component layer is optimized for interactive use:

  • Efficient event handling and state updates
  • Minimal re-rendering on state changes
  • Responsive keyboard input processing
  • Smooth pagination and scrolling
  • Optimized search filtering

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type KeyBindings 

type KeyBindings struct {
	Up           []string
	Down         []string
	Left         []string
	Right        []string
	PageUp       []string
	PageDown     []string
	Home         []string
	End          []string
	Search       []string
	Quit         []string
	Help         []string
	Refresh      []string
	PageSizeUp   []string
	PageSizeDown []string
	ResetPage    []string
	ClearSort    []string
	Sort1        []string
	Sort2        []string
	Sort3        []string
	Sort4        []string
	Sort5        []string
	Sort6        []string
	Sort7        []string
	Sort8        []string
	Sort9        []string
}

KeyBindings represents configurable key bindings for table interactions

func DefaultKeyBindings 

func DefaultKeyBindings() *KeyBindings

DefaultKeyBindings returns the default key bindings

func EmacsKeyBindings 

func EmacsKeyBindings() *KeyBindings

EmacsKeyBindings returns Emacs-style key bindings

func VimKeyBindings 

func VimKeyBindings() *KeyBindings

VimKeyBindings returns Vim-style key bindings

func (*KeyBindings) GetSortColumn 

func (kb *KeyBindings) GetSortColumn(key string) int

GetSortColumn returns the column index for sorting, or -1 if not a sort key

func (*KeyBindings) IsClearSort 

func (kb *KeyBindings) IsClearSort(key string) bool

IsClearSort checks if the key clears sorting

func (*KeyBindings) IsDown 

func (kb *KeyBindings) IsDown(key string) bool

IsDown checks if the key is a down navigation key

func (*KeyBindings) IsEnd 

func (kb *KeyBindings) IsEnd(key string) bool

IsEnd checks if the key is an end key

func (*KeyBindings) IsHelp 

func (kb *KeyBindings) IsHelp(key string) bool

IsHelp checks if the key is a help key

func (*KeyBindings) IsHome 

func (kb *KeyBindings) IsHome(key string) bool

IsHome checks if the key is a home key

func (*KeyBindings) IsLeft 

func (kb *KeyBindings) IsLeft(key string) bool

IsLeft checks if the key is a left navigation key

func (*KeyBindings) IsPageDown 

func (kb *KeyBindings) IsPageDown(key string) bool

IsPageDown checks if the key is a page down key

func (*KeyBindings) IsPageSizeDown 

func (kb *KeyBindings) IsPageSizeDown(key string) bool

IsPageSizeDown checks if the key decreases page size

func (*KeyBindings) IsPageSizeUp 

func (kb *KeyBindings) IsPageSizeUp(key string) bool

IsPageSizeUp checks if the key increases page size

func (*KeyBindings) IsPageUp 

func (kb *KeyBindings) IsPageUp(key string) bool

IsPageUp checks if the key is a page up key

func (*KeyBindings) IsQuit 

func (kb *KeyBindings) IsQuit(key string) bool

IsQuit checks if the key is a quit key

func (*KeyBindings) IsRefresh 

func (kb *KeyBindings) IsRefresh(key string) bool

IsRefresh checks if the key is a refresh key

func (*KeyBindings) IsResetPage 

func (kb *KeyBindings) IsResetPage(key string) bool

IsResetPage checks if the key resets to optimal page size

func (*KeyBindings) IsRight 

func (kb *KeyBindings) IsRight(key string) bool

IsRight checks if the key is a right navigation key

func (*KeyBindings) IsSearch 

func (kb *KeyBindings) IsSearch(key string) bool

IsSearch checks if the key is a search key

func (*KeyBindings) IsUp 

func (kb *KeyBindings) IsUp(key string) bool

IsUp checks if the key is an up navigation key

type TableModel 

type TableModel struct {
	// contains filtered or unexported fields
}

TableModel represents the Bubble Tea model for the table component

func NewTable 

func NewTable[T any](data []T) *TableModel

NewTable creates a new table model from a slice of data

func NewTableFromInterface 

func NewTableFromInterface(data []interface{}) *TableModel

NewTableFromInterface creates a new table model from a slice of interface{}

func NewTableWithColumns 

func NewTableWithColumns(data []map[string]interface{}, columns []table.Column) *TableModel

NewTableWithColumns creates a new table model with predefined columns

func (*TableModel) GetCurrentTable 

func (m *TableModel) GetCurrentTable() *table.Table

GetCurrentTable returns the current effective table (filtered or main)

func (*TableModel) GetSelectedRow 

func (m *TableModel) GetSelectedRow() (table.Row, bool)

GetSelectedRow returns the currently selected row

func (*TableModel) GetTable 

func (m *TableModel) GetTable() *table.Table

GetTable returns the underlying table

func (*TableModel) Init 

func (m *TableModel) Init() tea.Cmd

Init initializes the model

func (*TableModel) RefreshData 

func (m *TableModel) RefreshData(data interface{}) error

RefreshData refreshes the table with new data

func (*TableModel) SetData 

func (m *TableModel) SetData(data interface{}) error

SetData sets new data for the table

func (*TableModel) Update 

func (m *TableModel) Update(msg tea.Msg) (tea.Model, tea.Cmd)

Update handles messages and updates the model

func (*TableModel) View 

func (m *TableModel) View() string

View renders the table

func (*TableModel) WithKeyBindings 

func (m *TableModel) WithKeyBindings(bindings *KeyBindings) *TableModel

WithKeyBindings sets custom key bindings

func (*TableModel) WithOnRefresh 

func (m *TableModel) WithOnRefresh(callback func()) *TableModel

WithOnRefresh sets a callback for refresh requests

func (*TableModel) WithOnSearch 

func (m *TableModel) WithOnSearch(callback func(term string)) *TableModel

WithOnSearch sets a callback for search changes

func (*TableModel) WithOnSelect 

func (m *TableModel) WithOnSelect(callback func(row table.Row)) *TableModel

WithOnSelect sets a callback for row selection

func (*TableModel) WithOnSort 

func (m *TableModel) WithOnSort(callback func(columnIndex int, desc bool)) *TableModel

WithOnSort sets a callback for sorting changes

func (*TableModel) WithPageSize 

func (m *TableModel) WithPageSize(size int) *TableModel

WithPageSize sets the page size

func (*TableModel) WithSearch 

func (m *TableModel) WithSearch(enabled bool) *TableModel

WithSearch enables or disables search

func (*TableModel) WithSorting 

func (m *TableModel) WithSorting(enabled bool) *TableModel

WithSorting enables or disables sorting

func (*TableModel) WithTheme 

func (m *TableModel) WithTheme(theme *renderer.Theme) *TableModel

WithTheme sets the theme

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.