goaster

toast notification component for Go web applications.

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

Features

• No External Dependencies: Built with native Go and the templ library - no JavaScript required.
• Multiple Toasts: Display several notifications simultaneously.
• Configurable: Control appearance (border, rounded), behavior, and position.
• Variants: Accent, AccentLight, AccentDark, Filled, Outlined, Soft, Minimal, Brutalist, Retro, and Neon.
• Themeable: Style with CSS variables to match your app's design.
• Icon Support: Default SVG icons for common toast types - or use your own.
• Flexible Positioning: Place toasts in any corner of the screen.
• Auto-Dismiss Progress Bar: Visual countdown indicator for auto-dismissed toasts.
• Smooth Animations: Built-in entrance/exit transitions, fully controllable via CSS variables. Can be disabled.

Installation

go get github.com/indaco/goaster@latest

Usage

import "github.com/indaco/goaster"

Creating a Toaster

1. Default settings

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

2. Functional options

func HandleSingle(w http.ResponseWriter, r *http.Request) {
  toaster := goaster.NewToaster(
    goaster.WithVariant(goaster.Filled),
    goaster.WithBorder(false),
    goaster.WithRounded(true),
    goaster.WithShowIcon(true),
    goaster.WithButton(true),
    goaster.WithAutoDismiss(false),
    goaster.WithAnimation(true),
    goaster.WithProgressBar(false),
    goaster.WithPosition(goaster.TopRight),
  )
  templ.Handler(pages.HomePage(toaster)).ServeHTTP(w, r)
}

Options

Option	Description	Default
WithVariant(Variant)	Style variant (Accent, Filled, Neon, etc.)	(none)
WithBorder(bool)	Display border around the toast	true
WithRounded(bool)	Use rounded corners	true
WithShowIcon(bool)	Show the toast icon	true
WithButton(bool)	Show the close button	true
WithAutoDismiss(bool)	Auto-dismiss after timeout	true
WithAnimation(bool)	Enable entrance/exit animations	true
WithProgressBar(bool)	Show auto-dismiss progress bar	true
WithPosition(Position)	Screen position (TopRight, BottomLeft, etc.)	BottomRight
WithIcon(Level, string)	Custom SVG icon for a toast level	built-in icons

3. Builder pattern

func HandleSingle(w http.ResponseWriter, r *http.Request) {
  toaster := goaster.NewToasterBuilder().
    WithVariant(goaster.Neon).
    WithBorder(true).
    WithRounded(true).
    WithAutoDismiss(false).
    WithPosition(goaster.TopRight).
    Build()
  templ.Handler(pages.HomePage(toaster)).ServeHTTP(w, r)
}

Displaying Toast Messages

In your templ template, call the method for the desired level:

templ UserPage(toaster *goaster.Toaster) {
  @toaster.Default("Sample message.")
  @toaster.Success("Operation completed successfully.")
  @toaster.Error("An error occurred.")
  @toaster.Info("Here's some information.")
  @toaster.Warning("This is a warning message.")
}

Queueing Multiple Toasts

To display multiple toasts, queue them 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

Override the default icon for any toast level:

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

Theming

Theme goaster using CSS custom properties prefixed with gtt. See the CSS Custom Properties reference for full details.

html/template Integration

goaster includes HTMLGenerator for use with Go's html/template:

func HandlePage(w http.ResponseWriter, r *http.Request) {
  toaster := goaster.ToasterDefaults()
  toaster.PushSuccess("Operation completed.")

  gen := goaster.NewHTMLGenerator()
  toastHTML, err := gen.DisplayAll(r.Context(), toaster)
  if err != nil {
    http.Error(w, err.Error(), http.StatusInternalServerError)
    return
  }

  tmpl.Execute(w, map[string]any{
    "Toasts": toastHTML,
  })
}

Examples

See the examples for a complete showcase with setup instructions.

Contributing

See the Contributing Guide.

License

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