table

package
v0.12.1 Latest Latest
Warning

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

 Go to latest Published: May 28, 2022 License: MIT Imports: 10 Imported by: 89

Documentation

Overview

Package table contains a Bubble Tea component for an interactive and customizable table.

The simplest useful table can be created with table.New(...).WithRows(...). Row data should map to the column keys, as shown below. Note that extra data will simply not be shown, while missing data will be safely blank in the row's cell. 

const (
	// This is not necessary, but recommended to avoid typos
	columnKeyName  = "name"
	columnKeyCount = "count"
)

// Define the columns and how they appear
columns := []table.Column{
	table.NewColumn(columnKeyName, "Name", 10),
	table.NewColumn(columnKeyCount, "Count", 6),
}

// Define the data that will be in the table, mapping to the column keys
rows := []table.Row{
	table.NewRow(table.RowData{
		columnKeyName:  "Cheeseburger",
		columnKeyCount: 3,
	}),
	table.NewRow(table.RowData{
		columnKeyName:  "Fries",
		columnKeyCount: 2,
	}),
}

// Create the table
tbl := table.New(columns).WithRows(rows)

// Use it like any Bubble Tea component in your view
tbl.View()

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Border added in v0.2.0 

type Border struct {
	Top         string
	Left        string
	Right       string
	Bottom      string
	TopRight    string
	TopLeft     string
	BottomRight string
	BottomLeft  string

	TopJunction    string
	LeftJunction   string
	RightJunction  string
	BottomJunction string

	InnerJunction string

	InnerDivider string
	// contains filtered or unexported fields
}

Border defines the borders in and around the table.

type Column added in v0.3.0 

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

Column is a column in the table.

func NewColumn added in v0.3.0 

func NewColumn(key, title string, width int) Column

NewColumn creates a new fixed-width column with the given information.

func NewFlexColumn added in v0.8.0 

func NewFlexColumn(key, title string, flexFactor int) Column

NewFlexColumn creates a new flexible width column that tries to fill in the total table width. If multiple flex columns exist, each will measure against each other depending on their flexFactor. For example, if both have a flexFactor of 1, they will have equal width. If one has a flexFactor of 1 and the other has a flexFactor of 3, the second will be 3 times larger than the first. You must use WithTargetWidth if you have any flex columns, so that the table knows how much width it should fill.

func (Column) WithFiltered added in v0.7.0 

func (c Column) WithFiltered(filterable bool) Column

WithFiltered sets whether the column should be considered for filtering (true) or not (false).

func (Column) WithStyle added in v0.5.0 

func (c Column) WithStyle(style lipgloss.Style) Column

WithStyle applies a style to the column as a whole.

type KeyMap added in v0.4.0 

type KeyMap struct {
	RowDown key.Binding
	RowUp   key.Binding

	RowSelectToggle key.Binding

	PageDown  key.Binding
	PageUp    key.Binding
	PageFirst key.Binding
	PageLast  key.Binding

	// Filter allows the user to start typing and filter the rows.
	Filter key.Binding

	// FilterBlur is the key that stops the user's input from typing into the filter.
	FilterBlur key.Binding

	// FilterClear will clear the filter while it's blurred.
	FilterClear key.Binding
}

KeyMap defines the keybindings for the table when it's focused.

func DefaultKeyMap added in v0.4.0 

func DefaultKeyMap() KeyMap

DefaultKeyMap returns a set of sensible defaults for controlling a focused table.

type Model 

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

Model is the main table model. Create using New().

func New 

func New(columns []Column) Model

New creates a new table ready for further modifications.

func (Model) Border added in v0.2.0 

func (m Model) Border(border Border) Model

Border uses the given border components to render the table.

func (Model) BorderDefault added in v0.2.0 

func (m Model) BorderDefault() Model

BorderDefault uses the basic square border, useful to reset the border if it was changed somehow.

func (*Model) CurrentPage added in v0.5.0 

func (m *Model) CurrentPage() int

CurrentPage returns the current page that the table is on, starting from an index of 1.

func (Model) Filtered added in v0.7.0 

func (m Model) Filtered(filtered bool) Model

Filtered allows the table to show rows that match the filter.

func (Model) Focused 

func (m Model) Focused(focused bool) Model

Focused allows the table to show highlighted rows and take in controls of up/down/space/etc to let the user navigate the table and interact with it.

func (*Model) GetCanFilter added in v0.11.1 

func (m *Model) GetCanFilter() bool

GetCanFilter returns true if the table enables filtering at all. This does not say whether a filter is currently active, only that the feature is enabled.

func (*Model) GetColumnSorting added in v0.11.1 

func (m *Model) GetColumnSorting() []SortColumn

GetColumnSorting returns the current sorting rules for the table as a list of SortColumns, which are applied from first to last. This means that data will be grouped by the later elements in the list. The returned list is a copy and modifications will have no effect.

func (*Model) GetCurrentFilter added in v0.11.1 

func (m *Model) GetCurrentFilter() string

GetCurrentFilter returns the current filter text being applied, or an empty string if none is applied.

func (*Model) GetIsFilterActive added in v0.11.1 

func (m *Model) GetIsFilterActive() bool

GetIsFilterActive returns true if the table is currently being filtered. This does not say whether the table CAN be filtered, only whether or not a filter is actually currently being applied.

func (Model) GetVisibleRows added in v0.7.0 

func (m Model) GetVisibleRows() []Row

GetVisibleRows return sorted and filtered rows.

func (Model) HeaderStyle 

func (m Model) HeaderStyle(style lipgloss.Style) Model

HeaderStyle sets the style to apply to the header text, such as color or bold.

func (Model) HighlightStyle 

func (m Model) HighlightStyle(style lipgloss.Style) Model

HighlightStyle sets a custom style to use when the row is being highlighted by the cursor.

func (Model) HighlightedRow 

func (m Model) HighlightedRow() Row

HighlightedRow returns the full Row that's currently highlighted by the user.

func (Model) Init 

func (m Model) Init() tea.Cmd

Init initializes the table per the Bubble Tea architecture.

func (Model) KeyMap added in v0.4.0 

func (m Model) KeyMap() KeyMap

KeyMap returns a copy of the current key map in use.

func (*Model) MaxPages added in v0.5.0 

func (m *Model) MaxPages() int

MaxPages returns the maximum number of pages that are visible.

func (Model) PageDown added in v0.9.0 

func (m Model) PageDown() Model

PageDown goes to the next page of a paginated table, wrapping to the first page if the table is already on the last page.

func (Model) PageFirst added in v0.9.0 

func (m Model) PageFirst() Model

PageFirst goes to the first page of a paginated table.

func (Model) PageLast added in v0.9.0 

func (m Model) PageLast() Model

PageLast goes to the last page of a paginated table.

func (*Model) PageSize added in v0.5.0 

func (m *Model) PageSize() int

PageSize returns the current page size for the table, or 0 if there is no pagination enabled.

func (Model) PageUp added in v0.9.0 

func (m Model) PageUp() Model

PageUp goes to the previous page of a paginated table, wrapping to the last page if the table is already on the first page.

func (Model) SelectableRows 

func (m Model) SelectableRows(selectable bool) Model

SelectableRows sets whether or not rows are selectable. If set, adds a column in the front that acts as a checkbox and responds to controls if Focused.

func (Model) SelectedRows 

func (m Model) SelectedRows() []Row

SelectedRows returns all rows that have been set as selected by the user.

func (Model) SortByAsc added in v0.6.0 

func (m Model) SortByAsc(columnKey string) Model

SortByAsc sets the main sorting column to the given key, in ascending order. If a previous sort was used, it is replaced by the given column each time this function is called. Values are sorted as numbers if possible, or just as simple string comparisons if not numbers.

func (Model) SortByDesc added in v0.6.0 

func (m Model) SortByDesc(columnKey string) Model

SortByDesc sets the main sorting column to the given key, in descending order. If a previous sort was used, it is replaced by the given column each time this function is called. Values are sorted as numbers if possible, or just as simple string comparisons if not numbers.

func (Model) StartFilterTyping added in v0.7.0 

func (m Model) StartFilterTyping() Model

StartFilterTyping focuses the text input to allow user typing to filter.

func (Model) ThenSortByAsc added in v0.6.0 

func (m Model) ThenSortByAsc(columnKey string) Model

ThenSortByAsc provides a secondary sort after the first, in ascending order. Can be chained multiple times, applying to smaller subgroups each time.

func (Model) ThenSortByDesc added in v0.6.0 

func (m Model) ThenSortByDesc(columnKey string) Model

ThenSortByDesc provides a secondary sort after the first, in descending order. Can be chained multiple times, applying to smaller subgroups each time.

func (*Model) TotalRows added in v0.5.0 

func (m *Model) TotalRows() int

TotalRows returns the current total row count of the table. If the table is paginated, this is the total number of rows across all pages.

func (Model) Update 

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

Update responds to input from the user or other messages from Bubble Tea.

func (Model) View 

func (m Model) View() string

View renders the table. It does not end in a newline, so that it can be composed with other elements more consistently.

func (*Model) VisibleIndices added in v0.5.0 

func (m *Model) VisibleIndices() (start, end int)

VisibleIndices returns the current visible rows by their 0 based index. Useful for custom pagination footers.

func (Model) WithBaseStyle added in v0.6.3 

func (m Model) WithBaseStyle(style lipgloss.Style) Model

WithBaseStyle applies a base style as the default for everything in the table. This is useful for border colors, default alignment, default color, etc.

func (Model) WithColumns added in v0.10.0 

func (m Model) WithColumns(columns []Column) Model

WithColumns sets the visible columns for the table, so that columns can be added/removed/resized or headers rewritten.

func (Model) WithCurrentPage added in v0.9.0 

func (m Model) WithCurrentPage(currentPage int) Model

WithCurrentPage sets the current page (1 as the first page) of a paginated table, bounded to the total number of pages. The current selected row will be set to the top row of the page if the page changed.

func (Model) WithFilterInput added in v0.12.0 

func (m Model) WithFilterInput(input textinput.Model) Model

WithFilterInput makes the table use the provided text input bubble for filtering rather than using the built-in default. This allows for external text input controls to be used.

func (Model) WithFooterVisibility added in v0.12.0 

func (m Model) WithFooterVisibility(visibility bool) Model

WithFooterVisibility sets the visibility of the footer.

func (Model) WithHighlightedRow added in v0.8.1 

func (m Model) WithHighlightedRow(index int) Model

WithHighlightedRow sets the highlighted row to the given index.

func (Model) WithKeyMap added in v0.4.0 

func (m Model) WithKeyMap(keyMap KeyMap) Model

WithKeyMap sets the key map to use for controls when focused.

func (Model) WithNoPagination added in v0.5.0 

func (m Model) WithNoPagination() Model

WithNoPagination disable pagination in the table.

func (Model) WithPageSize added in v0.5.0 

func (m Model) WithPageSize(pageSize int) Model

WithPageSize enables pagination using the given page size. This can be called again at any point to resize the height of the table.

func (Model) WithRows 

func (m Model) WithRows(rows []Row) Model

WithRows sets the rows to show as data in the table.

func (Model) WithSelectedText added in v0.6.0 

func (m Model) WithSelectedText(unselected, selected string) Model

WithSelectedText describes what text to show when selectable rows are enabled. The selectable column header will use the selected text string.

func (Model) WithStaticFooter added in v0.4.0 

func (m Model) WithStaticFooter(footer string) Model

WithStaticFooter adds a footer that only displays the given text.

func (Model) WithTargetWidth added in v0.8.0 

func (m Model) WithTargetWidth(totalWidth int) Model

WithTargetWidth sets the total target width of the table, including borders. This only takes effect when using flex columns. When using flex columns, columns will stretch to fill out to the total width given here.

type Row 

type Row struct {
	Style lipgloss.Style
	Data  RowData
	// contains filtered or unexported fields
}

Row represents a row in the table with some data keyed to the table columns> Can have a style applied to it such as color/bold. Create using NewRow().

func NewRow 

func NewRow(data RowData) Row

NewRow creates a new row and copies the given row data.

func (Row) WithStyle 

func (r Row) WithStyle(style lipgloss.Style) Row

WithStyle uses the given style for the text in the row.

type RowData 

type RowData map[string]interface{}

RowData is a map of string column keys to interface{} data. Data with a key that matches a column key will be displayed. Data with a key that does not match a column key will not be displayed, but will remain attached to the Row. This can be useful for attaching hidden metadata for future reference when retrieving rows.

type SortColumn added in v0.11.1 

type SortColumn struct {
	ColumnKey string
	Direction SortDirection
}

SortColumn describes which column should be sorted and how.

type SortDirection added in v0.11.1 

type SortDirection int

SortDirection indicates whether a column should sort by ascending or descending. 

const (
	// SortDirectionAsc indicates the column should be in ascending order.
	SortDirectionAsc SortDirection = iota

	// SortDirectionDesc indicates the column should be in descending order.
	SortDirectionDesc
)

type StyledCell added in v0.5.0 

type StyledCell struct {
	Data  interface{}
	Style lipgloss.Style
}

StyledCell represents a cell in the table that has a particular style applied. The cell style takes highest precedence and will overwrite more general styles from the row, column, or table as a whole. This style should be generally limited to colors, font style, and alignments - spacing style such as margin will break the table format.

func NewStyledCell added in v0.5.0 

func NewStyledCell(data interface{}, style lipgloss.Style) StyledCell

NewStyledCell creates an entry that can be set in the row data and show as styled with the given style.

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.