blo - Blockchain Identicons Generator

blo is a small and fast library to generate Blockchain identicons.


Features

- 🐥 Small:  gzipped, distributed as minified ES modules.
- 🔍 Optimized: Leverages SVG to generate compact and sharp images at any size.
- 💆 Simple: Covering all blockchain networks, focusing on uniformity.
- 🗂 Typed: Ships with types included.
- 👫 Works everywhere: browsers, Bun, Node.js.
- ☁️ Zero dependencies.

Library Comparison

Library | Renders/sec[^1] | Size[^2] | Types | Environment[^3] | Rendering
--------|---------------:|------|--------|----------------|----------:
@blockchainhub/blo | 520 |  | !Types support | !Environment support | SVG
blockies-react-svg | 580 |  | !Types support | !Environment support | SVG
ethereum-blockies-base64 | 450 |  | !Types support | !Environment support | PNG
@download/blockies | 370 |  | !Types support | !Environment support | Canvas
blockies-ts | 370 |  | !Types support | !Environment support | Canvas
react-blockies | 700 |  | !Types support | !Environment support | Canvas

[^1]: The number of renders per second. It was measured on Chromium Engine 131, MacOS with an Apple M2 Max. See ./benchmark for the methodology.
[^2]: Minizipped bundle size. Good to be < 1 KiB.
[^3]: 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 @blockchainhub/blo
`

`sh
pnpm add @blockchainhub/blo
`

`sh
yarn add @blockchainhub/blo
`

`ts
import { blo } from "@blockchainhub/blo";

img.src = blo("cb7147879011ea207df5b35a24ca6f0859dcfb145999");
`

$3

blo is fast enough to not require memoization or async rendering for common use cases.

`tsx
function AddressIcon(address: string) {
return (
alt={address}
src={blo(address)}
/>
);
}
`

API

$3

Get a data URI string representing the identicon as an SVG image.

`ts
import { blo } from "@blockchainhub/blo";

// Default usage (64px)
img.src = blo("0x123...");

// With options
img.src = blo("0x123...", {
size: 32, // Custom size (default: 64)
seed: "custom" // Custom seed (default: undefined)
});
`

$3

Same as blo() but returns SVG code instead of a data URI.

`ts
const svg = bloSvg("0x123...", {
size: 32,
seed: "custom"
});
`

$3

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

`ts
const [imageData, palette] = bloImage("0x123...", {
seed: "custom"
});
`

$3

`ts
interface BloOptions {
// Size in pixels (default: 64)
size?: number;

// Custom seed for generation (default: undefined)
// If undefined, uses the address as seed
seed?: string;
}
`

$3

The library ships with TypeScript types included:

`ts
export type Address = string;
export type BloImage = [BloImageData, Palette];
export type BloImageData = Uint8Array;

export interface BloOptions {
size?: number;
seed?: string;
}

export type Palette = {
background: Hsl;
primary: Hsl;
accent: Hsl;
};

export type Hsl = Uint16Array;
`

Address Case Handling

By default, blo displays addresses in lowercase. You have three options for case handling:

- Lowercase (default): Set uppercase to false or omit it
- Uppercase: Set uppercase to true
- Preserve original case: Set uppercase to null

Example:

`ts
import { blo } from "@blockchainhub/blo";

const address = "cb7147879011ea207df5b35a24ca6f0859dcfb145999";

// Default behavior (lowercase)
const identicon1 = blo(address);

// Force uppercase
const identicon2 = blo(address, true);

// Preserve original case
const identicon3 = blo(address, null);
`

Note: The case of the address only affects its visual representation. Internally, the identicon generation algorithm always uses lowercase for consistency.

Acknowledgements

- blo is a modernized version of ethereum-blockies-base64, which I think was based on ethereum/blockies.

FAQ

$3

Yes. You can use the ENS name directly as the address parameter.

$3

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.

$3

blo focuses on the blockchain algorithm but you can use it with any data.

$3

blo is short for blockies, which is the name of the original library it is based on.

License

CORE

Contributing

See CONTRIBUTING.md for details.

Sponsor BlockchainHub

BlockchainHub is a platform for building Open Source applications.

Sponsor us to support our work.

Current GitHub Sponsors: