widget

package
v0.1.4 Latest Latest
Warning

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

 Go to latest Published: Apr 9, 2026 License: MIT Imports: 4 Imported by: 0

Documentation

Overview

Package widget provides built-in UI components for the tui framework.

Widgets fall into two categories: passive widgets that only render (like Text and Progress) and interactive widgets that handle input events (like Input, List, and Table).

Interactive widgets follow a consistent pattern: 

// In your Component's Update method:
a.list, cmd = a.list.Update(msg)

// In your Component's Render method:
a.list.Render(buf, area)

Most widgets support an optional tui.Block for borders and titles: 

block := tui.NewBlock()
block.Title = "Items"
a.list.SetBlock(block)

Image widgets use the Kitty Graphics Protocol via tui.ImagePlacement for rendering pixel-based graphics inline in the terminal.

Index

Constants

This section is empty.

Variables

View Source 
var (
	SpinnerDots = SpinnerStyle{
		Frames:   []string{"⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"},
		Interval: 80 * time.Millisecond,
	}
	SpinnerLine = SpinnerStyle{
		Frames:   []string{"|", "/", "-", "\\"},
		Interval: 100 * time.Millisecond,
	}
	SpinnerCircle = SpinnerStyle{
		Frames:   []string{"◐", "◓", "◑", "◒"},
		Interval: 120 * time.Millisecond,
	}
	SpinnerBounce = SpinnerStyle{
		Frames:   []string{"⠁", "⠂", "⠄", "⡀", "⢀", "⠠", "⠐", "⠈"},
		Interval: 100 * time.Millisecond,
	}
	SpinnerMeter = SpinnerStyle{
		Frames:   []string{"▱▱▱", "▰▱▱", "▰▰▱", "▰▰▰", "▰▰▱", "▰▱▱"},
		Interval: 150 * time.Millisecond,
	}
	SpinnerGlobe = SpinnerStyle{
		Frames:   []string{"🌍", "🌎", "🌏"},
		Interval: 200 * time.Millisecond,
	}
	SpinnerBlock = SpinnerStyle{
		Frames:   []string{"█", "▓", "▒", "░", "▒", "▓"},
		Interval: 100 * time.Millisecond,
	}
)

Predefined spinner styles.

Functions

This section is empty.

Types

type Alignment 

type Alignment int

Alignment controls text alignment. 

const (
	AlignLeft Alignment = iota
	AlignCenter
	AlignRight
)

type AnimatedImage 

type AnimatedImage struct {
	Animation *tui.Animation
	Block     *tui.Block
	// contains filtered or unexported fields
}

AnimatedImage displays an animated image using KGP animation frames.

func NewAnimatedImage 

func NewAnimatedImage(anim *tui.Animation) *AnimatedImage

NewAnimatedImage creates an animated image widget. The base image is transmitted as frame 1, and the Animation contains subsequent frames.

func (*AnimatedImage) Render 

func (a *AnimatedImage) Render(buf *tui.Buffer, area tui.Rect)

Render draws the animated image. On the first render, it transmits all frames.

func (*AnimatedImage) SetBlock 

func (a *AnimatedImage) SetBlock(b tui.Block) *AnimatedImage

SetBlock adds a border block.

type Dialog 

type Dialog struct {
	Title    string
	Message  string
	Buttons  []string
	Selected int
	Style    tui.Style
	Border   tui.BorderStyle

	// Styling
	ButtonStyle         tui.Style
	SelectedButtonStyle tui.Style
	MessageStyle        tui.Style
}

Dialog is a modal dialog box with a message and buttons.

func NewDialog 

func NewDialog(title, message string) *Dialog

NewDialog creates a dialog with OK/Cancel buttons.

func (*Dialog) Render 

func (d *Dialog) Render(buf *tui.Buffer, area tui.Rect)

Render draws the dialog centered in the given area.

func (*Dialog) SelectedButton 

func (d *Dialog) SelectedButton() string

SelectedButton returns the text of the currently selected button.

func (*Dialog) SetButtons 

func (d *Dialog) SetButtons(buttons ...string) *Dialog

SetButtons sets the dialog buttons.

func (*Dialog) Update 

func (d *Dialog) Update(msg tui.Msg) (*Dialog, tui.Cmd)

Update handles navigation between buttons.

type FocusInputMsg 

type FocusInputMsg struct{}

FocusInputMsg signals that the input should receive focus.

type Form 

type Form struct {
	Fields     []FormField
	FocusIndex int
	Style      tui.Style
	LabelStyle tui.Style
	LabelWidth int
	Block      *tui.Block
}

Form is a collection of labeled input fields.

func NewForm 

func NewForm(fields ...FormField) *Form

NewForm creates a new form with the given fields.

func (*Form) FocusedField 

func (f *Form) FocusedField() *FormField

FocusedField returns the currently focused field.

func (*Form) Render 

func (f *Form) Render(buf *tui.Buffer, area tui.Rect)

Render draws the form.

func (*Form) SetBlock 

func (f *Form) SetBlock(b tui.Block) *Form

SetBlock adds a border block.

func (*Form) Update 

func (f *Form) Update(msg tui.Msg) (*Form, tui.Cmd)

Update handles form navigation and input.

func (*Form) Value 

func (f *Form) Value(label string) string

Value returns the value of a field by label.

func (*Form) Values 

func (f *Form) Values() map[string]string

Values returns all field values as a map of label -> value.

type FormField 

type FormField struct {
	Label string
	Input *Input
}

FormField represents a single field in a form.

func NewFormField 

func NewFormField(label, placeholder string) FormField

NewFormField creates a form field with label and placeholder.

type Gauge 

type Gauge struct {
	Percent     float64
	Label       string
	Style       tui.Style
	FilledStyle tui.Style
	Block       *tui.Block
}

Gauge is a full-width progress gauge with a label overlay.

func NewGauge 

func NewGauge() *Gauge

NewGauge creates a new gauge widget.

func (*Gauge) Render 

func (g *Gauge) Render(buf *tui.Buffer, area tui.Rect)

Render draws the gauge.

func (*Gauge) SetBlock 

func (g *Gauge) SetBlock(b tui.Block) *Gauge

SetBlock adds a border block.

func (*Gauge) SetLabel 

func (g *Gauge) SetLabel(label string) *Gauge

SetLabel sets the overlay label. Use "" for auto percentage.

func (*Gauge) SetPercent 

func (g *Gauge) SetPercent(v float64) *Gauge

SetPercent sets the gauge value (0.0 to 1.0).

type Image 

type Image struct {
	Block *tui.Block
	// contains filtered or unexported fields
}

Image displays an image using the Kitty Graphics Protocol.

func NewImage 

func NewImage(img image.Image) *Image

NewImage creates an image widget from a Go image.

func NewImageFromFile 

func NewImageFromFile(path string) *Image

NewImageFromFile creates an image widget that loads from a file path.

func NewImageFromID 

func NewImageFromID(imageID uint32) *Image

NewImageFromID creates an image widget for a previously transmitted image.

func NewImageFromPNG 

func NewImageFromPNG(data []byte) *Image

NewImageFromPNG creates an image widget from raw PNG data.

func NewImageFromRGB 

func NewImageFromRGB(data []byte, width, height int) *Image

NewImageFromRGB creates an image widget from raw RGB pixel data.

func NewImageFromRGBA 

func NewImageFromRGBA(data []byte, width, height int) *Image

NewImageFromRGBA creates an image widget from raw RGBA pixel data.

func (*Image) Render 

func (i *Image) Render(buf *tui.Buffer, area tui.Rect)

Render draws the image into the buffer area.

func (*Image) SetBlock 

func (i *Image) SetBlock(b tui.Block) *Image

SetBlock adds a border block.

func (*Image) SetCompression 

func (i *Image) SetCompression(enabled bool) *Image

SetCompression enables ZLIB compression for RGBA/RGB data.

func (*Image) SetCrop 

func (i *Image) SetCrop(x, y, w, h int) *Image

SetCrop sets a source rectangle for cropping.

func (*Image) SetVirtual 

func (i *Image) SetVirtual(v bool) *Image

SetVirtual enables virtual (Unicode placeholder) placement.

func (*Image) SetZIndex 

func (i *Image) SetZIndex(z int) *Image

SetZIndex sets the z-index for layering.

type Input 

type Input struct {
	Value       string
	Placeholder string
	Style       tui.Style
	CursorStyle tui.Style
	Focused     bool
	Block       *tui.Block
	// contains filtered or unexported fields
}

Input is a single-line text input widget.

func NewInput 

func NewInput(placeholder string) *Input

NewInput creates a new input widget.

func (*Input) Focus 

func (in *Input) Focus() tui.Cmd

Focus returns a Cmd that sends a FocusInputMsg.

func (*Input) Render 

func (in *Input) Render(buf *tui.Buffer, area tui.Rect)

Render draws the input widget.

func (*Input) SetBlock 

func (in *Input) SetBlock(b tui.Block) *Input

SetBlock adds a border block.

func (*Input) SetStyle 

func (in *Input) SetStyle(s tui.Style) *Input

SetStyle sets the text style.

func (*Input) Update 

func (in *Input) Update(msg tui.Msg) (*Input, tui.Cmd)

Update handles key events for the input.

type List 

type List struct {
	Items         []ListItem
	Selected      int
	Style         tui.Style
	SelectedStyle tui.Style
	Block         *tui.Block
	// contains filtered or unexported fields
}

List is a scrollable, selectable list widget.

func NewList 

func NewList(items []string) *List

NewList creates a list from string items.

func NewListFromItems 

func NewListFromItems(items []ListItem) *List

NewListFromItems creates a list from ListItem values.

func (*List) Render 

func (l *List) Render(buf *tui.Buffer, area tui.Rect)

Render draws the list.

func (*List) SelectedItem 

func (l *List) SelectedItem() *ListItem

SelectedItem returns the currently selected item, or nil if the list is empty.

func (*List) SetBlock 

func (l *List) SetBlock(b tui.Block) *List

SetBlock adds a border block.

func (*List) SetSelectedStyle 

func (l *List) SetSelectedStyle(s tui.Style) *List

SetSelectedStyle sets the selected item style.

func (*List) SetStyle 

func (l *List) SetStyle(s tui.Style) *List

SetStyle sets the default item style.

func (*List) Update 

func (l *List) Update(msg tui.Msg) (*List, tui.Cmd)

Update handles key events for navigation.

type ListItem 

type ListItem struct {
	Text string
	Data any
}

ListItem represents a single item in a list.

type Progress 

type Progress struct {
	Percent     float64 // 0.0 to 1.0
	Style       tui.Style
	FilledChar  rune
	EmptyChar   rune
	FilledStyle tui.Style
	EmptyStyle  tui.Style
	Block       *tui.Block
	ShowLabel   bool
}

Progress renders a progress bar.

func NewProgress 

func NewProgress() *Progress

NewProgress creates a new progress bar.

func (*Progress) Render 

func (p *Progress) Render(buf *tui.Buffer, area tui.Rect)

Render draws the progress bar.

func (*Progress) SetBlock 

func (p *Progress) SetBlock(b tui.Block) *Progress

SetBlock adds a border block.

func (*Progress) SetPercent 

func (p *Progress) SetPercent(v float64) *Progress

SetPercent sets the progress value (0.0 to 1.0).

type Scrollbar 

type Scrollbar struct {
	Total   int // Total number of items/lines
	Visible int // Number visible at once
	Offset  int // Current scroll offset

	// Characters
	TrackChar  rune
	ThumbChar  rune
	Style      tui.Style
	ThumbStyle tui.Style

	Vertical bool // true = vertical (default), false = horizontal
}

Scrollbar renders a vertical or horizontal scrollbar.

func NewHScrollbar 

func NewHScrollbar(total, visible, offset int) *Scrollbar

NewHScrollbar creates a horizontal scrollbar.

func NewScrollbar 

func NewScrollbar(total, visible, offset int) *Scrollbar

NewScrollbar creates a vertical scrollbar.

func (*Scrollbar) Render 

func (s *Scrollbar) Render(buf *tui.Buffer, area tui.Rect)

Render draws the scrollbar.

type Sparkline 

type Sparkline struct {
	Data   []float64
	Style  tui.Style
	MaxVal float64 // 0 = auto
	Block  *tui.Block
}

Sparkline renders a mini line chart using braille/block characters.

func NewSparkline 

func NewSparkline(data []float64) *Sparkline

NewSparkline creates a new sparkline chart.

func (*Sparkline) PushData 

func (s *Sparkline) PushData(val float64, maxLen int) *Sparkline

PushData appends a value, keeping the slice at maxLen.

func (*Sparkline) Render 

func (s *Sparkline) Render(buf *tui.Buffer, area tui.Rect)

Render draws the sparkline.

func (*Sparkline) SetBlock 

func (s *Sparkline) SetBlock(b tui.Block) *Sparkline

SetBlock adds a border block.

func (*Sparkline) SetData 

func (s *Sparkline) SetData(data []float64) *Sparkline

SetData updates the sparkline data.

func (*Sparkline) SetMaxVal 

func (s *Sparkline) SetMaxVal(v float64) *Sparkline

SetMaxVal sets the maximum value for scaling. 0 = auto.

func (*Sparkline) SetStyle 

func (s *Sparkline) SetStyle(st tui.Style) *Sparkline

SetStyle sets the sparkline style.

type SparklineGroup 

type SparklineGroup struct {
	Sparklines []*Sparkline
	Block      *tui.Block
}

SparklineGroup renders multiple sparklines stacked vertically.

func NewSparklineGroup 

func NewSparklineGroup(sparklines ...*Sparkline) *SparklineGroup

NewSparklineGroup creates a group of sparklines.

func (*SparklineGroup) Render 

func (g *SparklineGroup) Render(buf *tui.Buffer, area tui.Rect)

Render draws all sparklines stacked.

func (*SparklineGroup) SetBlock 

func (g *SparklineGroup) SetBlock(b tui.Block) *SparklineGroup

SetBlock adds a border block.

type Spinner 

type Spinner struct {
	SpinnerStyle SpinnerStyle
	Style        tui.Style
	Label        string
	// contains filtered or unexported fields
}

Spinner is an animated loading indicator.

func NewSpinner 

func NewSpinner() *Spinner

NewSpinner creates a new spinner with the dots style.

func (*Spinner) Render 

func (s *Spinner) Render(buf *tui.Buffer, area tui.Rect)

Render draws the spinner and label.

func (*Spinner) SetLabel 

func (s *Spinner) SetLabel(label string) *Spinner

SetLabel sets the label shown after the spinner.

func (*Spinner) SetSpinnerStyle 

func (s *Spinner) SetSpinnerStyle(ss SpinnerStyle) *Spinner

SetSpinnerStyle changes the spinner animation.

func (*Spinner) SetStyle 

func (s *Spinner) SetStyle(st tui.Style) *Spinner

SetStyle sets the spinner text style.

func (*Spinner) Tick 

func (s *Spinner) Tick() tui.Cmd

Tick returns a Cmd that sends a SpinnerTickMsg after the interval.

func (*Spinner) Update 

func (s *Spinner) Update(msg tui.Msg) (*Spinner, tui.Cmd)

Update handles tick messages.

func (*Spinner) View 

func (s *Spinner) View() string

View returns the current spinner frame as a string.

type SpinnerStyle 

type SpinnerStyle struct {
	Frames   []string
	Interval time.Duration
}

SpinnerStyle defines the frames of a spinner animation.

type SpinnerTickMsg 

type SpinnerTickMsg struct {
	Time time.Time
	ID   int
}

SpinnerTickMsg triggers a spinner frame advance.

type Table 

type Table struct {
	Headers       []string
	Rows          [][]string
	ColWidths     []int // Fixed column widths (0 = auto)
	Selected      int
	Style         tui.Style
	HeaderStyle   tui.Style
	SelectedStyle tui.Style
	Block         *tui.Block
	// contains filtered or unexported fields
}

Table renders a data table with headers and rows.

func NewTable 

func NewTable(headers []string) *Table

NewTable creates a new table widget.

func (*Table) Render 

func (t *Table) Render(buf *tui.Buffer, area tui.Rect)

Render draws the table.

func (*Table) SelectedRow 

func (t *Table) SelectedRow() []string

SelectedRow returns the selected row data, or nil if empty.

func (*Table) SetBlock 

func (t *Table) SetBlock(b tui.Block) *Table

SetBlock adds a border block.

func (*Table) SetColWidths 

func (t *Table) SetColWidths(widths []int) *Table

SetColWidths sets fixed column widths.

func (*Table) SetRows 

func (t *Table) SetRows(rows [][]string) *Table

SetRows sets the table data.

func (*Table) SetSelectedStyle 

func (t *Table) SetSelectedStyle(s tui.Style) *Table

SetSelectedStyle sets the selected row style.

func (*Table) Update 

func (t *Table) Update(msg tui.Msg) (*Table, tui.Cmd)

Update handles key events for table navigation.

type Tabs 

type Tabs struct {
	Titles        []string
	Selected      int
	Style         tui.Style
	ActiveStyle   tui.Style
	InactiveStyle tui.Style
	Block         *tui.Block
	Separator     string
}

Tabs renders a tab bar with selectable tabs.

func NewTabs 

func NewTabs(titles []string) *Tabs

NewTabs creates a new tab bar.

func (*Tabs) Render 

func (t *Tabs) Render(buf *tui.Buffer, area tui.Rect)

Render draws the tab bar.

func (*Tabs) SetBlock 

func (t *Tabs) SetBlock(b tui.Block) *Tabs

SetBlock adds a border block.

func (*Tabs) Update 

func (t *Tabs) Update(msg tui.Msg) (*Tabs, tui.Cmd)

Update handles key events for tab switching.

type Text 

type Text struct {
	Content   string
	Style     tui.Style
	Alignment Alignment
	Block     *tui.Block
}

Text renders static text content.

func NewText 

func NewText(content string) *Text

NewText creates a new text widget.

func (*Text) Render 

func (t *Text) Render(buf *tui.Buffer, area tui.Rect)

Render draws the text into the buffer.

func (*Text) SetAlignment 

func (t *Text) SetAlignment(a Alignment) *Text

SetAlignment sets text alignment.

func (*Text) SetBlock 

func (t *Text) SetBlock(b tui.Block) *Text

SetBlock adds a border block around the text.

func (*Text) SetStyle 

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

SetStyle sets the text style.

type Tree 

type Tree struct {
	Root          []*TreeNode
	Selected      int // index in the flattened visible list
	Style         tui.Style
	SelectedStyle tui.Style
	Block         *tui.Block
	IndentSize    int
	// contains filtered or unexported fields
}

Tree is a navigable tree view widget.

func NewTree 

func NewTree(roots ...*TreeNode) *Tree

NewTree creates a tree from root nodes.

func (*Tree) Render 

func (t *Tree) Render(buf *tui.Buffer, area tui.Rect)

Render draws the tree.

func (*Tree) SelectedNode 

func (t *Tree) SelectedNode() *TreeNode

SelectedNode returns the currently selected tree node.

func (*Tree) SetBlock 

func (t *Tree) SetBlock(b tui.Block) *Tree

SetBlock adds a border block.

func (*Tree) SetSelectedStyle 

func (t *Tree) SetSelectedStyle(s tui.Style) *Tree

SetSelectedStyle sets the selected node style.

func (*Tree) SetStyle 

func (t *Tree) SetStyle(s tui.Style) *Tree

SetStyle sets the default node style.

func (*Tree) Update 

func (t *Tree) Update(msg tui.Msg) (*Tree, tui.Cmd)

Update handles navigation and expand/collapse.

type TreeNode 

type TreeNode struct {
	Text     string
	Children []*TreeNode
	Data     any
	Expanded bool
}

TreeNode represents a node in a tree view.

func NewTreeNode 

func NewTreeNode(text string, children ...*TreeNode) *TreeNode

NewTreeNode creates a tree node.

type Viewport 

type Viewport struct {
	Content string
	Style   tui.Style
	Block   *tui.Block
	YOffset int
	// contains filtered or unexported fields
}

Viewport is a scrollable text display widget.

func NewViewport 

func NewViewport(content string) *Viewport

NewViewport creates a new viewport.

func (*Viewport) LineCount 

func (v *Viewport) LineCount() int

LineCount returns the total number of wrapped lines.

func (*Viewport) Render 

func (v *Viewport) Render(buf *tui.Buffer, area tui.Rect)

Render draws the viewport content.

func (*Viewport) ScrollTo 

func (v *Viewport) ScrollTo(y int)

ScrollTo scrolls to an absolute line offset.

func (*Viewport) SetBlock 

func (v *Viewport) SetBlock(b tui.Block) *Viewport

SetBlock adds a border block.

func (*Viewport) SetContent 

func (v *Viewport) SetContent(content string) *Viewport

SetContent updates the displayed text.

func (*Viewport) SetStyle 

func (v *Viewport) SetStyle(s tui.Style) *Viewport

SetStyle sets the text style.

func (*Viewport) Update 

func (v *Viewport) Update(msg tui.Msg) (*Viewport, tui.Cmd)

Update handles scrolling keys.

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.