@iconoma-icons/core

Core engine for Iconoma — deterministic SVG icon generation from any string.

Install

npm install @iconoma-icons/core

You'll also want @iconoma-icons/collection for the built-in styles, unless you're writing your own.

API

createIcon(style, options?)

Generates a deterministic SVG icon from a style function and options.

import { createIcon } from '@iconoma-icons/core';
import { pixel } from '@iconoma-icons/collection';

const icon = createIcon(pixel, {
  seed: '[email protected]',
  size: 128,
  colors: ['#FF006E', '#8338EC', '#3A86FF', '#FFBE0B', '#FB5607'],
  isCircle: false,
  borderRadius: 0,
});

icon.toString();   // '<svg xmlns="http://www.w3.org/2000/svg" ...>...</svg>'
icon.toDataUri();  // 'data:image/svg+xml;charset=utf-8,%3Csvg...'

Returns: Result — an object with two methods:

| Method | Returns | Description | |--------|---------|-------------| | toString() | string | Raw SVG markup. Use with innerHTML, fs.writeFileSync(), etc. | | toDataUri() | string | Data URI string. Use with <img src="..."> or CSS background-image. |

Options:

| Option | Type | Default | Description | |--------|------|---------|-------------| | seed | string | random | Any string. Determines the icon appearance. Same seed = same icon. | | size | number | 128 | Width & height in pixels. | | colors | string[] | ['#FF006E', '#8338EC', '#3A86FF', '#FFBE0B', '#FB5607'] | Array of hex color strings (e.g. '#FF006E'). 3-5 colors recommended. | | isCircle | boolean | false | Clip to circle via SVG <clipPath>. | | borderRadius | number | 0 | Rounded corner radius in px. Ignored if isCircle is true. | | styleOptions | Record<string, any> | style defaults | Style-specific tuning params. See @iconoma-icons/collection docs for options per style. |

SeededRandom

Deterministic pseudo-random number generator. Used internally and exposed for custom styles.

import { SeededRandom } from '@iconoma-icons/core';

const rng = new SeededRandom(42);

rng.random();              // float in [0, 1)
rng.randomInt(0, 10);      // integer in [0, 10] inclusive
rng.randomElement(array);  // picks one element
rng.shuffle(array);        // Fisher-Yates shuffle, returns the shuffled array

Style type

A style is a function with this signature:

type Style = (rng: SeededRandom, options: Options) => string;

It receives a seeded RNG and the resolved options, and returns an SVG body string (the markup inside the <svg> tag — rects, paths, polygons, etc). The createIcon function wraps this in a proper SVG element with viewBox, clipping, etc.

Writing a custom style

import { createIcon, SeededRandom } from '@iconoma-icons/core';
import type { Style, Options } from '@iconoma-icons/core';

const myStyle: Style = (rng: SeededRandom, options: Options): string => {
  const size = options.size || 128;
  const colors = options.colors || ['#000', '#fff'];
  const bg = rng.randomElement(colors);
  const fg = rng.randomElement(colors);

  // Return SVG body markup (everything inside <svg>)
  return `
    <rect width="${size}" height="${size}" fill="${bg}"/>
    <circle cx="${size/2}" cy="${size/2}" r="${size/3}" fill="${fg}"/>
  `;
};

const icon = createIcon(myStyle, { seed: 'hello', size: 256 });
console.log(icon.toString());

License

MIT