November 6, 2025•5 min read

Geometricon

TypeScriptSVGLibraryOpen Source

A TypeScript library that generates unique, symmetrical geometric icons from hash strings for user avatars and visual identifiers.

Generate unique, symmetrical geometric icons from hash strings. Perfect for creating user avatars and visual identifiers with a modern aesthetic. Transform any hash input into deterministic, visually balanced SVG icons with zero dependencies.

View on GitHub

Key Features

Deterministic Generation

Same hash input always produces identical icons. Perfect for consistent user avatars and visual identifiers across your application.

Symmetrical Compositions

Five structured layouts including centered, radial, split, frame, and random modes ensure every icon is visually balanced and professional.

Rich Color Options

Eight preset color schemes (pastel, vibrant, warm, cool, monochrome, earth, ocean, sunset) plus custom palette support with optional gradients.

Zero Dependencies

Pure TypeScript implementation with no external dependencies. Works in Node.js and browsers, outputting clean SVG with transparent backgrounds.

Geometric Shapes

Geometricon supports seven distinct shape types that can be combined to create unique visual identities:

Circles

Squares

Triangles

Hexagons

Diamonds

Stars

Shapes use variable opacity (75-95%) for subtle depth effects and are constrained to 90-degree rotations for a clean, professional appearance.

Installation

1. Clone the repository

git clone https://github.com/cjscrofani/geometricon.git

2. Install dependencies and build

npm installnpm run build

Usage Examples

CLI Usage

Basic generation:

geometricon abc123def456 -o icon.svg

With color scheme and composition:

geometricon abc123 --color-scheme ocean --composition radial

Custom shapes and gradients:

geometricon abc123 --shape-count 3 --shapes circle,square --use-gradients

Node.js API

const { generateIcon } = require('./dist/index');

const svg = generateIcon('abc123def456', {
  size: 300,
  composition: 'centered',
  colorScheme: 'ocean',
  useGradients: true
});

// Save or serve the SVG
fs.writeFileSync('icon.svg', svg);

Configuration Options

Composition Modes

centered: Focus shapes in the center
radial: Distribute shapes in a circle
split: Divide canvas into sections
frame: Create decorative borders
random: Organic placement

Color Schemes

pastel: Soft, muted colors
vibrant: Bold, saturated hues
warm: Reds, oranges, yellows
cool: Blues, greens, purples
monochrome: Grayscale palette
earth: Natural tones
ocean: Blue and teal shades
sunset: Orange and pink gradients

Technical Architecture

Geometricon uses deterministic hash-based generation to create consistent, unique icons:

Hash Processing

Portions of hash determine shape types, quantities, and positions

Size Constraints

Shapes sized 15-25% of canvas with 5% padding

SVG Output

Clean, transparent background SVG files

License

MIT License

Resources

GitHub Repository Documentation