Generate Random Cartoon Avatars With JS And SVG – faces.js

Preview:

Description:

faces.js is a standalone JavaScript library used for generating random, SVG-based, vector shaped cartoon faces for user avatars.

How to use it:

1. Install and import.

# Yarn
$ yarn add facesjs
# NPM
$ npm i facesjs

import { display, generate } from "facesjs";

2. OR Download and place the JavaScript file faces.js at the bottom of the webpage.

<script src="faces.js"></script>

3. Generate a random cartoon avatar inside a given container.

<div id="example"></div>

const face = generate();
display("example", face);

4. Get the cartoon avatar as a JS object.

var face = faces.generate("example");
console.log(face);

5. Customize the color of the avatar.

const face = generate({
      body: { color: "yellow" }
});
// or
faces.display("example", face, { 
  body: { color: "yellow" } 
});

6. Specify the race: white, black, asian, or brown.

const face = generate({
      null, 
      {race: "white"}
});

7. Generate female faces.

const face = generate({
      null, 
      {gender: "female"}
});

8. convert a face object to an SVG string.

import { faceToSvgString, generate } from "facesjs";

const face = generate();
const svg = faceToSvgString(face);

Changelog:

v5.0.0/1 (05/06/2025)

• Package updated

v4.3.3 (03/24/2025)

• New generateRelative function to generate a face that is similar to an exisiting face, like a sibling/parent/child.

v4.2.2 (08/05/2024)

• Updated for React

v4.2.1 (05/15/2024)

• Restore the “shave” facial feature option to the editor, which was accidentally removed in v4.1.0.

v4.2.0 (05/13/2024)

• Added a Face React component for easier integration with React.
• Renamed the Face type to FaceConfig.

v4.1.1 (05/06/2024)

• Fixed the CommonJS build.

v4.1.0 (04/23/2024)

• Rewrote the editor UI and added a ton of functionality. The main new features are a gallery of faces showing previews of all features you can select, and the ability to export a face in SVG or PNG format.

v4.0.0 (11/19/2023)

• Added faceToSvgString function to output faces as SVG strings, rather than only rendering to the DOM via display.
• Added CLI for generating faces and outputting them as SVG strings.

v3.8.2 (03/16/2023)

• Fixed the esm build.

v3.8.1 (02/26/2023)

• Add back accidentally-deleted hair

v3.8.0 (02/25/2023)

• Added a gender option to generate female faces

v3.7.4 (07/10/2022)

• Restore rate of accessories (such as headbands) being present.

v3.7.3 (06/17/2022)

• Tweak baseball jersey/hat colors

v3.7.2 (03/28/2022)

• Tweak baseball jersey/hat colors

v3.7.0 (03/26/2022)

• Added baseball jerseys and hats

v3.6.0 (08/18/2021)

• Added new football jersey style

v3.5.0 (06/14/2021)

• Added ability to select which facial features to randomize in the editor UI
• Improved Asian skin tones

v3.4.0 (03/18/2021)

• Added some additional jersey options for football and basketball