goaster

     

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, requiring no external frontend dependencies.
• Multiple Toasts: Support to display multiple toast notifications.
• Configurable: Customize appearance (bordered, rounded), behavior, and position.
• Variants: Provide toast style variants like Accent, AccentLight and AccentDark.
• Themeable: Use CSS variables to theme your toasts to match your application's design.
• Icon Support: Include default SVG icons for various toast levels (such as success, error, info, etc.), allowing you to use your preferred icons.
• Positioning: Flexible positioning of toast messages (top-right, bottom-left, etc.).
• Progress Bar for Auto-Dismiss: A visual progress bar indicates the countdown until the toast will automatically dismiss (with auto-dismiss enabled only).
• Animations: Entrance and exit animations for toast notifications.
  • Default Animations: built-in animations for toasts appearing and disappearing.
  • Custom Animations: Customize animations via CSS variables or integrate with external CSS animation libraries.
  • Animation Control: Full control over animation timing, easing, delay and effects, via CSS variables.
  • Disable Animations Option: Ability to completely disable animations, providing flexibility for different application needs and user preferences.

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

Initialize a Toaster with default settings:

toaster := goaster.NewToaster()

or customize the toaster with options:

toaster := goaster.NewToaster(
   goaster.WithBorder(false),
   goaster.WithPosition(goaster.TopRight),
   goaster.WithAutoDismiss(false)
   // ...
)

Add goester CSS and Javascript

goaster leverages the templ library's features, including CSS Components and JavaScript Templates, to encapsulate all necessary styling and functionality without relying on external dependencies.

• GoasterCSS: it supplies the required CSS, encapsulating the visual design and layout specifics of the toast notifications.
• GoasterJS: it provides the JavaScript logic essential for dynamic behaviors such as displaying, hiding, and managing toast notifications.

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.

3 methods, acting as wrappers to the templ's templ.ToGoHTML, generate the necessary HTML to be embedded them into server-rendered pages:

• GoasterCSSToGoHTML: render the GoasterCSS component into a template.HTML value.
• GoasterJSToGoHTML: render the GoasterJScomponent into a template.HTML value.

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

Displaying Toast Messages

Display different levels of toast messages:

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.")

Add Toast Messages to the queue and display them

Multiple toast messages in the queue:

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.")

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. For a comprehensive list of CSS custom properties, along with their default values and descriptions, please consult the tabber CSS custom Props document.

Examples

• use with a-h/templ template
• multiple messages with a-h/templ
• use with template/html
• multiple messages with template/html
• theming
• variants
• custom icons
• custom animations

Contributing

Contributions are welcome! Feel free to open an issue or submit a pull request.

Development Environment Setup

To set up a development environment for this repository, you can use devbox along with the provided devbox.json configuration file.

1. Install devbox by following the instructions in the devbox documentation.
2. Clone this repository to your local machine.
3. Navigate to the root directory of the cloned repository.
4. Run devbox install to install all packages mentioned in the devbox.json file.
5. Run devbox shell to start a new shell with access to the environment.
6. Once the devbox environment is set up, you can start developing, testing, and contributing to the repository.

Using Makefile

Additionally, you can make use of the provided Makefile to run various tasks:

make build       # The main build target
make examples    # Process templ files in the _examples folder
make templ       # Process TEMPL files
make test        # Run go tests
make help        # Print this help message

License

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