shimmer

README

Shimmer

Animated shimmering text for Go terminals. A wave of light sweeps across your text.

Built for handleui/detent.

Install

go get github.com/handleui/shimmer

Usage

shimmer.Run("Loading", "#00D787")

With background task

shimmer.NewSpinner("Installing", "#00D787").
    Action(func() { exec.Command("npm", "install").Run() }).
    Run()

With context

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
shimmer.RunContext(ctx, "Loading", "#00D787")

API

Functions

Function	Description
Run(text, color, opts...)	Display shimmer until Ctrl+C
RunContext(ctx, text, color, opts...)	Display shimmer with context
New(text, color, opts...)	Create Bubble Tea component
NewSpinner(text, color, opts...)	Create spinner with action

Options

Option	Default	Description
WithInterval(time.Duration)	50ms	Animation speed
WithWaveWidth(int)	8	Wave size in characters
WithWavePause(int)	8	Pause between loops
WithPeakLight(int)	90	Brightness 0-100
WithDirection(Direction)	Right	DirectionLeft or DirectionRight

Bubble Tea

m := shimmer.New("Loading", "#00D787")
m.Init()              // start animation
m.Update(msg)         // handle ticks
m.View()              // render
m.SetText("Done")     // change text
m.SetLoading(false)   // stop animation

Demo

go run ./_examples/demo

Documentation

Overview

Package shimmer provides animated shimmering text for terminal UIs.

A wave of light sweeps across text, creating a modern loading indicator. Works standalone or as a Bubble Tea component.

Quick start:

shimmer.Run("Loading", "#00D787")

With background task:

shimmer.NewSpinner("Installing", "#00D787").
    Action(func() { exec.Command("npm", "install").Run() }).
    Run()

As Bubble Tea component:

m := shimmer.New("Loading", "#00D787")
// use m.Init(), m.Update(), m.View() in your Bubble Tea app

Index

• Constants
• func Run(text, color string, opts ...Option) error
• func RunContext(ctx context.Context, text, color string, opts ...Option) error
• type Direction
• type Model
  • func New(text, baseColor string, opts ...Option) Model
  • func (m Model) Init() tea.Cmd
  • func (m Model) SetLoading(loading bool) Model
  • func (m Model) SetText(text string) Model
  • func (m Model) Update(msg tea.Msg) (Model, tea.Cmd)
  • func (m Model) View() string
• type Option
  • func WithDirection(dir Direction) Option
  • func WithInterval(d time.Duration) Option
  • func WithPeakLight(percent int) Option
  • func WithWavePause(pause int) Option
  • func WithWaveWidth(width int) Option
• type Spinner
  • func NewSpinner(text, color string, opts ...Option) *Spinner
  • func (s *Spinner) Action(fn func()) *Spinner
  • func (s *Spinner) Context(ctx context.Context) *Spinner
  • func (s *Spinner) Run() error
• type TickMsg

Constants

const (
	DefaultInterval  = 50 * time.Millisecond // Animation frame rate
	DefaultPeakLight = 90                    // Maximum lightness percentage (0-100)
	DefaultWaveWidth = 8                     // Number of characters in the wave
	DefaultWavePause = 8                     // Pause between wave loops (in characters)
)

Default configuration values for the shimmer effect.

Functions

func Run

func Run(text, color string, opts ...Option) error

Run displays shimmering text until the user presses Ctrl+C, q, or Esc. This is a blocking call that handles all Bubble Tea setup.

Example:

shimmer.Run("Loading", "#00D787")

With options:

shimmer.Run("Processing", "#FFC000",
    shimmer.WithInterval(100*time.Millisecond),
    shimmer.WithWaveWidth(12),
)

func RunContext

func RunContext(ctx context.Context, text, color string, opts ...Option) error

RunContext is like Run but accepts a context for cancellation.

Types

type Direction

type Direction int

Direction controls which way the shimmer wave moves.

const (
	DirectionRight Direction = iota // Wave moves left to right (default)
	DirectionLeft                   // Wave moves right to left
)

Shimmer wave direction constants.

type Model

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

Model creates an animated shimmer effect on text. A wave of brightened color sweeps across the text, creating a loading indicator.

func New

func New(text, baseColor string, opts ...Option) Model

New creates a new shimmer model with the given text and base color. Color should be a hex color like "#00D787".

func (Model) Init

func (m Model) Init() tea.Cmd

Init starts the shimmer animation tick.

func (Model) SetLoading

func (m Model) SetLoading(loading bool) Model

SetLoading enables or disables the shimmer animation.

func (Model) SetText

func (m Model) SetText(text string) Model

SetText updates the text being displayed.

func (Model) Update

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

Update handles shimmer animation ticks.

func (Model) View

func (m Model) View() string

View renders the shimmer text with per-character coloring.

type Option

type Option func(*Model)

Option is a function that configures a Model.

func WithDirection

func WithDirection(dir Direction) Option

WithDirection sets the wave direction (left or right).

func WithInterval

func WithInterval(d time.Duration) Option

WithInterval sets the animation speed (time between frames).

func WithPeakLight

func WithPeakLight(percent int) Option

WithPeakLight sets the maximum lightness (0-100). Higher = brighter shimmer.

func WithWavePause

func WithWavePause(pause int) Option

WithWavePause sets the pause between wave loops (in character positions).

func WithWaveWidth

func WithWaveWidth(width int) Option

WithWaveWidth sets the width of the shimmer wave in characters.

type Spinner

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

Spinner provides a builder pattern for running shimmer with a background action.

func NewSpinner

func NewSpinner(text, color string, opts ...Option) *Spinner

NewSpinner creates a spinner builder for running shimmer with background work.

Example:

shimmer.NewSpinner("Installing", "#00D787").
    Action(func() { exec.Command("npm", "install").Run() }).
    Run()

func (*Spinner) Action

func (s *Spinner) Action(fn func()) *Spinner

Action sets a function to run while the shimmer animates. The shimmer stops when the action completes.

func (*Spinner) Context

func (s *Spinner) Context(ctx context.Context) *Spinner

Context sets the context for cancellation.

func (*Spinner) Run

func (s *Spinner) Run() error

Run executes the shimmer animation with the configured action.

type TickMsg

type TickMsg time.Time

TickMsg triggers a shimmer animation frame.