https://github.com/indaco/goaster
A configurable and themeable toast notification component for Go web applications.
https://github.com/indaco/goaster
component go golang server-side templ toast-notifications ui-component
Last synced: 10 months ago
JSON representation
A configurable and themeable toast notification component for Go web applications.
- Host: GitHub
- URL: https://github.com/indaco/goaster
- Owner: indaco
- License: mit
- Created: 2024-02-27T12:19:50.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-05-07T06:54:17.000Z (over 1 year ago)
- Last Synced: 2025-02-27T08:53:53.383Z (11 months ago)
- Topics: component, go, golang, server-side, templ, toast-notifications, ui-component
- Language: Go
- Homepage:
- Size: 8.83 MB
- Stars: 27
- Watchers: 4
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
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](https://github.com/a-h/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:
```sh
go get github.com/indaco/goaster@latest
```
## Usage
Import `goaster` module into your project:
```go
import "github.com/indaco/goaster"
```
### Creating a Toaster
Initialize a `Toaster` with default settings:
```go
toaster := goaster.NewToaster()
```
or customize the toaster with options:
```go
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 `GoasterJS`component into a `template.HTML` value.
> **Note**: refer to the [Examples](#examples) section to see how to use `goaster` with `templ` and `html/template`.
### Displaying Toast Messages
Display different levels of toast messages:
```go
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:
```go
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:
```go
toaster := goaster.NewToaster(
goaster.WithIcon(toast.SuccessLevel, "..."),
goaster.WithIcon(toast.ErrorLevel, "..."),
)
```
## 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](./docs/css-props.md) document.
## Examples
- [use with `a-h/templ` template](_examples/a-h-templ-single-toast)
- [multiple messages with `a-h/templ`](_examples/a-h-templ-multiple-toasts)
- [use with `template/html`](_examples/go-html-template-single-toast)
- [multiple messages with `template/html`](_examples/go-html-template-multiple-toasts)
- [theming](_examples/theming)
- [variants](_examples/variants)
- [custom icons](_examples/custom-icons)
- [custom animations](_examples/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](https://www.jetify.com/devbox) along with the provided `devbox.json` configuration file.
1. Install devbox by following the instructions in the [devbox documentation](https://www.jetify.com/devbox/docs/installing_devbox/).
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:
```bash
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.