@teapotlabs/identeapots

Indeteapots

Identeapots is a simple TypeScript library for generating identicon images.

The library has no dependencies and is designed to be lightweight and easy to use.

See the demo application »

Installation

npm i @teapotlabs/identeapots

Basic Usage

The return value of the generateIdenteapot function is Data URL.

import { generateIdenteapot } from "@teapotlabs/identeapots";

// data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAACPEAAAH0C...
const identicon: string = generateIdenteapot("hello world", "salt");

Which can be used in <img> tags as src attribute.

<img src={identicon} alt="Example Identeapot" />

This will generate the following image:

Advanced Usage

You can also pass various configuration options to the generateIdenteapot function to customize the generated identicons.

import { generateIdenteapot } from "@teapotlabs/identeapots";

const identicon: string = generateIdenteapot("hello world", {
  salt: "salt",
  size: 200
  // other options...
});

🔑 Hash Configuration

Option	Type	Default	Description
salt	string	""	A string appended to the seed before hashing. Useful for variant generation.

🎨 Color Configuration

Option	Type	Default	Description
paletteSize	number	8	Number of colors in the palette.
coloredCellLightness	number	60	Lightness value for colored cells.
emptyCellLightness	number	90	Lightness value for empty cells.

🧩 Identicon Configuration

Option	Type	Default	Description
size	number	400	Final image size in pixels.
gridSize	number	9	Number of cells per row and column in the grid.
patternSize	number	7	Size of the identicon pattern in cells (must be ≤ gridSize).
overlap	number	0.5	Overlap in pixels to avoid visible gaps between cells.

Example

A complete example of a NextJS application is available in the /demo folder. You can run it locally by cloning the repository and running:

npm install
npm run dev

Then open your browser and navigate to http://localhost:3000.

You can also view the demo application online at https://identeapots.pages.dev/.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

License

MIT