blo is a small and fast library to generate Ethereum identicons.
## Features
- π₯ **Small**: **[0.67 KB](https://bundlejs.com/?bundle&q=blo)** gzipped.
- π₯ **Fast**: **[more than 5x faster](#benchmark)** than the second fastest solution.
- π **Optimized**: Leverages SVG to generate compact and sharp images at any size.
- π **Simple**: Focuses on Ethereum identicons only, allowing for a simpler API.
- π **Typed**: Ships with [TypeScript definitions](#types).
- π« **Universal**: Compatible with browsers, [Bun](https://bun.sh/), and [Node.js](http://nodejs.org/).
- βοΈ **Standalone**: Zero dependencies.
## Library Comparison
| Library | Operations/sec[^1] | Size | Types | Environment[^2] | Rendering |
| ------------------------------------- | -----------------: | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------- | ---------------------------------------------- | --------: |
| blo | π₯ 403,226 | [](https://bundlejs.com/?bundle&q=blo) |  |  | SVG |
| ethereum-blockies-base64 | 2,191 | [](https://bundlejs.com/?bundle&q=ethereum-blockies-base64) |  |  | PNG |
| blockies-react-svg | 76,628 | [](https://bundlejs.com/?bundle&q=blockies-react-svg) |  |  | SVG |
| @download/blockies | 112 | [](https://bundlejs.com/?bundle&q=%6ead0a%2Fblockies) |  |  | Canvas |
| blockies-ts | 137 | [](https://bundlejs.com/?bundle&q=blockies-ts) |  |  | Canvas |
| react-blockies | 4,693 | [](https://bundlejs.com/?bundle&q=react-blockies) |  |  | Canvas |
[^1]: These numbers are based on the [#benchmark](#benchmark) results (higher is better).
[^2]: The term βallβ refers to libraries that are framework agnostic and that run in browsers, Bun and Node.js.
## Getting Started
```sh
npm i -S blo
pnpm add blo
yarn add blo
```
```ts
import { blo } from "blo";
img.src = blo("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045");
```
### React / Vue / Others
blo is fast enough to not require memoization or async rendering for common use cases.
```tsx
function AddressIcon({ address }: { address: `0x${string}` }) {
return (
);
}
```
## API
blo(address: Address, size = 64): string
Get a data URI string representing the identicon as an SVG image.
The `size` paramater shouldnβt usually be needed, as the image will stay sharp no matter what the size of the `img` element is.
Example:
```ts
import { blo } from "blo";
img.src = blo(address); // size inside the SVG defaults to 64px
img2.src = blo(address, 24); // set it to 24px
```
bloSvg(address: Address, size = 64): string
Same as above except it returns the SVG code instead of a data URI string.
bloImage(address: Address): BloImage
Get a `BloImage` data structure that can be used to render the image in different formats.
Check the [Bun](./demos/bun/index.ts) and [Node](./demos/node/index.js) demos to see usage examples.
## Types
The library ships with TypeScript types included.
```ts
// BloImage contains the data needed to render an icon.
export type BloImage = [BloImageData, Palette];
// 4x8 grid of the image left side, as 32 PaletteIndex items.
// The right side is omitted as it's a mirror of the left side.
export type BloImageData = Uint8Array;
// Colors used by a given icon.
export type Palette = [
Hsl, // background
Hsl, // color
Hsl, // spot
];
// Points to one of the three Palette colors.
export type PaletteIndex =
| 0 // background
| 1 // color
| 2; // spot
// A color in the HSL color space.
// [0]: 0-360 (hue)
// [1]: 0-100 (saturation)
// [2]: 0-100 (lightness)
export type Hsl = Uint16Array;
// An Ethereum address.
export type Address = `0x${string}`;
```
## Acknowledgements
- blo is a modernized version of [ethereum-blockies-base64](https://github.com/MyCryptoHQ/ethereum-blockies-base64), which I think was based on [ethereum/blockies](https://github.com/ethereum/blockies).
- This README style was heavily inspired by [colord](https://github.com/omgovich/colord).
- The visual was made in collaboration with [@dizzypaty](https://twitter.com/dizzypaty) π.
## FAQ
### Does it follow the exact same algorithm as Etherscan, MetaMask and others?
Yes.
### Does it work with ENS names?
No it only works with Ethereum addresses, but you can resolve the ENS name to an address (e.g. with [wagmi](https://wagmi.sh/core/actions/fetchEnsAddress)) and pass the result to blo.
### Can blo render other formats than SVG?
You can render to any format you want by using the `bloImage()` function, which returns a data structure (see [API](#api) above). Check out the [Bun](./demos/bun) and [Node](./demos/node) demos for examples of rendering an identicon in the terminal.
### Can it be used to generate other types of identicons?
blo only focuses on the Ethereum identicons algorithm but you can use it with any data, just prefix it with `0x` to fulfill the expected `Address` type if you are using TypeScript.
### Why is it named blo?
blo is short for blockies, which is the name of [the original library](https://github.com/ethereum/blockies) it is based on.
## Benchmark
This benchmark attempts to use the fastest possible way to generate a data URI representing an Ethereum identicon, for each of the libraries compared.
```
$ bun benchmark
clk: ~2.39 GHz
cpu: AMD Ryzen 7 PRO 7840U w/ Radeon 780M Graphics
runtime: bun 1.2.5 (x64-linux)
benchmark avg (min β¦ max) p75 / p99 (min β¦ top 1%)
------------------------------------------- -------------------------------
blo 2.48 Β΅s/iter 2.55 Β΅s 3.13 Β΅s β ββββββββββ
@download/blockies 8.95 ms/iter 9.17 ms 10.63 ms βββββββββββ
blockies-react-svg 13.05 Β΅s/iter 14.39 Β΅s 14.53 Β΅s βββββββββββ
blockies-ts 7.28 ms/iter 7.41 ms 8.48 ms βββββββββββ
ethereum-blockies-base64 456.49 Β΅s/iter 501.59 Β΅s 882.05 Β΅s βββββββββββ
react-blockies 213.03 Β΅s/iter 220.64 Β΅s 268.34 Β΅s βββββββββββ
summary
blo
5.26x faster than blockies-react-svg
85.78x faster than react-blockies
183.82x faster than ethereum-blockies-base64
2929.86x faster than blockies-ts
3603.5x faster than @download/blockies
```
See [./benchmark](./benchmark) for the benchmark code.
## License
[MIT](./LICENSE)