goaster
goaster copied to clipboard
A configurable and themeable toast notification component for Go web applications.
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
andAccentDark
. - 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.
![Image](https://github.com/indaco/goaster/raw/main/statics/demo.gif)
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 theGoasterCSS
component into atemplate.HTML
value. -
GoasterJSToGoHTML
: render theGoasterJS
component into atemplate.HTML
value.
Note: refer to the Examples section to see how to use
goaster
withtempl
andhtml/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.
- Install devbox by following the instructions in the devbox documentation.
- Clone this repository to your local machine.
- Navigate to the root directory of the cloned repository.
- Run
devbox install
to install all packages mentioned in thedevbox.json
file. - Run
devbox shell
to start a new shell with access to the environment. - 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.