https://github.com/sig-0/boring-avatars-go
A Go library & server for generating & serving Boring Avatars identicons. Based on the original JS implementation.
https://github.com/sig-0/boring-avatars-go
avatars boring boring-avatars identicons
Last synced: 6 months ago
JSON representation
A Go library & server for generating & serving Boring Avatars identicons. Based on the original JS implementation.
- Host: GitHub
- URL: https://github.com/sig-0/boring-avatars-go
- Owner: sig-0
- License: apache-2.0
- Created: 2025-07-04T14:21:40.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-11-18T12:31:39.000Z (8 months ago)
- Last Synced: 2025-11-18T15:39:32.898Z (8 months ago)
- Topics: avatars, boring, boring-avatars, identicons
- Language: Go
- Homepage: https://boringavatars.com/
- Size: 424 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
## Overview
Generate deterministic, SVG-only Boring Avatars (Beam, Bauhaus, Marble, Pixel, Ring and Sunset) in Go - ready for
servers, CDNs, CLI tools or front-ends.
## NOTICE - this is a fork!
This Go library is a port of the original JS library for generating Boring Avatars.
It would not exist, without the work and dedication of the Boring Designers team:
https://github.com/boringdesigners/boring-avatars/tree/master
Please consider supporting their project with a star and a donation!
https://boringavatars.com/
## Features
- Six sleek Boring Avatar styles.
- Deterministic: same (style, name, palette) -> identical SVG.
- Plug-and-play HTTP server with Chi + functional middleware options.
## Installing
```shell
go get -u github.com/sig-0/boring-avatars-go
```
## Library usage
```go
package main
import (
"fmt"
"github.com/sig-0/boring-avatars-go/avatars"
)
func main() {
svg := avatars.Generate(
avatars.Marble, // style
"Amelia Earhart", // name / seed
[]string{"#0a0310", "#49007e", "#ff005b", "#ff7d10", "#ffb238"}, // optional custom palette
80, // size in px
false, // square mask? (false = round)
)
fmt.Println(svg) //
}
```
## Embedded HTTP server
```go
package main
import (
"context"
"log"
"log/slog"
"github.com/sig-0/boring-avatars-go/server"
)
func main() {
srv, _ := server.New(
server.WithLogger(slog.Default()), // custom logger
// optional middlewares
)
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
log.Fatal(srv.Serve(ctx)) // blocking
}
```
### REST API
The root endpoint of the bundled HTTP server allows you to generate Boring Avatar SVGs.
You can configure the CORS policy in the server configuration, by running the `generate` command and editing the file.
#### Paid Service
You can run the bundled server on your own, or you can use the paid service the good folks over at Boring Designers
already provide:
https://boringavatars.com/api-service
Their team handles all the setup and heavy lifting for your endpoint, so you can go back to doing the important stuff
(building your app!).
#### Base endpoint
```text
GET /?name={NAME}&variant={VARIANT}&size={SIZE}&colors={COLORS}&square=true
```
All parameters are optional unless otherwise noted.
#### Params
##### `name` (optional)
A string used to generate a unique avatar (e.g., username, email, or ID).
```html
```
##### `variant` (optional)
Specifies the visual style of the avatar. Options include:
- `marble`
- `beam`
- `pixel`
- `sunset`
- `ring`
- `bauhaus`
```html
```
##### `size` (optional)
The width and height of the avatar in pixels (SVG format).
```html
```
##### `colors` (optional)
A comma-separated list of up to 6 hex color values used to style the avatar.
```html
```
##### `square` (optional)
Forces the avatar to render in a square format. Accepts `true` or `false`.
```html
```
### Random Avatars
If you omit all query parameters, the endpoint returns a randomly generated avatar using the default size (`80x80`) and
the `marble` variant:
```html
```