🌩 @cloudnouns/kit

The best way to build with Nouns and Lil Nouns. ⌐◨-◨

@cloudnouns/kit is a JavaScript library that makes creating Nouns dead simple.

• 🔥 Create *any* Noun or Lil Noun.
• 👩🏽‍🔬 Choose all, some, or no traits. Or make Nouns with invisible traits.
• 🟩 Customize background colors
• 💝 Compatible with any frontend framework (like React, Vue, and Svelte) or vanilla JS.

Note: Check out the Cloud API for a hosted, URL-based version of this library. Perfect for designers and no-code based workflows. Learn more ↗️.

Quick start

Install with your favorite package manager...

npm install @cloudnouns/kit
# or
yarn add @cloudnouns/kit

... import into your project...

import { Noun } from '@cloudnouns/kit';

... initialize...

// random Noun
const noun = new Noun();

... and use generously.

<img src={noun.images.svg} alt="noun" />

Try it out

Use the CodeSandbox links below to try out the library:

• React
• Svelte
• Vue
• Vanilla JS

For more information, check out our documentation.

Noun Properties

property	type
hex	string	hex color code. only set when seed.background equals 2
images	object	keys: svg (data url)
seed	object	keys: background, body, accessory, head, glasses
size	number	dimensions (square) of the image
style	string	classic or lil
url	string	url for hosted image of the Noun

Example

const noun = new Noun({
	traits: { head: 50, glasses: 7, background: 2 },
	hex: 'dcff70'
});

// noun.hex = 'dcff70'
// noun.images = { svg: 'data:image/svg+xml;base64...' }
// noun.seed = { background: 2, head: 50, glasses: 7, ... } (body & accessory chosen at random)
// noun.size = 320 (default)
// noun.style = 'classic' (default)
// noun.url = 'https://api.cloudnouns.com/v1/pfp?...`

Preview this Noun in your browser! Refresh the page for new combinations of the unspecified traits.

Options

If no options are provided, a random Noun will be generated and returned.

prop	type
style	string	classic or lil
traits	object or array	see below for example usage
text	string	any text. used to generate Noun seed
hash	string	must be a 0x-prefixed, valid, bytes32 hash
hex	string	must be a valid hex color code
size	number	image dimensions (square)

Example usage

style

// classic Noun
const noun = new Noun();
const noun2 = new Noun({ style: 'classic' });

// lil Noun
const lilnoun = new Noun({ style: 'lil' });

traits

// each trait is optional. unspecified traits are chosen at random.

// partial object.
const noun = new Noun({
	traits: {
		head: 50,
		glasses: 7
	}
});

// full object
const noun2 = new Noun({
	traits: {
		background: 1,
		body: 15,
		accessory: 94,
		head: 138,
		glasses: 5
	}
});

// array. must include 5-valid values.
const noun3 = new Noun({ traits: [1, 15, 94, 138, 5] });

text

// will always return the same Noun for a given string.
// below examples return 3 different Nouns
const noun = new Noun({ text: 'Badu Blanc' });
const noun2 = new Noun({ text: 'badublanc.eth' });
const noun3 = new Noun({ text: '@badublanc' });

hash

// changes the hash used for Noun generation.
// must be a 0x-prefixed, valid, bytes32 hash.
// this prop is ignored without the text prop.
const ignored = new Noun({
	hash: '0x241aa473a95cb34fa4dc2d2c9b294ce9cc29a48b791f496b82341b937503fa69'
});

// produces two different Nouns due to hash, despite having same string
const noun = new Noun({ text: 'Badu Blanc' });
const noun2 = new Noun({
	text: 'Badu Blanc',
	hash: '0x241aa473a95cb34fa4dc2d2c9b294ce9cc29a48b791f496b82341b937503fa69'
});

hex

// any valid hex color string
// ignored unless background is 2
const ignored = new Noun({ hex: 'c0fca6' });

const noun = new Noun({ traits: { background: 2 }, hex: 'c0fca6' });
const noun2 = new Noun({ traits: [2, 15, 3, 72, 10], hex: '79d4e0' });

size

const small = new Noun({ size: 100 });
const large = new Noun({ size: 1000 });

Combining props

const customNoun = new Noun({
	traits: { background: 2, body: 13, accessory: 9, head: 23, glasses: 7 },
	hex: 'c0fca6',
	style: 'lil',
	size: 750
});