progress

Documentation

Overview

Package progress provides a simple progress bar for Bubble Tea applications.

Index

• Constants
• type ColorFunc
• type FrameMsg
• type Model
  • func New(opts ...Option) Model
  • func (m *Model) DecrPercent(v float64) tea.Cmd
  • func (m *Model) IncrPercent(v float64) tea.Cmd
  • func (m Model) Init() tea.Cmd
  • func (m *Model) IsAnimating() bool
  • func (m Model) Percent() float64
  • func (m *Model) SetPercent(p float64) tea.Cmd
  • func (m *Model) SetSpringOptions(frequency, damping float64)
  • func (m *Model) SetWidth(w int)
  • func (m Model) Update(msg tea.Msg) (Model, tea.Cmd)
  • func (m Model) View() string
  • func (m Model) ViewAs(percent float64) string
  • func (m Model) Width() int
• type Option
  • func WithColorFunc(fn ColorFunc) Option
  • func WithColors(colors ...color.Color) Option
  • func WithDefaultBlend() Option
  • func WithFillCharacters(full rune, empty rune) Option
  • func WithScaled(enabled bool) Option
  • func WithSpringOptions(frequency, damping float64) Option
  • func WithWidth(w int) Option
  • func WithoutPercentage() Option

Constants

const (
	// DefaultFullCharHalfBlock is the default character used to fill the progress
	// bar. It is a half block, which allows more granular color blending control,
	// by having a different foreground and background color, doubling blending
	// resolution.
	DefaultFullCharHalfBlock = '▌'

	// DefaultFullCharFullBlock can also be used as a fill character for the
	// progress bar. Use this to disable the higher resolution blending which is
	// enabled when using [DefaultFullCharHalfBlock].
	DefaultFullCharFullBlock = '█'

	// DefaultEmptyCharBlock is the default character used to fill the empty
	// portion of the progress bar.
	DefaultEmptyCharBlock = '░'
)

Types

type ColorFunc

type ColorFunc func(total, current float64) color.Color

ColorFunc is a function that can be used to dynamically fill the progress bar based on the current percentage. total is the total filled percentage, and current is the current percentage that is actively being filled with a color.

type FrameMsg

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

FrameMsg indicates that an animation step should occur.

type Model

type Model struct {

	// "Filled" sections of the progress bar.
	Full      rune
	FullColor color.Color

	// "Empty" sections of the progress bar.
	Empty      rune
	EmptyColor color.Color

	// Settings for rendering the numeric percentage.
	ShowPercentage  bool
	PercentFormat   string // a fmt string for a float
	PercentageStyle lipgloss.Style
	// contains filtered or unexported fields
}

Model stores values we'll use when rendering the progress bar.

func New

func New(opts ...Option) Model

New returns a model with default values.

func (*Model) DecrPercent

func (m *Model) DecrPercent(v float64) tea.Cmd

DecrPercent decrements the percentage by a given amount, returning a command necessary to animate the progress bar to the new percentage.

If you're rendering with ViewAs you won't need this.

func (*Model) IncrPercent

func (m *Model) IncrPercent(v float64) tea.Cmd

IncrPercent increments the percentage by a given amount, returning a command necessary to animate the progress bar to the new percentage.

If you're rendering with ViewAs you won't need this.

func (Model) Init

func (m Model) Init() tea.Cmd

Init exists to satisfy the tea.Model interface.

func (*Model) IsAnimating

func (m *Model) IsAnimating() bool

IsAnimating returns false if the progress bar reached equilibrium and is no longer animating.

func (Model) Percent

func (m Model) Percent() float64

Percent returns the current visible percentage on the model. This is only relevant when you're animating the progress bar.

If you're rendering with ViewAs you won't need this.

func (*Model) SetPercent

func (m *Model) SetPercent(p float64) tea.Cmd

SetPercent sets the percentage state of the model as well as a command necessary for animating the progress bar to this new percentage.

If you're rendering with ViewAs you won't need this.

func (*Model) SetSpringOptions

func (m *Model) SetSpringOptions(frequency, damping float64)

SetSpringOptions sets the frequency and damping for the current spring. Frequency corresponds to speed, and damping to bounciness. For details see:

https://github.com/charmbracelet/harmonica

func (*Model) SetWidth

func (m *Model) SetWidth(w int)

SetWidth sets the width of the progress bar.

func (Model) Update

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

Update is used to animate the progress bar during transitions. Use SetPercent to create the command you'll need to trigger the animation.

If you're rendering with ViewAs you won't need this.

func (Model) View

func (m Model) View() string

View renders an animated progress bar in its current state. To render a static progress bar based on your own calculations use ViewAs instead.

func (Model) ViewAs

func (m Model) ViewAs(percent float64) string

ViewAs renders the progress bar with a given percentage.

func (Model) Width

func (m Model) Width() int

Width returns the width of the progress bar.

type Option

type Option func(*Model)

Option is used to set options in New. For example:

progress := New(
	WithColors(
		lipgloss.Color("#5A56E0"),
		lipgloss.Color("#EE6FF8"),
	),
	WithoutPercentage(),
)

func WithColorFunc

func WithColorFunc(fn ColorFunc) Option

WithColorFunc sets a function that can be used to dynamically fill the progress bar based on the current percentage. total is the total filled percentage, and current is the current percentage that is actively being filled with a color. When specified, this overrides any other defined colors and scaling.

Example: A progress bar that changes color based on the total completed percentage:

WithColorFunc(func(total, current float64) color.Color {
	if total <= 0.3 {
		return lipgloss.Color("#FF0000")
	}
	if total <= 0.7 {
		return lipgloss.Color("#00FF00")
	}
	return lipgloss.Color("#0000FF")
}),

func WithColors

func WithColors(colors ...color.Color) Option

WithColors sets the colors to use to fill the progress bar. Depending on the number of colors passed in, will determine whether to use a solid fill or a blend of colors.

• 0 colors: clears all previously set colors, setting them back to defaults.
• 1 color: uses a solid fill with the given color.
• 2+ colors: uses a blend of the provided colors.

func WithDefaultBlend

func WithDefaultBlend() Option

WithDefaultBlend sets a default blend of colors, which is a blend of purple haze to neon pink.

func WithFillCharacters

func WithFillCharacters(full rune, empty rune) Option

WithFillCharacters sets the characters used to construct the full and empty components of the progress bar.

func WithScaled

func WithScaled(enabled bool) Option

WithScaled sets whether to scale the blend/gradient to fit the width of only the filled portion of the progress bar. The default is false, which means the percentage must be 100% to see the full color blend/gradient.

This is ignored when not using blending/multiple colors.

func WithSpringOptions

func WithSpringOptions(frequency, damping float64) Option

WithSpringOptions sets the initial frequency and damping options for the progress bar's built-in spring-based animation. Frequency corresponds to speed, and damping to bounciness. For details see:

https://github.com/charmbracelet/harmonica

func WithWidth

func WithWidth(w int) Option

WithWidth sets the initial width of the progress bar. Note that you can also set the width via the Width property, which can come in handy if you're waiting for a tea.WindowSizeMsg.

func WithoutPercentage

func WithoutPercentage() Option

WithoutPercentage hides the numeric percentage.