@m3000/hashed-gems

Generative gem avatars for user identification. Each gem is uniquely rendered based on a seed string (username, email, id) using WebGL shaders with spectral color dispersion.

Built on React 19.

Installation

pnpm add @m3000/hashed-gems

Peer dependencies:

pnpm add react react-dom

Styles

Import the stylesheet once in your app entry:

import "@m3000/hashed-gems/styles.css";

Usage

Import the component and use any string as a seed:

import { HashedGem } from "@m3000/hashed-gems";

<HashedGem seed="ada.lovelace" />
<HashedGem seed="[email protected]" size={128} />

Accessibility

Use aria-label when the gem should be announced on its own. Use aria-hidden when nearby text already identifies the person or item.

import { HashedGem } from "@m3000/hashed-gems";

<HashedGem seed="ada.lovelace" aria-label="Avatar for Ada Lovelace" />

<div>
  <HashedGem seed="ada.lovelace" aria-hidden={true} />
  <span>Ada Lovelace</span>
</div>

Determinism

The same seed always produces the same gem, so you can use it as a stable visual identity across sessions and devices.

<HashedGem seed="ada.lovelace" />
<HashedGem seed="ada.lovelace" />

Both renders will resolve to the same gem type, cut, and motion profile.

Props

| Prop | Type | Default | Description | | ------------- | ---------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | seed | string | "" | Any string — username, email, id — hashed to a deterministic avatar | | size | number | 64 | Display size in pixels (container width & height) | | resolution | number | size × dpr | WebGL canvas pixel resolution. Pass larger value for higher quality captures (e.g. resolution={512} on size={160} for crisp blob image) | | gemType | GemType | auto | Override gem type: diamond, ruby, sapphire, emerald, topaz, amethyst, aquamarine, rose-quartz, citrine, onyx, alexandrite, or opal | | cutType | CutType | auto | Override cut type: round-brilliant, princess, cushion, emerald-step, firework, jubilee, or rose | | static | boolean | false | Render a single frame and stop animating. Good for lists | | aria-label | string | - | Accessible name used when the gem should be exposed as an image | | aria-hidden | boolean | true when unlabeled | Hides the gem from assistive technology when surrounding UI already provides the label | | role | AriaRole | "img" when labeled | Optional semantic role override. Defaults to img when aria-label is provided | | className | string | - | Additional CSS classes |

License

MIT