@basementuniverse/marble-identicons

Marble Identicons

Generate random marble-style identicons.

Installation

npm install @basementuniverse/marble-identicons

Usage

API:

function identicon(
  name: string,
  settings: Partial<IdenticonSettings>
) => HTMLCanvasElement

See below for more information on configuration settings.

In a browser environment

Include the script in your page and call the identicon function. It will return a HTMLCanvasElement node which can be appended to the DOM or drawn into another canvas.

Example:

<script src="build/identicon.js"></script>
<script>

const myIdenticon = identicon('Alan Turing');

document.body.appendChild(myIdenticon);

</script>

In React

This example shows one way of wrapping the HTMLCanvasElement inside a JSX element:

import { useRef, useLayoutEffect } from 'react';
import { identicon } from '@basementuniverse/marble-identicons';

export function MarbleIdenticon({ name }: { name: string }) {
  const ref = useRef<HTMLDivElement>(null);

  useLayoutEffect(() => {
    if (ref.current) {
      ref.current.innerHTML = '';
      ref.current.appendChild(identicon(name));
    }
  });

  return (
    <div className="identicon" ref={ref}></div>
  );
}

This component can then be used like so:

ReactDOM.render(
  <MarbleIdenticon name="Alan Turing" />,
  document.getElementById('root')
);

Settings

type IdenticonSettings = {
  size: number;
  baseSeed: string;
  font: string;
  fontStyle: FontStyle;
  fontSize: number;
  backgroundColours: string[];
  initialsColours: string[];
  initialsOffset: vec;
  initialsAlpha: number;
  initialsCompositeOperation: CompositeOperation;
  stripeColours: string[];
  stripeAlpha: number;
  stripeCompositeOperation: CompositeOperation;
  stripes: [number, number];
  stripeWidth: [number, number];
  stripeDeviation: [number, number];
  curveAmount: [number, number];
  curveOffset: [number, number];
  startWidthSign: WidthSign[];
  endWidthSign: WidthSign[];
};

Setting	Type	Description	Default value
size	number	The size of the identicon in pixels	100
baseSeed	string	A string that will be prefixed onto the name when seeding the RNG	''
font	string	The font family used for the initials	'Helvetica'
fontStyle	FontStyle	The font style used for the initials. Must be one of '', 'normal', 'bold', 'italic'	'bold'
fontSize	number	The font size used for the initials, as a factor of size	0.4
backgroundColours	string[]	An array of background colours. One will be picked at random from this list.	['#16a085', '#1abc9c', '#2ecc71', '#3498db', '#1970b9', '#9b59b6', '#e67e22', '#e74c3c', '#e0395b']
initialsColours	string[]	An array of colours used for the initials. The index of the randomly-chosen background colour will be used to select from this list, clamped to the size of the array.	['#ffffff']
initialsOffset	vec	The initials offset position. { x: number, y: number }	{ x: 0, y: 0 }
initialsAlpha	number	The alpha opacity of the initials	1
initialsCompositeOperation	CompositeOperation	The global composite operation used for the initials. Must be one of 'source-over', 'lighter', 'multiply', 'screen', 'overlay', 'color-dodge', 'color-burn', 'hard-light', 'soft-light'	'source-over'
stripeColours	string[]	An array of colours used for the stripes. The index of the randomly-chosen background colour will be used to select from this list, clamped to the size of the array.	['#f1c40f']
stripeAlpha	number	The alpha opacity of the stripes	0.15
stripeCompositeOperation	CompositeOperation	The global composite operation used for the stripes. Must be one of 'source-over', 'lighter', 'multiply', 'screen', 'overlay', 'color-dodge', 'color-burn', 'hard-light', 'soft-light'	'lighter'
stripes	[number, number]	A tuple containing the minimum and maximum number of stripes to draw	[3, 8]
stripeWidth	[number, number]	A tuple containing the minimum and maximum stripe width, measured in radians.	[0.2, 0.7]
stripeDeviation	[number, number]	A tuple containing minimum and maximum distances between successive stripes, measured in radians.	[-0.5, 0.5]
curveAmount	[number, number]	A tuple containing the minimum and maximum radius multiplier for the control point circle.	[0.2, 0.4]
curveOffset	[number, number]	A tuple containing the minimum and maximum offset angle for the control point measured in radians.	[0, 0.5]
startWidthSign	WidthSign[]	An array of signs ('positive' or 'negative') for the starting edge of each stripe. If startWidthSign is ['positive'] and endWidthSign is ['negative'] (or vice-versa) then the stripe side edges will not cross over.	['positive', 'negative']
endWidthSign	WidthSign[]	An array of signs ('positive' or 'negative') for the ending edge of each stripe.	['positive', 'negative']