@maxnth/gestalt

@maxnth/gestalt

l

Give @maxnth/gestalt a string or number — a user id, email, handle, or anything else — and it renders a unique inline SVG avatar. The same seed always produces the same result, so you get consistent, good-looking avatars entirely from data.

Documentation · Storybook

Why use it?

• No assets to ship. Every avatar is generated on the fly, so there is no image folder, no CDN, and no broken links.
• Stable by design. A seed like ada@example.com always produces the exact same avatar.
• Server-rendered. Built-in Vue components emit complete inline SVG during SSR, with no client-side drawing pass.
• Flexible core. Use a component, generate a framework-independent SVG document, or keep using the canvas helpers for raster export and custom algorithms.
• Easy to extend. Bring your own rendering algorithm via the generic <Avatar> component.
• Fully typed. Written in TypeScript with declarations included.

Install

pnpm add @maxnth/gestalt
# or: npm i / yarn add / bun add

Requires vue >= 3.5.

Usage

<GradientAvatar>

The quickest way to start is the mesh-gradient avatar component.

<script setup>
import { GradientAvatar } from '@maxnth/gestalt'
</script>

<template>
  <GradientAvatar seed="jane@example.com" :size="96" />
</template>

Props

class is forwarded to the wrapper <span> like any standard Vue attribute.

<!-- Palette-quantized pixel treatment -->
<GradientAvatar seed="jane@example.com" :size="96" mode="dither" />

Ring / border

All avatar components support a ring prop that draws an outline around the avatar using box-shadow, so it naturally follows the chosen radius.

<GradientAvatar seed="jane@example.com" :size="96" ring />

<GradientAvatar seed="jane@example.com" :size="96" :ring="4" />

<GradientAvatar seed="jane@example.com" :size="96" ring="0 0 0 3px #10b981" />

<!-- Circle -->
<GradientAvatar seed="jane@example.com" :size="96" />

<!-- Rounded square -->
<GradientAvatar seed="jane@example.com" :size="96" :radius="16" />

<!-- Square -->
<GradientAvatar seed="jane@example.com" :size="96" :radius="0" />

<IdenticonAvatar>

For a GitHub-style geometric avatar, render a symmetric grid of cells with a deterministic color pair.

<script setup>
import { IdenticonAvatar } from '@maxnth/gestalt'
</script>

<template>
  <IdenticonAvatar seed="jane@example.com" :size="96" />
  <IdenticonAvatar seed="jane@example.com" :size="96" mirror="vertical" />
</template>

<FlowFieldAvatar>

For a plotter-style generative avatar, render streamlines through a deterministic noise field.

<script setup>
import { FlowFieldAvatar } from '@maxnth/gestalt'
</script>

<template>
  <FlowFieldAvatar seed="jane@example.com" :size="96" />
  <FlowFieldAvatar seed="jane@example.com" :size="96" :columns="9" :rows="9" :iterations="56" />
</template>

<InitialsAvatar>

For a more traditional placeholder avatar, render one or two initials on a solid background.

<script setup>
import { InitialsAvatar } from '@maxnth/gestalt'
</script>

<template>
  <InitialsAvatar seed="Maximilian Nöth" :size="96" mode="single" />
  <InitialsAvatar seed="Maximilian Nöth" :size="96" mode="double" />
</template>

Double initials split the seed by spaces, dashes, underscores, and dots — so Ada Lovelace becomes AL.

Generic <Avatar>

When you want to experiment with a custom Canvas2D generator, use the lower-level <Avatar> component. The built-in components above use inline SVG; this generic compatibility component remains canvas-based.

<script setup>
import { Avatar, gradientAvatarAlgorithm } from '@maxnth/gestalt'
</script>

<template>
  <Avatar seed="user-123" :size="80" :algorithm="gradientAvatarAlgorithm" />
</template>

An algorithm is just an object with a name and a render function:

import type { AlgorithmRenderContext, AvatarAlgorithm } from '@maxnth/gestalt'

const stripeAlgorithm: AvatarAlgorithm = {
  name: 'stripe',
  render({ ctx, size, seed }: AlgorithmRenderContext, options) {
    ctx.fillStyle = '#3b82f6'
    ctx.fillRect(0, 0, size, size / 2)
  },
}

Engine helpers

The same gradient engine is exposed as plain functions, which is handy for downloads, server renderers, or anywhere you need an <img> src.

import {
  generatePalette,
  gradientToDataURL,
  seedFromString,
} from '@maxnth/gestalt'

// 512×512 PNG data URL
const src = gradientToDataURL('jane@example.com', { size: 512 })

// Inspect the palette behind a seed
const { seed, colors, harmony } = generatePalette('jane@example.com')

// Convert a string to its numeric seed
const numericSeed = seedFromString('jane@example.com')

Generator dimensions are rounded and clamped from 1 through 4096; identicon gridSize is clamped from 1 through 64. Built-in color options accept #RGB and #RRGGBB only and normalize them to uppercase #RRGGBB, keeping SVG and Canvas output consistent across runtimes.

SSR

All built-in avatar components render complete inline SVG markup on the server. Their output is deterministic and hydrates without a client-side drawing pass. The lower-level <Avatar> component remains canvas-based for custom Canvas2D algorithms and therefore renders an empty canvas until it mounts in the browser.

License

MIT © Maximilian Nöth