chord-illustrator
v2.1.4
Published
SVG-based library, which illustrates finger positions of a guitar chord on a fretboard.
Downloads
47
Maintainers
calinalexandruReadme
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-illustratorUsage 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
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.documentwith 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
fingeringproperty 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
MIT © Alexandru Calin
inspired by guitar-js (Fomin Sergey)