chord-illustrator

SVG-based library, which illustrates finger positions of a guitar chord on a fretboard.

Blazingly fast and blazingly small 🚀
No dependencies
Works on browser & Node.js
Minified: 2.4 kB
Minified + gzipped: 1 kB

Installation

$ npm install --save chord-illustrator

Usage in browser

illustrates B minor

import ChordIllustrator from 'chord-illustrator';

// insert it into any HTML element
ChordIllustrator.setContainer(document.body);

// or get output directly
const svg = ChordIllustrator.make({
  name: 'Bm',
  mutedStrings: ['yes'],
  fingering: [
    { fret: 2, barre: { from: 1, to: 5 } },
    { fret: 3, string: 2, finger: 2 },
    { fret: 4, string: 3, finger: 4 },
    { fret: 4, string: 4, finger: 3 },
  ],
});
console.log('HTML output', svg);

looks like this

sometext

the fretboard will expand automatically based on chord length

Usage in Node.js

The library is tightly coupled with window.document. To use it on Node.js, you may want to import something like jsdom.

import { JSDOM } from 'jsdom';
import ChordIllustrator from 'chord-illustrator';

// create some html
const dom = new JSDOM(`<!DOCTYPE html><p>Hello world</p>`);

// set missing dom
ChordIllustrator.setDocument(dom.window.document);

const svg = ChordIllustrator.make({
  name: 'C',
  mutedStrings: ['yes'],
  fingering: [
    { fret: 1, string: 2, finger: 1 },
    { fret: 2, string: 4, finger: 2 },
    { fret: 3, string: 5, finger: 3 },
  ],
});
console.log('HTML output', svg);

API docs

.setContainer(container: HTMLElement)

set the container where the output renders.

.setDocument(document: DOM)

override the default window.document with your own.

.setHeight(height: number)

specify the SVG height. The width will adjust automatically.

.make({ name: string, fingering: array, mutedStrings: array, fretboardRange: object, labels: object })

specify the chord options by passing an object. Only fingering property is mandatory, and others are optional.

@param(name: string)

The title is displayed at the top. Omit the property to hide.

name: 'Am';

@param(fingering: array)

Mandatory property detailing the chord fingering:

fingering: [
  { fret: 2, barre: { from: 1, to: 5 } },
  { fret: 3, string: 2, finger: 2 },
];

@param(mutedStrings: array)

An array of 6 items filled with ”yes/no/open”. If not specified, values will default to “no”.

mutedStrings: ['yes', 'no', 'no', 'no', 'no', 'open'];

@param(fretboardRange: object)

The fretboard will expand automatically based on chord length. You may override the generated fretboard like this:

fretboardRange: { from: 1, to: 12 }

@param(labels: object)

The fret number label is shown at the bottom left. You can hide this label or customize the prefix:

labels: {
  title: { style: { show: false, fill: 'blue', opacity: 1 } },
  fretNumber: { style: { show: false, fill: 'red', opacity: 1 } },
}

You can customize the whole SVG fretboard using this object.

fretboard: {
  fret: { style: { stroke: 'red', fill: 'red' } },
  string: { style: { stroke: 'green', fill: 'green' } },
  neck: { style: { stroke: 'blue', fill: 'blue' } },
  barre: { style: { stroke: 'gray', fill: 'gray' } },
  finger: { style: { stroke: 'yellow', fill: 'yellow' } },
  fingerText: { style: { stroke: 'orange', fill: 'orange' } },
}

@param(vertical: boolean)

Display the chord vertically.

vertical: true,

Support

Tested on Chrome & Node.js v17.6.0

License

inspired by guitar-js (Fomin Sergey)

Package detail