widget

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Apr 6, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DefaultCellRenderer 

func DefaultCellRenderer(ds TableDataSource, row, col int, selected bool, width int, styles TableStyles) string

DefaultCellRenderer is the built-in cell renderer used when ColumnDef.Renderer is nil. It applies styles.Selected (with full width background) for selected rows, and styles.Cell otherwise.

func LayoutHorizontal 

func LayoutHorizontal(children []Component, x, y, availW, availH, spacing int)

LayoutHorizontal arranges children left-to-right within available space. Each child gets availH (unless it has a preferred height). Each child gets its preferred width, or its natural rendered width if no preference. No flexing — remaining space to the right is unused.

func LayoutTCB 

func LayoutTCB(top, center, bottom Component, x, y, availW, availH int)

LayoutTCB arranges three slots: top, center, bottom. Top and Bottom get their preferred/natural height. Center gets ALL remaining height — this is the only layout that stretches. All slots get availW (unless they have a preferred width). Nil slots use no space.

func LayoutVertical 

func LayoutVertical(children []Component, x, y, availW, availH int)

LayoutVertical arranges children top-to-bottom within available space. Each child gets availW (unless it has a preferred width). Each child gets its preferred height, or its natural rendered height if no preference. No flexing — remaining space below the last child is unused.

func PrepareCell 

func PrepareCell(ds TableDataSource, row, col, width int) string

PrepareCell returns the cell value truncated to width, ready for styling. Use this in custom renderers to prevent lipgloss.Width() from wrapping long text into multiple lines.

Types

type Alignment 

type Alignment int

Alignment controls horizontal alignment within a component's width. 

const (
	AlignLeft Alignment = iota
	AlignCenter
	AlignRight
)

type BaseComponent 

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

BaseComponent provides common fields and methods embedded by all concrete components.

func NewBaseComponent 

func NewBaseComponent(id string) *BaseComponent

NewBaseComponent creates a BaseComponent with sensible defaults.

func (*BaseComponent) Active 

func (bc *BaseComponent) Active() bool

Active returns true if this component is enabled and its parent (if any) is also active.

func (*BaseComponent) Alignment 

func (bc *BaseComponent) Alignment() Alignment

Alignment returns the current horizontal alignment.

func (*BaseComponent) Enabled 

func (bc *BaseComponent) Enabled() bool

func (*BaseComponent) Focusable 

func (bc *BaseComponent) Focusable() bool

func (*BaseComponent) Focused 

func (bc *BaseComponent) Focused() bool

func (*BaseComponent) HandleEvent 

func (bc *BaseComponent) HandleEvent(event Event) (tea.Cmd, bool)

HandleEvent default: not consumed, bubble to parent.

func (*BaseComponent) ID 

func (bc *BaseComponent) ID() string

func (*BaseComponent) KeyBindings 

func (bc *BaseComponent) KeyBindings() []key.Binding

func (*BaseComponent) Parent 

func (bc *BaseComponent) Parent() Container

func (*BaseComponent) Position 

func (bc *BaseComponent) Position() (int, int)

func (*BaseComponent) PreferredHeight 

func (bc *BaseComponent) PreferredHeight() int

func (*BaseComponent) PreferredWidth 

func (bc *BaseComponent) PreferredWidth() int

func (*BaseComponent) RegisterKeyBinding 

func (bc *BaseComponent) RegisterKeyBinding(keys, description string, action func() tea.Cmd)

RegisterKeyBinding registers a global key binding with its action on this component. keys is the key combo (e.g. "ctrl+q"). description is the help text (e.g. "Quit"). Pass empty description to hide from help/hints.

func (*BaseComponent) RemoveKeyBinding 

func (bc *BaseComponent) RemoveKeyBinding(binding key.Binding)

RemoveKeyBinding removes a previously registered key binding by matching its key(s). No-op if the binding is not found.

func (*BaseComponent) RenderInSize 

func (bc *BaseComponent) RenderInSize(content string) string

RenderInSize pads content to fill the component's stored width and height using its alignment. MaxWidth prevents wrapping — content is truncated if too wide. Components must render at their allocated size.

func (*BaseComponent) ResolveKeyBinding 

func (bc *BaseComponent) ResolveKeyBinding(msg tea.KeyMsg) (func() tea.Cmd, bool)

ResolveKeyBinding checks if the key message matches any registered binding. Returns the action and true if a match is found.

func (*BaseComponent) SetAlignment 

func (bc *BaseComponent) SetAlignment(a Alignment)

SetAlignment sets the horizontal alignment used by RenderInSize.

func (*BaseComponent) SetEnabled 

func (bc *BaseComponent) SetEnabled(v bool)

func (*BaseComponent) SetFocused 

func (bc *BaseComponent) SetFocused(v bool) tea.Cmd

func (*BaseComponent) SetParent 

func (bc *BaseComponent) SetParent(p Container)

func (*BaseComponent) SetPosition 

func (bc *BaseComponent) SetPosition(x, y int)

func (*BaseComponent) SetPreferredHeight 

func (bc *BaseComponent) SetPreferredHeight(h int)

func (*BaseComponent) SetPreferredWidth 

func (bc *BaseComponent) SetPreferredWidth(w int)

func (*BaseComponent) SetSize 

func (bc *BaseComponent) SetSize(w, h int)

func (*BaseComponent) SetVisible 

func (bc *BaseComponent) SetVisible(v bool)

func (*BaseComponent) Size 

func (bc *BaseComponent) Size() (int, int)

func (*BaseComponent) View 

func (bc *BaseComponent) View() string

func (*BaseComponent) Visible 

func (bc *BaseComponent) Visible() bool

type BaseContainer 

type BaseContainer struct {
	BaseComponent
	// contains filtered or unexported fields
}

BaseContainer is a component composed of other components.

func NewBaseContainer 

func NewBaseContainer(id string, self Container) *BaseContainer

NewBaseContainer creates a BaseContainer with sensible defaults. If self is non-nil it is used as the parent reference for AddChild; otherwise the BaseContainer itself is used (useful in tests).

func (*BaseContainer) AddChild 

func (bc *BaseContainer) AddChild(child Component)

AddChild appends a child component and sets its parent to bc.self.

func (*BaseContainer) Children 

func (bc *BaseContainer) Children() []Component

Children returns the child components.

func (*BaseContainer) Focusable 

func (bc *BaseContainer) Focusable() bool

Focusable returns false; containers do not receive focus directly.

func (*BaseContainer) InnerFocused 

func (bc *BaseContainer) InnerFocused() bool

InnerFocused returns true if any descendant has focus.

func (*BaseContainer) View 

func (bc *BaseContainer) View() string

View returns an empty string; concrete containers override with their layout.

type BorderConfig 

type BorderConfig struct {
	Type        BorderType
	Color       lipgloss.Color // border color when no inner focus
	ActiveColor lipgloss.Color // border color when inner focused
	Padding     int            // horizontal padding inside border (columns per side)
}

BorderConfig defines the border appearance for a Panel.

func DefaultBorder 

func DefaultBorder() BorderConfig

DefaultBorder returns the default border configuration.

func SingleLineBorder 

func SingleLineBorder(color, activeColor string) BorderConfig

SingleLineBorder creates a BorderConfig with rounded border style.

func (BorderConfig) ChromeHeight 

func (bc BorderConfig) ChromeHeight() int

ChromeHeight returns the total vertical chrome (border) in rows.

func (BorderConfig) ChromeWidth 

func (bc BorderConfig) ChromeWidth() int

ChromeWidth returns the total horizontal chrome (border + padding) in columns.

func (BorderConfig) HasBorder 

func (bc BorderConfig) HasBorder() bool

HasBorder returns true if the border type is not NoBorder.

func (BorderConfig) Style 

func (bc BorderConfig) Style(focused bool) lipgloss.Style

Style returns the lipgloss style for the border in the given focus state.

type BorderType 

type BorderType int

BorderType defines the visual style of a panel's border. 

const (
	NoBorder      BorderType = iota // no border (default)
	RoundedBorder                   // rounded corners
)

type Button 

type Button struct {
	FocusableComponent
	// contains filtered or unexported fields
}

Button is a focusable action button component.

func NewButton 

func NewButton(id, label string, styles ButtonStyles) *Button

NewButton creates a new Button with the given ID, label, and styles.

func (*Button) BindDefaultActionToKey 

func (b *Button) BindDefaultActionToKey(keys string, description ...string)

BindDefaultActionToKey registers a global key binding that triggers the button's default action (onPress).

func (*Button) HandleEvent 

func (b *Button) HandleEvent(event Event) (tea.Cmd, bool)

HandleEvent handles high-level events. MouseClick fires onPress.

func (*Button) OnPress 

func (b *Button) OnPress(fn func() tea.Cmd)

OnPress sets the callback invoked when the button is pressed.

func (*Button) Update 

func (b *Button) Update(msg tea.KeyMsg) (tea.Cmd, bool)

Update handles key input. Space and enter trigger the onPress callback.

func (*Button) View 

func (b *Button) View() string

View renders the button label with the appropriate style for its state.

type ButtonStyles 

type ButtonStyles struct {
	Normal  lipgloss.Style
	Focused lipgloss.Style
}

ButtonStyles defines the styles used by a Button in different states.

func DefaultButtonStyles 

func DefaultButtonStyles() ButtonStyles

DefaultButtonStyles returns a ButtonStyles with sensible defaults.

func DefaultPopupButtonStyles 

func DefaultPopupButtonStyles() ButtonStyles

DefaultPopupButtonStyles returns a ButtonStyles with defaults for popup buttons.

type Card 

type Card struct {
	BaseComponent
	// contains filtered or unexported fields
}

Card is a non-focusable bordered display component showing a title and value.

func NewCard 

func NewCard(id, title, value string, styles CardStyles) *Card

NewCard creates a new Card with the given ID, title, value, and styles.

func (*Card) SetAlert 

func (c *Card) SetAlert(alert bool)

SetAlert sets whether the card value should be rendered with the alert style.

func (*Card) SetValue 

func (c *Card) SetValue(value string)

SetValue updates the card's displayed value.

func (*Card) Value 

func (c *Card) Value() string

Value returns the card's current value.

func (*Card) View 

func (c *Card) View() string

View renders a bordered box with title on the first line and value on the second.

type CardStyles 

type CardStyles struct {
	Border lipgloss.Style
	Title  lipgloss.Style
	Value  lipgloss.Style
	Alert  lipgloss.Style // for values that exceed thresholds
}

CardStyles defines the styles used by a Card component.

func DefaultCardStyles 

func DefaultCardStyles() CardStyles

DefaultCardStyles returns a CardStyles with sensible defaults.

type CellRenderer 

type CellRenderer func(ds TableDataSource, row, col int, selected bool, width int, styles TableStyles) string

CellRenderer renders a single table cell. The renderer receives the data source (for cross-column lookups), position, selection state, the resolved cell width, and the table's styles. It returns a fully styled string. Use PrepareCell to get a truncated value safe for single-line rendering.

type CheckboxItem 

type CheckboxItem struct {
	Label   string
	Value   string
	Checked bool
	IsGroup bool
}

CheckboxItem represents a single item in a CheckboxList.

type CheckboxList 

type CheckboxList struct {
	FocusableComponent
	// contains filtered or unexported fields
}

CheckboxList is a focusable list of checkable items.

func NewCheckboxList 

func NewCheckboxList(id string, items []CheckboxItem, styles CheckboxListStyles) *CheckboxList

NewCheckboxList creates a new CheckboxList with the given ID, items, and styles.

func (*CheckboxList) BindDefaultActionToKey 

func (cl *CheckboxList) BindDefaultActionToKey(keys string, description ...string)

BindDefaultActionToKey registers a global key binding that triggers the checkbox's default action (toggle the item at cursor).

func (*CheckboxList) Cursor 

func (cl *CheckboxList) Cursor() int

Cursor returns the current cursor position.

func (*CheckboxList) HandleEvent 

func (cl *CheckboxList) HandleEvent(event Event) (tea.Cmd, bool)

HandleEvent handles high-level events. MouseClick toggles cursor item.

func (*CheckboxList) Items 

func (cl *CheckboxList) Items() []CheckboxItem

Items returns the current items.

func (*CheckboxList) OnChange 

func (cl *CheckboxList) OnChange(fn func([]CheckboxItem) tea.Cmd)

OnChange sets the callback invoked when an item is toggled.

func (*CheckboxList) Selected 

func (cl *CheckboxList) Selected() []string

Selected returns the values of all checked items.

func (*CheckboxList) Update 

func (cl *CheckboxList) Update(msg tea.KeyMsg) (tea.Cmd, bool)

Update handles key input for navigation and toggling.

func (*CheckboxList) View 

func (cl *CheckboxList) View() string

View renders the checkbox list.

type CheckboxListStyles 

type CheckboxListStyles struct {
	Cursor    lipgloss.Style // "> " marker on current item
	Checked   lipgloss.Style // "[x] " checked indicator
	Unchecked lipgloss.Style // "[ ] " unchecked indicator
	Item      lipgloss.Style // normal item label
	Group     lipgloss.Style // group item label
	Dim       lipgloss.Style // non-cursor items prefix ("  ")
}

CheckboxListStyles defines the styles used by a CheckboxList.

func DefaultCheckboxListStyles 

func DefaultCheckboxListStyles() CheckboxListStyles

DefaultCheckboxListStyles returns a CheckboxListStyles with sensible defaults.

type ColumnDef 

type ColumnDef struct {
	Title    string
	Width    int          // fixed width; 0 = take remaining space
	Renderer CellRenderer // nil = default renderer
}

ColumnDef defines a single column in the table.

type Component 

type Component interface {
	ID() string
	View() string
	SetSize(w, h int)
	Size() (w, h int)
	SetPosition(x, y int)
	Position() (x, y int)
	Visible() bool
	SetVisible(bool)
	Enabled() bool
	SetEnabled(bool)
	Active() bool
	Focusable() bool
	Focused() bool
	SetFocused(bool) tea.Cmd
	Parent() Container
	SetParent(Container)
	KeyBindings() []key.Binding
	RegisterKeyBinding(keys, description string, action func() tea.Cmd)
	ResolveKeyBinding(tea.KeyMsg) (func() tea.Cmd, bool)
	// HandleEvent receives high-level UI events. If not consumed (returns false),
	// the base implementation bubbles the event up to the parent.
	HandleEvent(event Event) (tea.Cmd, bool)
	PreferredWidth() int
	PreferredHeight() int
	SetPreferredWidth(int)
	SetPreferredHeight(int)
}

Component is the base interface for all UI elements.

type Container 

type Container interface {
	Component
	Children() []Component
	AddChild(child Component)
	InnerFocused() bool
}

Container is a component composed of other components.

type Event 

type Event interface {
	// contains filtered or unexported methods
}

Event is a high-level UI event dispatched to components.

type Field 

type Field struct {
	BaseContainer
	// contains filtered or unexported fields
}

Field composes a label (Text), separator (Text), and an input component. The Field controls the label's style based on focus state — when any descendant has focus, the label highlights. The separator never highlights.

Construction: NewField("name", "Name", textBox, styles) Renders: <label><separator><input>

func NewField 

func NewField(id, labelText string, input Component, styles FieldStyles) *Field

NewField creates a Field with a label, ": " separator, and the given input component.

func (*Field) Input 

func (f *Field) Input() Component

Input returns the input component.

func (*Field) Label 

func (f *Field) Label() *Text

Label returns the label Text component.

func (*Field) Separator 

func (f *Field) Separator() *Text

Separator returns the separator Text component.

func (*Field) View 

func (f *Field) View() string

View renders label + separator + input horizontally. Field controls the label style based on focus state.

type FieldStyles 

type FieldStyles struct {
	Label     lipgloss.Style // label when no inner focus
	LabelHot  lipgloss.Style // label when input has focus
	Separator lipgloss.Style // separator style (always the same)
}

FieldStyles defines the styles used by a Field.

func DefaultFieldStyles 

func DefaultFieldStyles() FieldStyles

DefaultFieldStyles returns a FieldStyles with sensible defaults.

type FocusableComponent 

type FocusableComponent struct {
	BaseComponent
	// contains filtered or unexported fields
}

FocusableComponent extends BaseComponent for components that can receive focus. Adds OnKeyPress handler and overrides Focusable() to return true. Leaf components embed this instead of BaseComponent.

func NewFocusableComponent 

func NewFocusableComponent(id string) FocusableComponent

NewFocusableComponent creates a FocusableComponent with sensible defaults.

func (*FocusableComponent) Focusable 

func (fc *FocusableComponent) Focusable() bool

func (*FocusableComponent) OnKeyPress 

func (fc *FocusableComponent) OnKeyPress(fn func(tea.KeyMsg) tea.Cmd)

OnKeyPress sets a handler called when the component has focus and receives a key that the component's internal Update doesn't consume.

type FormattedTextInput 

type FormattedTextInput struct {
	TextInput
	// contains filtered or unexported fields
}

FormattedTextInput extends TextInput with validation and formatting.

func NewFormattedTextInput 

func NewFormattedTextInput(id string, inputWidth int) *FormattedTextInput

NewFormattedTextInput creates a new FormattedTextInput with the given ID and input width.

func (*FormattedTextInput) SetFocused 

func (fti *FormattedTextInput) SetFocused(focused bool) tea.Cmd

SetFocused sets the focused state. On blur, it runs validation and formatting.

func (*FormattedTextInput) WithFormat 

func (fti *FormattedTextInput) WithFormat(fn func(string) string)

WithFormat sets the format function applied on blur after successful validation.

func (*FormattedTextInput) WithValidation 

func (fti *FormattedTextInput) WithValidation(fn func(string) error)

WithValidation sets the validation function. Validation runs on blur.

type Layout 

type Layout int

Layout represents the layout strategy for a container. 

const (
	Vertical   Layout = iota // stack children top-to-bottom
	Horizontal               // stack children left-to-right
	TCB                      // Top-Center-Bottom: center flexes
)

type Leaf 

type Leaf interface {
	Component
	Update(msg tea.KeyMsg) (tea.Cmd, bool)
}

Leaf is a focusable component that handles keyboard input. Only focused leaves receive keyboard events. Mouse and other events go through HandleEvent on Component.

type MouseClickEvent 

type MouseClickEvent struct {
	X, Y   int
	Button tea.MouseButton
}

MouseClickEvent is sent when a mouse button is pressed on a component.

type MouseScrollEvent 

type MouseScrollEvent struct {
	X, Y      int
	Direction int
}

MouseScrollEvent is sent when the mouse wheel is scrolled over a component. Direction: negative = up, positive = down.

type Panel 

type Panel struct {
	BaseContainer
	// contains filtered or unexported fields
}

Panel is the universal container. It has a layout (Vertical, Horizontal, or TCB), an optional border, an optional title, and a unified Add(child, Position) method.

func NewPanel 

func NewPanel(id string, layout ...Layout) *Panel

NewPanel creates a Panel. Layout defaults to Vertical. Optional layout parameter: NewPanel("id") or NewPanel("id", TCB)

func (*Panel) Add 

func (p *Panel) Add(child Component, position Position)

Add places a child component at the given position. For Vertical/Horizontal: use Next to append sequentially. For TCB: use Next (fills Top->Center->Bottom) or explicit TCBTop/TCBCenter/TCBBottom.

func (*Panel) SetBorder 

func (p *Panel) SetBorder(config BorderConfig)

SetBorder sets the border configuration.

func (*Panel) SetSpacing 

func (p *Panel) SetSpacing(spacing int)

SetSpacing sets spacing between children (Horizontal layout only).

func (*Panel) SetTitle 

func (p *Panel) SetTitle(title string)

SetTitle sets the panel's title text (rendered inside the border, above children).

func (*Panel) SetTitleStyle 

func (p *Panel) SetTitleStyle(style lipgloss.Style)

SetTitleStyle sets the style for the title text.

func (*Panel) View 

func (p *Panel) View() string

View renders the panel with its layout and optional border.

type Position 

type Position int

Position specifies where a child is placed in the layout. 

const (
	Next      Position = iota // sequential: append for V/H, fill next slot for TCB
	TCBTop                    // TCB only: top slot
	TCBCenter                 // TCB only: center slot
	TCBBottom                 // TCB only: bottom slot
)

type ScrollableText 

type ScrollableText struct {
	FocusableComponent
	// contains filtered or unexported fields
}

ScrollableText is a focusable, scrollable, read-only text display area. It renders text within its SetSize bounds and scrolls with keyboard input when focused. Content may contain ANSI color codes.

func NewScrollableText 

func NewScrollableText(id string, styles ScrollableTextStyles) *ScrollableText

NewScrollableText creates a new ScrollableText with the given ID and styles.

func (*ScrollableText) Content 

func (st *ScrollableText) Content() string

Content returns the current content.

func (*ScrollableText) HandleEvent 

func (st *ScrollableText) HandleEvent(event Event) (tea.Cmd, bool)

HandleEvent handles mouse scroll events.

func (*ScrollableText) ScrollTo 

func (st *ScrollableText) ScrollTo(line int)

ScrollTo scrolls to a specific line (clamped to valid range).

func (*ScrollableText) ScrollTop 

func (st *ScrollableText) ScrollTop()

ScrollTop scrolls to the top.

func (*ScrollableText) SetContent 

func (st *ScrollableText) SetContent(text string)

SetContent sets the full text content (may contain newlines and ANSI styling).

func (*ScrollableText) SetWrap 

func (st *ScrollableText) SetWrap(wrap bool)

SetWrap sets whether long lines are wrapped to fit the viewport width. When false, lines are truncated. Default is true.

func (*ScrollableText) Update 

func (st *ScrollableText) Update(msg tea.KeyMsg) (tea.Cmd, bool)

Update handles keyboard scrolling when focused.

func (*ScrollableText) View 

func (st *ScrollableText) View() string

View renders the visible portion of the text content.

type ScrollableTextStyles 

type ScrollableTextStyles struct {
	Normal  lipgloss.Style // unfocused appearance
	Focused lipgloss.Style // focused appearance
}

ScrollableTextStyles defines the styles used by ScrollableText.

func DefaultScrollableTextStyles 

func DefaultScrollableTextStyles() ScrollableTextStyles

DefaultScrollableTextStyles returns sensible defaults for ScrollableText.

type SliceDataSource 

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

SliceDataSource is a TableDataSource backed by a [][]string.

func NewSliceDataSource 

func NewSliceDataSource(data [][]string) *SliceDataSource

NewSliceDataSource creates a SliceDataSource wrapping the given data.

func (*SliceDataSource) CellData 

func (s *SliceDataSource) CellData(row, col int) string

func (*SliceDataSource) RowCount 

func (s *SliceDataSource) RowCount() int

func (*SliceDataSource) SetData 

func (s *SliceDataSource) SetData(data [][]string)

SetData replaces the backing data. The Table re-reads on the next render.

type TabBar 

type TabBar struct {
	FocusableComponent
	// contains filtered or unexported fields
}

TabBar is a focusable horizontal tab selector component. It has two distinct states:

  • cursor: which tab the keyboard highlight is on (moves with left/right)
  • active: which tab's content is currently displayed (changes on space/enter)

func NewTabBar 

func NewTabBar(id string, labels []string, styles TabBarStyles) *TabBar

NewTabBar creates a new TabBar with the given ID, labels, and styles.

func (*TabBar) ActiveTab 

func (tb *TabBar) ActiveTab() int

ActiveTab returns the index of the currently active (selected) tab.

func (*TabBar) BindDefaultActionToKey 

func (tb *TabBar) BindDefaultActionToKey(keys string, description ...string)

BindDefaultActionToKey registers a global key binding that triggers the tab bar's default action (activate the tab under cursor).

func (*TabBar) CursorTab 

func (tb *TabBar) CursorTab() int

CursorTab returns the index the keyboard cursor is on.

func (*TabBar) HandleEvent 

func (tb *TabBar) HandleEvent(event Event) (tea.Cmd, bool)

HandleEvent handles mouse clicks by activating the clicked tab. The click X is relative to the tab bar's position and mapped to a tab using the rendered width of each label (including style padding).

func (*TabBar) OnChange 

func (tb *TabBar) OnChange(fn func(int) tea.Cmd)

OnChange sets the callback invoked when the active tab changes (on space/enter).

func (*TabBar) SetActiveTab 

func (tb *TabBar) SetActiveTab(i int)

SetActiveTab sets the active tab index and moves the cursor to match.

func (*TabBar) SetFocused 

func (tb *TabBar) SetFocused(v bool) tea.Cmd

SetFocused overrides to reset cursor to active tab when gaining focus.

func (*TabBar) SetTabKeyBinding 

func (tb *TabBar) SetTabKeyBinding(index int, keys string, description ...string)

SetTabKeyBinding binds a keyboard shortcut to activate a specific tab by index. The keys parameter is a key combo string (e.g. "ctrl+d"). The optional description is used for help text; if omitted, the tab's label is used. Panics if index is out of range. If a binding already exists for this index, it is replaced.

func (*TabBar) Update 

func (tb *TabBar) Update(msg tea.KeyMsg) (tea.Cmd, bool)

Update handles key input. Left/right moves the cursor. Space/enter activates the tab under the cursor.

func (*TabBar) View 

func (tb *TabBar) View() string

View renders the tabs horizontally joined with the appropriate styles.

Rendering rules:

  • Active tab (content displayed): Active style
  • Cursor tab (when focused and cursor != active): Focused style (yellow, highlighted)
  • Active + cursor (focused, cursor on active tab): Active style with underline
  • Other tabs: Inactive style

type TabBarStyles 

type TabBarStyles struct {
	Active   lipgloss.Style // selected tab
	Inactive lipgloss.Style // non-selected tab
	Focused  lipgloss.Style // focused inactive tab (keyboard cursor on it but not the selected tab)
}

TabBarStyles defines the styles used by a TabBar in different states.

func DefaultTabBarStyles 

func DefaultTabBarStyles() TabBarStyles

DefaultTabBarStyles returns a TabBarStyles with sensible defaults.

type TabComponent 

type TabComponent struct {
	BaseContainer
	// contains filtered or unexported fields
}

TabComponent is a container that manages tab switching. It uses TCB layout internally: the TabBar header at the top, the active tab's content panel at the center (fills remaining space).

Usage: 

tabs := widget.NewTabComponent("tabs", themeTabBarStyles())
tabs.AddTab("Dashboard", dashPanel)
tabs.AddTab("Servers", serverPanel)
tabs.AddTab("Settings", settingsPanel)
tabs.SetTabKeyBinding(0, "ctrl+d")
win.Add(tabs, widget.TCBCenter)

func NewTabComponent 

func NewTabComponent(id string, styles TabBarStyles) *TabComponent

NewTabComponent creates a TabComponent with the given ID and tab bar styles.

func (*TabComponent) ActiveTab 

func (tc *TabComponent) ActiveTab() int

ActiveTab returns the index of the currently active tab.

func (*TabComponent) AddTab 

func (tc *TabComponent) AddTab(label string, content Component)

AddTab adds a tab with the given label and content panel.

func (*TabComponent) OnChange 

func (tc *TabComponent) OnChange(fn func(int) tea.Cmd)

OnChange sets a callback invoked when the active tab changes.

func (*TabComponent) SetActiveTab 

func (tc *TabComponent) SetActiveTab(index int)

SetActiveTab switches to the tab at the given index.

func (*TabComponent) SetTabKeyBinding 

func (tc *TabComponent) SetTabKeyBinding(index int, keys string, description ...string)

SetTabKeyBinding binds a keyboard shortcut to activate a specific tab.

func (*TabComponent) TabBar 

func (tc *TabComponent) TabBar() *TabBar

TabBar returns the underlying TabBar leaf component.

func (*TabComponent) View 

func (tc *TabComponent) View() string

View renders the tab header at the top and the active tab's content filling the remaining height.

type Table 

type Table struct {
	FocusableComponent
	// contains filtered or unexported fields
}

Table is a generic, column-aware scrollable data table with cursor selection and per-cell rendering. Data is provided via a TableDataSource.

func NewTable 

func NewTable(id string, columns []ColumnDef, ds TableDataSource, styles TableStyles) *Table

NewTable creates a new Table with the given ID, columns, data source, and styles.

func (*Table) Cursor 

func (t *Table) Cursor() int

Cursor returns the current cursor index.

func (*Table) DataSource 

func (t *Table) DataSource() TableDataSource

DataSource returns the current data source.

func (*Table) HandleEvent 

func (t *Table) HandleEvent(event Event) (tea.Cmd, bool)

HandleEvent handles mouse clicks and scroll wheel events. Clicks select the row under the cursor. Scroll wheel moves the cursor up/down by 3 rows (matching typical terminal scroll speed).

func (*Table) OnRowClick 

func (t *Table) OnRowClick(fn func(row int) tea.Cmd)

OnRowClick sets a handler called when a data row is clicked. The handler receives the zero-based row index.

func (*Table) OnRowKeyPress 

func (t *Table) OnRowKeyPress(fn func(row int, msg tea.KeyMsg) tea.Cmd)

OnRowKeyPress sets a handler called when the table has focus and receives a key that the table's internal navigation doesn't consume. Unlike OnKeyPress, this passes the current cursor row so the handler has row context.

func (*Table) SetColumnSpacing 

func (t *Table) SetColumnSpacing(spacing int)

SetColumnSpacing sets the number of spaces between columns. Default is 1.

func (*Table) SetCursor 

func (t *Table) SetCursor(c int)

SetCursor sets the cursor to c if in range.

func (*Table) SetDataSource 

func (t *Table) SetDataSource(ds TableDataSource)

SetDataSource replaces the data source and clamps the cursor.

func (*Table) Update 

func (t *Table) Update(msg tea.KeyMsg) (tea.Cmd, bool)

Update handles key input for table navigation.

func (*Table) View 

func (t *Table) View() string

View renders the table: header row followed by visible data rows.

type TableDataSource 

type TableDataSource interface {
	// RowCount returns the total number of rows.
	RowCount() int
	// CellData returns the raw (unstyled) string for the given cell.
	// The Table guarantees row < RowCount() and col < len(columns).
	CellData(row, col int) string
}

TableDataSource provides row data to a Table. Implementations must return consistent results within a single render cycle. To change the data, call Table.SetDataSource with a new (or updated) source.

type TableStyles 

type TableStyles struct {
	Header   lipgloss.Style
	Selected lipgloss.Style
	Cell     lipgloss.Style // default cell style when no column renderer
}

TableStyles defines the styles used by the Table.

func DefaultTableStyles 

func DefaultTableStyles() TableStyles

DefaultTableStyles returns a TableStyles with sensible defaults.

type Text 

type Text struct {
	BaseComponent
	// contains filtered or unexported fields
}

Text is a non-focusable component that renders a styled string. It knows nothing about focus, parents, or context — it just displays text with whatever style has been set on it. The parent controls the style based on application state.

func NewText 

func NewText(id, text string, style lipgloss.Style) *Text

NewText creates a new Text component with the given ID, text, and style.

func (*Text) GetText 

func (t *Text) GetText() string

GetText returns the current text.

func (*Text) SetStyle 

func (t *Text) SetStyle(s lipgloss.Style)

SetStyle sets the rendering style.

func (*Text) SetText 

func (t *Text) SetText(text string)

SetText updates the displayed text.

func (*Text) Style 

func (t *Text) Style() lipgloss.Style

Style returns the current style.

func (*Text) View 

func (t *Text) View() string

View renders the text with its current style.

type TextInput 

type TextInput struct {
	FocusableComponent
	// contains filtered or unexported fields
}

TextInput is a focusable text input box. It wraps bubbles/textinput and handles cursor, placeholder, and character input. It does NOT render a label — use Field for label + separator + input.

func NewTextInput 

func NewTextInput(id string, inputWidth int) *TextInput

NewTextInput creates a new TextInput with the given ID and input width.

func (*TextInput) Error 

func (t *TextInput) Error() string

Error returns the current validation error.

func (*TextInput) HandleEvent 

func (t *TextInput) HandleEvent(event Event) (tea.Cmd, bool)

HandleEvent — text inputs do not react to clicks (just focus).

func (*TextInput) OnChange 

func (t *TextInput) OnChange(fn func(string) tea.Cmd)

OnChange sets the callback invoked when the input value changes.

func (*TextInput) OnSubmit 

func (t *TextInput) OnSubmit(fn func(string) tea.Cmd)

OnSubmit sets the callback invoked when Enter is pressed.

func (*TextInput) SetError 

func (t *TextInput) SetError(e string)

SetError sets a validation error message.

func (*TextInput) SetFocused 

func (t *TextInput) SetFocused(v bool) tea.Cmd

SetFocused sets the focused state and focuses/blurs the inner textinput.

func (*TextInput) SetSize 

func (t *TextInput) SetSize(w, h int)

SetSize overrides BaseComponent to adjust the inner input width.

func (*TextInput) SetValue 

func (t *TextInput) SetValue(v string)

SetValue sets the input value.

func (*TextInput) Update 

func (t *TextInput) Update(msg tea.KeyMsg) (tea.Cmd, bool)

Update handles key input. Enter triggers onSubmit; all other keys are delegated to the inner textinput. Returns (cmd, true) consuming ALL input when active. If not active, returns (nil, false).

func (*TextInput) Value 

func (t *TextInput) Value() string

Value returns the current input value.

func (*TextInput) View 

func (t *TextInput) View() string

View renders the input area only (no label).

func (*TextInput) WithCharLimit 

func (t *TextInput) WithCharLimit(n int) *TextInput

WithCharLimit sets the character limit for the input.

func (*TextInput) WithPlaceholder 

func (t *TextInput) WithPlaceholder(p string) *TextInput

WithPlaceholder sets placeholder text displayed when the field is empty.

type Toggle 

type Toggle struct {
	FocusableComponent
	// contains filtered or unexported fields
}

Toggle is a boolean on/off component with two rendering modes.

func NewToggle 

func NewToggle(id, label string, initial bool, mode ToggleMode, styles ToggleStyles) *Toggle

NewToggle creates a new Toggle with the given ID, label, initial state, mode, and styles.

func (*Toggle) BindDefaultActionToKey 

func (t *Toggle) BindDefaultActionToKey(keys string, description ...string)

BindDefaultActionToKey registers a global key binding that triggers the toggle's default action (toggle state).

func (*Toggle) HandleEvent 

func (t *Toggle) HandleEvent(event Event) (tea.Cmd, bool)

HandleEvent handles high-level events. MouseClick toggles state.

func (*Toggle) On 

func (t *Toggle) On() bool

On returns the current toggle state.

func (*Toggle) OnChange 

func (t *Toggle) OnChange(fn func(bool) tea.Cmd)

OnChange sets the callback invoked when the toggle state changes.

func (*Toggle) SetLabels 

func (t *Toggle) SetLabels(onLabel, offLabel string)

SetLabels sets the on/off display labels.

func (*Toggle) SetOn 

func (t *Toggle) SetOn(v bool)

SetOn sets the toggle state.

func (*Toggle) Update 

func (t *Toggle) Update(msg tea.KeyMsg) (tea.Cmd, bool)

Update handles key input. Space and enter toggle the state.

func (*Toggle) View 

func (t *Toggle) View() string

View renders the toggle with the appropriate style for its state.

type ToggleMode 

type ToggleMode int

ToggleMode controls how the toggle is rendered. 

const (
	// ToggleModeOnOff renders one value at a time: "Feature:[on]" or "Feature:[off]".
	ToggleModeOnOff ToggleMode = iota
	// ToggleModeRadio renders both labels side by side: "[Live] [Cache]".
	ToggleModeRadio
)

type ToggleStyles 

type ToggleStyles struct {
	Label       lipgloss.Style // label prefix
	OnActive    lipgloss.Style // on value, unfocused (green)
	OnFocused   lipgloss.Style // on value, focused (yellow)
	OffActive   lipgloss.Style // off value, unfocused (dim for OnOff, orange for Radio)
	OffFocused  lipgloss.Style // off value, focused (yellow)
	OffInactive lipgloss.Style // off value, not selected (dim) — used in Radio mode
}

ToggleStyles defines the styles used by a Toggle in different states.

func DefaultToggleStyles 

func DefaultToggleStyles() ToggleStyles

DefaultToggleStyles returns a ToggleStyles with sensible defaults.

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.