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.