toast

package
v0.21.0 Latest Latest
Warning

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

Go to latest
Published: Jun 6, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package toast provides animated notification stacks.

A Manager is a normal termdash widget, so it can be placed in a regular container, embedded in a modal window, wrapped with widgets/fx effects, or hosted by a container whose border is animated by widgets/borderfx.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Action

type Action struct {
	// Label is drawn between square brackets.
	Label string
	// Callback runs when the label is clicked. A nil callback renders as a
	// visual-only action.
	Callback func() error
	// Dismiss removes the notification after a successful click.
	Dismiss bool
}

Action is a clickable label shown in a notification footer.

type Animation

type Animation int

Animation identifies the motion used when a toast appears.

const (
	// AnimationNone renders notifications at their final position immediately.
	AnimationNone Animation = iota
	// AnimationSlide slides notifications in from the configured direction.
	AnimationSlide
	// AnimationFade renders notifications with dimmed cells until settled.
	AnimationFade
	// AnimationPop grows notifications from a compact centered rectangle.
	AnimationPop
)

Animation values supported by Manager.

type Direction

type Direction int

Direction identifies the edge used by slide animations.

const (
	// DirectionRight slides notifications in from the right edge.
	DirectionRight Direction = iota
	// DirectionLeft slides notifications in from the left edge.
	DirectionLeft
	// DirectionTop slides notifications in from the top edge.
	DirectionTop
	// DirectionBottom slides notifications in from the bottom edge.
	DirectionBottom
)

Direction values supported by slide animations.

type Manager

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

Manager renders and manages a stack of toast notifications.

Implements widgetapi.Widget. This object is thread-safe.

func New

func New(opts ...Option) (*Manager, error)

New returns a new notification manager.

func (*Manager) Clear

func (m *Manager) Clear()

Clear removes all notifications.

func (*Manager) Count

func (m *Manager) Count() int

Count returns the number of notifications currently held by the manager.

func (*Manager) Dismiss

func (m *Manager) Dismiss(id string) bool

Dismiss removes a notification by ID.

func (*Manager) Draw

func (m *Manager) Draw(cvs *canvas.Canvas, meta *widgetapi.Meta) error

Draw implements widgetapi.Widget.

func (*Manager) Keyboard

func (m *Manager) Keyboard(k *terminalapi.Keyboard, meta *widgetapi.EventMeta) error

Keyboard implements widgetapi.Widget.

func (*Manager) Mouse

func (m *Manager) Mouse(event *terminalapi.Mouse, meta *widgetapi.EventMeta) error

Mouse implements widgetapi.Widget.

func (*Manager) Notify

func (m *Manager) Notify(title, message string, opts ...NotificationOption) string

Notify creates a notification from the provided title and message.

func (*Manager) Options

func (m *Manager) Options() widgetapi.Options

Options implements widgetapi.Widget.

func (*Manager) Push

func (m *Manager) Push(n Notification) string

Push adds a prepared notification and returns its ID.

type Notification

type Notification struct {
	// ID uniquely identifies the notification. A stable ID is generated when
	// empty.
	ID string
	// Title is the first, emphasized line.
	Title string
	// Message is wrapped underneath the title.
	Message string
	// Severity selects the visual style.
	Severity Severity
	// TTL controls how long the notification remains visible. Zero uses the
	// manager default; negative values make the notification sticky.
	TTL time.Duration
	// Created is the timestamp used for TTL and entrance animation. The current
	// manager clock is used when Created is zero.
	Created time.Time
	// Icon overrides the severity icon when non-zero.
	Icon rune
	// Progress is the optional progress value in the range [0, 1].
	Progress float64
	// ShowProgress controls whether Progress is drawn.
	ShowProgress bool
	// Actions are compact labels drawn at the bottom of the toast.
	Actions []Action
}

Notification is a single toast entry.

type NotificationOption

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

NotificationOption configures a notification passed to Notify.

func Sticky

func Sticky() NotificationOption

Sticky makes the notification stay visible until dismissed.

func WithAction

func WithAction(label string, callback func() error) NotificationOption

WithAction appends a clickable action label to the notification footer.

func WithActionValues

func WithActionValues(actions ...Action) NotificationOption

WithActionValues replaces the notification footer with prepared actions.

func WithActions

func WithActions(actions ...string) NotificationOption

WithActions sets compact action labels for the notification footer.

func WithCreated

func WithCreated(created time.Time) NotificationOption

WithCreated sets the notification creation time.

func WithID

func WithID(id string) NotificationOption

WithID sets the notification ID.

func WithIcon

func WithIcon(icon rune) NotificationOption

WithIcon sets a notification-specific icon.

func WithProgress

func WithProgress(progress float64) NotificationOption

WithProgress shows a progress bar clamped to the range [0, 1].

func WithSeverity

func WithSeverity(sev Severity) NotificationOption

WithSeverity sets the notification severity.

func WithTTL

func WithTTL(ttl time.Duration) NotificationOption

WithTTL sets the notification lifetime.

type Option

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

Option configures a Manager.

func ActionCellOpts

func ActionCellOpts(opts ...cell.Option) Option

ActionCellOpts sets the base styling for action labels.

func Anchor

func Anchor(p Placement) Option

Anchor sets the toast stack placement.

func AnimationDuration

func AnimationDuration(d time.Duration) Option

AnimationDuration sets how long entrance animations run.

func AnimationMode

func AnimationMode(a Animation) Option

AnimationMode sets the notification entrance animation.

func Border

func Border(ls linestyle.LineStyle, opts ...cell.Option) Option

Border sets the toast border style and optional base cell options.

func Borderless

func Borderless() Option

Borderless disables the toast border.

func Clock

func Clock(clock func() time.Time) Option

Clock sets the time source used for TTL and animation calculations.

func CustomPosition

func CustomPosition(fn PositionFunc) Option

CustomPosition sets a custom placement function and selects PlacementCustom.

func DefaultTTL

func DefaultTTL(ttl time.Duration) Option

DefaultTTL sets the lifetime used by notifications that do not set a TTL.

func DismissOnClick

func DismissOnClick(enabled bool) Option

DismissOnClick controls whether clicking a visible toast removes it.

func FillCellOpts

func FillCellOpts(opts ...cell.Option) Option

FillCellOpts sets the base styling for toast interior cells.

func Gap

func Gap(gap int) Option

Gap sets the number of cells between stacked notifications.

func Margin

func Margin(x, y int) Option

Margin sets the horizontal and vertical distance from the canvas edge.

func MaxMessageLines

func MaxMessageLines(count int) Option

MaxMessageLines sets the maximum message lines shown in each toast.

func MaxVisible

func MaxVisible(count int) Option

MaxVisible sets the maximum number of notifications drawn at once.

func MaxWidth

func MaxWidth(width int) Option

MaxWidth sets the largest toast width used during responsive layout.

func MessageCellOpts

func MessageCellOpts(opts ...cell.Option) Option

MessageCellOpts sets the base styling for toast message text.

func MinWidth

func MinWidth(width int) Option

MinWidth sets the smallest toast width used during responsive layout.

func MinimumSize

func MinimumSize(size image.Point) Option

MinimumSize sets the smallest canvas requested by the widget.

func NewestFirst

func NewestFirst(enabled bool) Option

NewestFirst controls whether the newest notifications are closest to the configured anchor.

func SeverityStyle

func SeverityStyle(sev Severity, style Style) Option

SeverityStyle replaces the visual style for a severity.

func Shadow

func Shadow(enabled bool, opts ...cell.Option) Option

Shadow enables or disables the one-cell toast drop shadow.

func SlideDirection

func SlideDirection(d Direction) Option

SlideDirection sets the edge used by AnimationSlide.

func Stack

func Stack(direction StackDirection) Option

Stack sets how multiple visible notifications are stacked.

func TitleCellOpts

func TitleCellOpts(opts ...cell.Option) Option

TitleCellOpts sets the base styling for toast titles.

func Width

func Width(width int) Option

Width sets the preferred toast width in terminal cells.

type Placement

type Placement int

Placement identifies the anchor point used for toast stacks.

const (
	// PlacementTopRight anchors notifications to the upper-right corner.
	PlacementTopRight Placement = iota
	// PlacementTopLeft anchors notifications to the upper-left corner.
	PlacementTopLeft
	// PlacementBottomRight anchors notifications to the lower-right corner.
	PlacementBottomRight
	// PlacementBottomLeft anchors notifications to the lower-left corner.
	PlacementBottomLeft
	// PlacementCenter anchors notifications near the center of the canvas.
	PlacementCenter
	// PlacementCustom delegates placement to a caller-provided PositionFunc.
	PlacementCustom
)

Placement values supported by Manager.

type PositionFunc

type PositionFunc func(canvas image.Rectangle, size image.Point, index int) image.Point

PositionFunc returns the top-left corner for a toast.

The canvas rectangle is the full drawing area, size is the toast's requested size, and index is the toast's index in the visible stack.

type Severity

type Severity int

Severity identifies the semantic style of a notification.

const (
	// SeverityInfo is the default informational notification style.
	SeverityInfo Severity = iota
	// SeveritySuccess is used for successful operations.
	SeveritySuccess
	// SeverityWarning is used for warnings and recoverable problems.
	SeverityWarning
	// SeverityError is used for failures and destructive outcomes.
	SeverityError
	// SeverityNeutral is used for low-emphasis notifications.
	SeverityNeutral
)

Severity values supported by Manager.

type StackDirection

type StackDirection int

StackDirection identifies how multiple notifications are stacked.

const (
	// StackAuto chooses a natural stack direction for the configured Placement.
	StackAuto StackDirection = iota
	// StackDown stacks later notifications downward from the anchor.
	StackDown
	// StackUp stacks later notifications upward from the anchor.
	StackUp
)

StackDirection values supported by Manager.

type Style

type Style struct {
	// Icon is drawn before the notification title when non-zero.
	Icon rune
	// Accent is the default accent color used when a more specific cell option
	// is not supplied.
	Accent cell.Color
	// BorderCellOpts styles the toast border.
	BorderCellOpts []cell.Option
	// FillCellOpts styles the toast interior fill cells.
	FillCellOpts []cell.Option
	// TitleCellOpts styles the notification title.
	TitleCellOpts []cell.Option
	// MessageCellOpts styles the notification message.
	MessageCellOpts []cell.Option
	// IconCellOpts styles the severity icon.
	IconCellOpts []cell.Option
	// ProgressCellOpts styles the optional progress bar.
	ProgressCellOpts []cell.Option
}

Style defines visual details for one notification severity.

type Surface

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

Surface is a reusable overlay widget that hosts toast managers at multiple placements.

Use Manager directly when an application needs one stack. Use Surface when a single widget should support multiple corners or a custom overlay point.

Implements widgetapi.Widget. This object is thread-safe.

func NewSurface

func NewSurface(opts ...SurfaceOption) (*Surface, error)

NewSurface returns a toast surface with one default placement registered.

func (*Surface) Clear

func (s *Surface) Clear()

Clear removes all notifications from every registered placement.

func (*Surface) ClearAt

func (s *Surface) ClearAt(p Placement)

ClearAt removes all notifications from one placement.

func (*Surface) Count

func (s *Surface) Count() int

Count returns the total number of notifications held by the surface.

func (*Surface) Draw

func (s *Surface) Draw(cvs *canvas.Canvas, meta *widgetapi.Meta) error

Draw implements widgetapi.Widget.

func (*Surface) Keyboard

func (s *Surface) Keyboard(k *terminalapi.Keyboard, meta *widgetapi.EventMeta) error

Keyboard implements widgetapi.Widget.

func (*Surface) Manager

func (s *Surface) Manager(p Placement) (*Manager, bool)

Manager returns the manager for a placement when one exists.

func (*Surface) Mouse

func (s *Surface) Mouse(event *terminalapi.Mouse, meta *widgetapi.EventMeta) error

Mouse implements widgetapi.Widget.

func (*Surface) Notify

func (s *Surface) Notify(title, message string, opts ...NotificationOption) string

Notify adds a notification to the surface's default placement.

func (*Surface) NotifyAt

func (s *Surface) NotifyAt(p Placement, title, message string, opts ...NotificationOption) string

NotifyAt adds a notification to the requested placement.

Built-in placements are created lazily. PlacementCustom must be registered first with Surface.Register or SurfacePlacement so it can provide a CustomPosition option.

func (*Surface) Options

func (s *Surface) Options() widgetapi.Options

Options implements widgetapi.Widget.

func (*Surface) Register

func (s *Surface) Register(p Placement, opts ...Option) error

Register creates or replaces the manager for a placement.

type SurfaceOption

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

SurfaceOption configures a Surface.

func DefaultPlacement

func DefaultPlacement(p Placement) SurfaceOption

DefaultPlacement sets the placement used by Surface.Notify.

func DefaultToastOptions

func DefaultToastOptions(opts ...Option) SurfaceOption

DefaultToastOptions sets options inherited by managers created by a Surface.

func SurfaceMinimumSize

func SurfaceMinimumSize(size image.Point) SurfaceOption

SurfaceMinimumSize sets the smallest canvas requested by a Surface.

func SurfacePlacement

func SurfacePlacement(p Placement, opts ...Option) SurfaceOption

SurfacePlacement pre-registers a placement on a Surface.

Directories

Path Synopsis
Binary toastdemo shows animated toast notifications in normal containers and modal windows.
Binary toastdemo shows animated toast notifications in normal containers and modal windows.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL