Features

• 🐥 Small: 0.7 kB gzipped, even less with tree shaking.
• 💥 Fast: more than 9x faster than other blockies libraries.
• 🔍 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.
• 👫 Universal: Compatible with browsers, Bun, and Node.js.
• ☁️ Standalone: Zero dependencies.

Library Comparison

| Library | Operations/sec[^1] | Size | Types | Environment[^2] | Rendering | | ------------------------------------- | -----------------: | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------- | ---------------------------------------------- | --------: | | blo | 💥 418,951 | | | | SVG | | blo/wasm (experimental) | 💥💥 973,137 | [^3] | | | SVG | | ethereum-blockies-base64 | 1,330 | | | | PNG | | blockies-react-svg | 43,088 | | | | SVG | | @download/blockies | 66 | | | | Canvas | | blockies-ts | 104 | | | | Canvas | | react-blockies | 3,927 | | | | Canvas |

[^1]: Operations/sec are calculated from the average times in the benchmark below (higher is better). Wasm initialization is excluded. [^2]: The term “all” refers to libraries that are framework agnostic and that run in browsers, Bun and Node.js. [^3]: Measured locally with esbuild and gzip, importing blo and init from blo/wasm.

Getting Started

npm i -S blo
pnpm add blo
yarn add blo

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.

function AddressIcon({ address }: { address: `0x${string}` }) {
  return (
    <img
      alt={address}
      src={blo(address)}
    />
  );
}

API

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:

import { blo } from "blo";

img.src = blo(address); // size inside the SVG defaults to 64px
img2.src = blo(address, 24); // set it to 24px

Same as above except it returns the SVG code instead of a data URI string.

Get a BloImage data structure that can be used to render the image in different formats.

Check the Bun and Node demos to see usage examples.

Experimental Wasm

An experimental Rust/Wasm version is available through blo/wasm, with the same blo(), bloSvg(), and bloImage() API:

import { blo, init } from "blo/wasm";

init(); // Optional: prepare Wasm synchronously ahead of the first call.
img.src = blo("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045");

The first call initializes automatically. The binary is embedded, so no await or separate download is needed. This version adds bundle and startup costs; see the experiment for details and benchmarks.

Types

The library ships with TypeScript types included.

// 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, which I think was based on ethereum/blockies.
• This README style was heavily inspired by colord.
• The visual was made in collaboration with @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) 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 above). Check out the Bun and 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 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. Wasm is initialized before measurement.

Run pnpm run build and pnpm --dir benchmark install before running the comparison.

$ pnpm --dir benchmark bench

clk: ~2.21 GHz
cpu: AMD Ryzen 7 PRO 7840U w/ Radeon 780M Graphics
runtime: bun 1.4.0 (x64-linux)

benchmark                   avg (min … max) p75 / p99    (min … top 1%)
------------------------------------------- -------------------------------
blo                            2.39 µs/iter   2.47 µs   3.85 µs ▃█▄▃▂▁▁▁▁▁▁
blo/wasm                       1.03 µs/iter   1.11 µs   1.41 µs ▂██▆▃▅▄▂▂▁▁
@download/blockies            15.25 ms/iter  15.06 ms  27.17 ms ▅▅█▁▁▁▂▁▁▁▁
blockies-react-svg            23.21 µs/iter  26.03 µs  75.90 µs ▂█▅▃▂▂▁▁▁▁▁
blockies-ts                    9.66 ms/iter   9.81 ms  12.53 ms ▄▆█▆▃▁▂▂▁▂▃
ethereum-blockies-base64     751.89 µs/iter   1.03 ms   1.70 ms ▅█▆▅▃▃▄▂▂▂▁
react-blockies               254.63 µs/iter 269.46 µs 465.67 µs ▂▇█▅▃▂▁▁▁▁▁

summary
  blo/wasm
   2.32x faster than blo
   22.59x faster than blockies-react-svg
   247.79x faster than react-blockies
   731.69x faster than ethereum-blockies-base64
   9401.36x faster than blockies-ts
   14836.35x faster than @download/blockies

See ./benchmark for the benchmark code.

Run pnpm run bench:browser to open the interactive browser benchmark at http://127.0.0.1:5174, with library comparisons and live previews.

License

MIT