goaster

README

goaster

toast notification component for Go web applications.

Features • Installation • Usage • Custom Icons • Theming • Examples • Contributing

A configurable, themeable and non-intrusive server-rendered toast notification component for Go web applications. Built with templ library for seamless integration with Go-based web frontends.

Features

• No External Dependencies: Built with native Go and the templ library—no JavaScript or frontend dependencies required.
• Multiple Toasts: Supports displaying multiple toast notifications simultaneously.
• Highly Configurable: Customize appearance (bordered, rounded), behavior, and position to fit your UI.
• Variants: Includes style variants such as Accent, AccentLight, and AccentDark.
• Themeable: Easily theme your toasts using CSS variables to match your app’s design.
• Icon Support: Comes with default SVG icons for common toast types (success, error, info, etc.)—or use your own.
• Flexible Positioning: Display toast messages in any corner (top-right, bottom-left, etc.).
• Auto-Dismiss Progress Bar: Visual progress indicator for toast duration (when auto-dismiss is enabled).
• Smooth Animations:
  • Built-in Animations: Default entrance and exit transitions.
  • Custom Animations: Define your own via CSS variables or external animation libraries.
  • Animation Control: Fine-tune timing, easing, delay, and effects with CSS variables.
  • Disable Option: Disable all animations when needed (e.g., for accessibility or testing).

Installation

Ensure your project is using Go Modules.

To install the module, use the go get command:

go get github.com/indaco/goaster@latest

Usage

Import goaster module into your project:

import "github.com/indaco/goaster"

Creating a Toaster

You can create a Toaster instance using one of the following approaches:

1. Use default settings

func HandleSingle(w http.ResponseWriter, r *http.Request) {
  toaster := goaster.ToasterDefaults()
  templ.Handler(pages.HomePage(toaster)).ServeHTTP(w, r)
}

2. Use functional options

Customize the toaster behavior on creation:

func HandleSingle(w http.ResponseWriter, r *http.Request) {
  toaster := goaster.NewToaster(
    goaster.WithBorder(false),
    goaster.WithPosition(goaster.TopRight),
    goaster.WithAutoDismiss(false),
    // ...
  )
  templ.Handler(pages.HomePage(toaster)).ServeHTTP(w, r)
}

3. Use the builder pattern

More readable when chaining multiple settings:

func HandleSingle(w http.ResponseWriter, r *http.Request) {
  toaster := goaster.NewToasterBuilder().WithAutoDismiss(false).Build()
  templ.Handler(pages.HomePage(toaster)).ServeHTTP(w, r)
}

Displaying Toast Messages

In your templ pages, call the appropriate method on the Toaster instance:

templ UserPage(toaster *goaster.Toaster) {
  @toaster.Success("Operation completed successfully.")
}

Each toast level has a corresponding method:

@toaster.Default("Sample message.")
@toaster.Error("An error occurred.")
@toaster.Info("Here's some information.")
@toaster.Warning("This is a warning message.")

💡 Toast messages are displayed when @toaster.<Level>() is called in your template.

Queueing Toast Messages from Go

You can queue multiple toast messages in your handler:

toaster.PushDefault("Sample message.")
toaster.PushSuccess("Operation completed successfully.")
toaster.PushError("An error occurred.")
toaster.PushInfo("Here's some information.")
toaster.PushWarning("This is a warning message.")

Then render them all in your templ page:

templ UserPage(toaster *goaster.Toaster) {
  @toaster.RenderAll()
}

Custom Icons

Specify custom SVG icons for each toast level:

toaster := goaster.NewToaster(
   goaster.WithIcon(toast.SuccessLevel, "<svg>...</svg>"),
   goaster.WithIcon(toast.ErrorLevel, "<svg>...</svg>"),
)

Theming

Customizing the appearance of goaster notifications to align with your design preferences is both straightforward and flexible, accomplished by using CSS custom properties (CSS variables) prefixed with gtt.

See the CSS Custom Properties reference for full details.

Use with Go's template/html

To facilitate integration with Go's template/html standard library, goaster includes a dedicated HTMLGenerator type to seamlessly integrate toast notifications into web applications built with Go's html/template standard library.

Note: See the Examples section to learn how to use goaster with templ and html/template.

Examples

👉 Check out the examples with setup instructions

Contributing

Contributions are welcome!

See the Contributing Guide for setup instructions.

License

This project is licensed under the MIT License – see the LICENSE file for details.

Documentation

Overview

Package goaster - Helpers for using toasts with `template/html`

Index

• Constants
• type HTMLGenerator
  • func NewHTMLGenerator() *HTMLGenerator
  • func (g *HTMLGenerator) DisplayAll(t *Toaster) (template.HTML, error)
• type Icon
  • func (i Icon) String() string
• type Level
  • func (l Level) String() string
• type Option
  • func WithAnimation(animation bool) Option
  • func WithAutoDismiss(autoDismiss bool) Option
  • func WithBorder(border bool) Option
  • func WithButton(button bool) Option
  • func WithIcon(level Level, iconSVG string) Option
  • func WithPosition(position Position) Option
  • func WithProgressBar(progressbar bool) Option
  • func WithRounded(rounded bool) Option
  • func WithShowIcon(icon bool) Option
  • func WithVariant(variant Variant) Option
• type Position
  • func (p Position) String() string
• type Queue
  • func NewQueue() *Queue
  • func (q *Queue) Dequeue() (Toast, error)
  • func (q *Queue) Enqueue(toast Toast)
  • func (q *Queue) GetMessagesAndDequeue() []Toast
  • func (q *Queue) IsEmpty() bool
  • func (q *Queue) Size() int
  • func (q *Queue) String() string
• type Toast
  • func NewToast(msg string, level Level) Toast
• type Toaster
  • func NewToaster(options ...Option) *Toaster
  • func ToasterDefaults() *Toaster
  • func (t *Toaster) Default(message string) templ.Component
  • func (t *Toaster) Error(message string) templ.Component
  • func (t *Toaster) Info(message string) templ.Component
  • func (t *Toaster) PushDefault(message string)
  • func (t *Toaster) PushError(message string)
  • func (t *Toaster) PushInfo(message string)
  • func (t *Toaster) PushSuccess(message string)
  • func (t *Toaster) PushWarning(message string)
  • func (t *Toaster) Queue() *Queue
  • func (t *Toaster) RenderAll() templ.Component
  • func (t *Toaster) Success(message string) templ.Component
  • func (t *Toaster) ToViewModel() viewmodel.ToasterViewModel
  • func (t *Toaster) Warning(message string) templ.Component
• type ToasterBuilder
  • func NewToasterBuilder() *ToasterBuilder
  • func (b *ToasterBuilder) Build() *Toaster
  • func (b *ToasterBuilder) WithAnimation(animation bool) *ToasterBuilder
  • func (b *ToasterBuilder) WithAutoDismiss(autoDismiss bool) *ToasterBuilder
  • func (b *ToasterBuilder) WithBorder(border bool) *ToasterBuilder
  • func (b *ToasterBuilder) WithButton(button bool) *ToasterBuilder
  • func (b *ToasterBuilder) WithIcon(level Level, iconSVG string) *ToasterBuilder
  • func (b *ToasterBuilder) WithOptions(options ...Option) *ToasterBuilder
  • func (b *ToasterBuilder) WithPosition(position Position) *ToasterBuilder
  • func (b *ToasterBuilder) WithProgressBar(progressBar bool) *ToasterBuilder
  • func (b *ToasterBuilder) WithRounded(rounded bool) *ToasterBuilder
  • func (b *ToasterBuilder) WithShowIcon(showIcon bool) *ToasterBuilder
  • func (b *ToasterBuilder) WithVariant(variant Variant) *ToasterBuilder
• type Variant
  • func (v Variant) String() string

Constants

const (
	TopRight     = Position("top-right")
	TopLeft      = Position("top-left")
	TopCenter    = Position("top-center")
	BottomRight  = Position("bottom-right")
	BottomLeft   = Position("bottom-left")
	BottomCenter = Position("bottom-center")
)

Predefined toast positions

const (
	Accent      = Variant("accent")
	AccentLight = Variant("accent-light")
	AccentDark  = Variant("accent-dark")
)

Predefined style variants

Types

type HTMLGenerator

type HTMLGenerator struct{}

HTMLGenerator provides functions for generating HTML code for toast notifications.

func NewHTMLGenerator

func NewHTMLGenerator() *HTMLGenerator

NewHTMLGenerator creates a new instance of HTMLGenerator.

func (*HTMLGenerator) DisplayAll

func (g *HTMLGenerator) DisplayAll(t *Toaster) (template.HTML, error)

DisplayAll generates HTML code for displaying the toast and returns it as a template.HTML.

type Icon

type Icon string

Icon is a named type for SVG string representations.

func (Icon) String

func (i Icon) String() string

type Level

type Level string

Level represents the severity level of a toast notification.

const (
	DefaultLevel Level = "default"
	SuccessLevel Level = "success"
	ErrorLevel   Level = "error"
	WarningLevel Level = "warning"
	InfoLevel    Level = "info"
)

Predefined toast levels

func (Level) String

func (l Level) String() string

type Option

type Option func(*Toaster)

Option represents a configuration function that modifies a Toaster instance.

func WithAnimation

func WithAnimation(animation bool) Option

WithAnimation configures whether the toast should use animations.

func WithAutoDismiss

func WithAutoDismiss(autoDismiss bool) Option

WithAutoDismiss configures whether the toast should auto-dismiss.

func WithBorder

func WithBorder(border bool) Option

WithBorder configures the presence of a border around the toast.

func WithButton

func WithButton(button bool) Option

WithButton configures whether the toast should display the close button.

func WithIcon

func WithIcon(level Level, iconSVG string) Option

WithIcon sets the icon for a specific toast level.

func WithPosition

func WithPosition(position Position) Option

WithPosition sets the position of the toast notifications.

func WithProgressBar

func WithProgressBar(progressbar bool) Option

WithProgressBar configures whether the toast should display a progressbar.

func WithRounded

func WithRounded(rounded bool) Option

WithRounded configures the presence of a rounded border around the toast.

func WithShowIcon

func WithShowIcon(icon bool) Option

WithShowIcon configures whether the toast should display the icon.

func WithVariant

func WithVariant(variant Variant) Option

WithVariant configures the style variant for the toast.

type Position

type Position string

Position represents the placement for the toast container.

func (Position) String

func (p Position) String() string

type Queue

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

func NewQueue

func NewQueue() *Queue

func (*Queue) Dequeue

func (q *Queue) Dequeue() (Toast, error)

Dequeue removes and returns the first element of the queue. If the queue is empty, it returns -1 and an error.

func (*Queue) Enqueue

func (q *Queue) Enqueue(toast Toast)

Enqueue adds an element to the end of the queue.

func (*Queue) GetMessagesAndDequeue

func (q *Queue) GetMessagesAndDequeue() []Toast

GetMessagesAndDequeue returns a slice of Toast messages from the queue. It dequeues messages from the queue until it's empty. **NOTE**: in a-h/templ only `for...range` is a valid `for`loop.

func (*Queue) IsEmpty

func (q *Queue) IsEmpty() bool

IsEmpty checks if the queue is empty.

func (*Queue) Size

func (q *Queue) Size() int

Size returns the number of elements in the queue.

func (*Queue) String

func (q *Queue) String() string

String returns a string representation of the queue.

type Toast

type Toast struct {
	Message string
	Level   Level
}

Toast holds a message and its level.

func NewToast

func NewToast(msg string, level Level) Toast

NewToast creates a new Toast with a message and level.

type Toaster

type Toaster struct {
	Variant     Variant          // Style variant
	Border      bool             // Display border
	Rounded     bool             // Use rounded corners
	ShowIcon    bool             // Show icon
	Button      bool             // Show close button
	AutoDismiss bool             // Auto-dismiss after timeout
	Animation   bool             // Animate entrance/exit
	ProgressBar bool             // Show progress bar
	Position    Position         // Screen position
	Icons       map[Level]string // Custom icons
	// contains filtered or unexported fields
}

Toaster holds configuration for toast notifications.

func NewToaster

func NewToaster(options ...Option) *Toaster

NewToaster creates a Toaster instance with default settings and applies any given options.

func ToasterDefaults

func ToasterDefaults() *Toaster

func (*Toaster) Default

func (t *Toaster) Default(message string) templ.Component

Default displays a default toast notification.

func (*Toaster) Error

func (t *Toaster) Error(message string) templ.Component

Error displays an error toast notification.

func (*Toaster) Info

func (t *Toaster) Info(message string) templ.Component

Info displays an info toast notification.

func (*Toaster) PushDefault

func (t *Toaster) PushDefault(message string)

PushDefault adds a default toast notification.

func (*Toaster) PushError

func (t *Toaster) PushError(message string)

PushError adds an error toast notification.

func (*Toaster) PushInfo

func (t *Toaster) PushInfo(message string)

PushInfo adds an info toast notification.

func (*Toaster) PushSuccess

func (t *Toaster) PushSuccess(message string)

PushSuccess adds a success toast notification.

func (*Toaster) PushWarning

func (t *Toaster) PushWarning(message string)

PushWarning adds a warning toast notification.

func (*Toaster) Queue

func (t *Toaster) Queue() *Queue

Queue returns the internal toast queue.

func (*Toaster) RenderAll

func (t *Toaster) RenderAll() templ.Component

RenderAll prints all the toast notifications in the queue.

func (*Toaster) Success

func (t *Toaster) Success(message string) templ.Component

Success displays a success toast notification.

func (*Toaster) ToViewModel

func (t *Toaster) ToViewModel() viewmodel.ToasterViewModel

func (*Toaster) Warning

func (t *Toaster) Warning(message string) templ.Component

Warning displays a warning toast notification.

type ToasterBuilder

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

ToasterBuilder builds a Toaster instance using chainable methods.

func NewToasterBuilder

func NewToasterBuilder() *ToasterBuilder

NewToasterBuilder creates a new builder with default values.

func (*ToasterBuilder) Build

func (b *ToasterBuilder) Build() *Toaster

Build finalizes and returns the configured Toaster instance.

func (*ToasterBuilder) WithAnimation

func (b *ToasterBuilder) WithAnimation(animation bool) *ToasterBuilder

func (*ToasterBuilder) WithAutoDismiss

func (b *ToasterBuilder) WithAutoDismiss(autoDismiss bool) *ToasterBuilder

func (*ToasterBuilder) WithBorder

func (b *ToasterBuilder) WithBorder(border bool) *ToasterBuilder

func (*ToasterBuilder) WithButton

func (b *ToasterBuilder) WithButton(button bool) *ToasterBuilder

func (*ToasterBuilder) WithIcon

func (b *ToasterBuilder) WithIcon(level Level, iconSVG string) *ToasterBuilder

func (*ToasterBuilder) WithOptions

func (b *ToasterBuilder) WithOptions(options ...Option) *ToasterBuilder

func (*ToasterBuilder) WithPosition

func (b *ToasterBuilder) WithPosition(position Position) *ToasterBuilder

func (*ToasterBuilder) WithProgressBar

func (b *ToasterBuilder) WithProgressBar(progressBar bool) *ToasterBuilder

func (*ToasterBuilder) WithRounded

func (b *ToasterBuilder) WithRounded(rounded bool) *ToasterBuilder

func (*ToasterBuilder) WithShowIcon

func (b *ToasterBuilder) WithShowIcon(showIcon bool) *ToasterBuilder

func (*ToasterBuilder) WithVariant

func (b *ToasterBuilder) WithVariant(variant Variant) *ToasterBuilder

type Variant

type Variant string

Variant represents a style variant for the toast component.

func (Variant) String

func (v Variant) String() string