Documentation - Fretboard

Installation

Use npm/yarn:

$ npm i @moonwave99/fretboard.js --save

Usage

Given an existing DOM element:

<figure id="fretboard"></figure>

require / import the library accordingly:

const { Fretboard } = require('@moonwave99/fretboard.js');
// OR
import { Fretboard } from '@moonwave99/fretboard.js';

Then initialise a Fretboard instance with desired options:

const fretboard = new Fretboard({
  el: '#fretboard',
  fretColor: 'blue',
  dotFill: 'red',
  ...
});

First set the dots with setDots and call the render method to display:

// this would render an open C chord
fretboard.setDots([
  {
    string: 5,
    fret: 3,
  },
  {
    string: 4,
    fret: 2,
  },
  {
    string: 2,
    fret: 1,
  },
]);

fretboard.render();

Since setDots returns the fretboard instance itself, you can chain the two calls as:

fretboard.setDots(dots).render();

Configuration options

Note: even though the context should provide enough disambiguation, the word string refers to both the instrument ones and the programming data type!

Fretboard API

The Fretboard object has the following methods:

setDots()

setDots(dots: Position[]): Fretboard

Sets the passed dots. Returns the instance itself.

render()

render(): Fretboard

Renders the fretboard. Returns the instance itself.

clear()

clear(): Fretboard

Clears all positions from the fretboard. Returns the instance itself.

style()

style({
  filter = (): boolean => true,
  text,
  fontSize,
  fontFill,
  ...opts
}: {
  filter?: (position: Position) => boolean | Record<string, string|number|boolean>;
  text?: (position: Position) => string;
  fontSize?: number;
  fontFill?: string;
  [key: string]: string | number | Function;
}): Fretboard

Applies the passed properties to selected positions (via the filter function parameter). If no filter is provided, all positions are affected. Returns the instance itself. Example:

const fretboard = new Fretboard();

fretboard
  .setDots(dots)
  .render()
  .style({
    // this gives us just the root notes
    filter: { interval: '1P' },
    // displays the note name
    text: ({ note }) => note,
    // sets the value of the fill attribute
    fill: 'red',
  });

renderScale()

renderScale({
  type,
  root,
  box
 }: {
  type: string;
  root: string;
  box?: {
    box: string | number;
    system: Systems;
  }
}): Fretboard

Populates the fretboard with all the notes of the given scale, e.g.:

const fretboard = new Fretboard();

// shows where all the C,D,E,F,G,A,B are across all strings
fretboard.renderScale({
  type: 'major',
  root: 'C',
});

To highlight a specific box, use the optional box param:

import { Fretboard, Systems } from '@moonwave99/fretboard.js';

const fretboard = new Fretboard();

// shows where all the A,B,C#,D,E,F#,G# are across all strings,
// highlighting the C box of the CAGED system (between frets 9 and 12, that is)
fretboard.renderScale({
  type: 'major',
  root: 'A',
  box: {
    system: Systems.CAGED,
    box: 'C',
  },
});

For more information, see Fretboard Systems.

renderChord()

renderChord(chord: string, barres? Barre | Barre[]): Fretboard

Shorthand for rendering positions from a chord voicing string, e.g. x32010 for a C Major in open position.

The string is mapped onto the fretboard starting from the bottom string, in this case:

• x: 6th string muted;
• 3: 5th string 3rd fret;
• 2: 4th string 2nd fret;
• 0: 3rd string open;
• 1: 2nd string 1st fret;
• 0: 1st string open.

Examples:

// renders an open C major
const fretboard = new Fretboard({
  fretCount: 3,
  showFretNumbers: false,
});

fretboard.renderChord('x32010');

// renders the Hendrix chord, displaying only frets 6, 7, 8
const fretboard = new Fretboard({
  fretCount: 3,
  showFretNumbers: true,
  crop: true,
});

fretboard.renderChord('x7678x');

Note: for frets above the 9th, the dash-splitted-notation should be used in order to prevent parsing ambiguity - for instance 10-x-10-10-8-x for a Dmadd11 chord.

Barres are supported by passing either a single Barre parameter, or an array of them:

// renders a F major in first position
const fretboard = new Fretboard({
  fretCount: 3,
  showFretNumbers: false,
  crop: true,
});

fretboard.renderChord('133211', { fret: 1 });

// renders a B minor in second position
const fretboard = new Fretboard({
  fretCount: 3,
  showFretNumbers: false,
  crop: true,
});

fretboard.renderChord('x24432', { fret: 2, stringFrom: 5 });

// renders a C major in third position
const fretboard = new Fretboard({
  fretCount: 3,
  showFretNumbers: false,
  crop: true,
});

fretboard.renderChord('x35553', [
  { fret: 3, stringFrom: 5 },
  { fret: 5, stringFrom: 4, stringTo: 2 },
]);

Note: stringFrom defaults to the lowest string, and stringTo to the first. Pass the "human" agreed value otherwise, e.g. 2 for the open B string, or 5 for the open A (in standard guitar tuning of course).

muteStrings()

muteStrings({
  strings,
  width,
  strokeWidth,
  stroke
}: {
  strings: number[];
  width?: number;
  strokeWidth?: number;
  stroke?: string;
}): Fretboard

Marks passed strings with a cross, e.g. fretboard.muteStrings({ strings: [1, 6]}).

highlightAreas()

highlightAreas(...areas: [Position, Position][]): Fretboard

Highlights the specified areas.

// highlights the E-shaped box of the G major scale
const fretboard = new Fretboard();

fretboard.renderScale({ root: 'G', type: 'major' });
fretboard.highlightAreas([
  { string: 1, fret: 5 },
  { string: 6, fret: 2 },
]);

// highlights the E-shaped and A-shaped box of the G major scale
const fretboard = new Fretboard();

fretboard.renderScale({ root: 'G', type: 'major' });
fretboard.highlightAreas(
  [
    { string: 1, fret: 5 },
    { string: 6, fret: 2 },
  ],
  [
    { string: 1, fret: 13 },
    { string: 6, fret: 9 },
  ]
);

clearHighlightAreas()

clearHighlightAreas(): Fretboard

Clears all the highlighted areas.

Events

You can listen to click and mousemove events on a fretboard instance. The callback function will be invoked with the corresponding Position (string/fret number), and the original MouseEvent as second parameter.

fretboard.on(eventName, (position: Position, event: MouseEvent) => void)

For example:

// this renders a dot following the mouse coordinates
const fretboard = new Fretboard();
fretboard.render([]);
fretboard.on('mousemove', (position) => fretboard.render([position]));

// you can remove the eventListeners with
fretboard.removeEventListeners();

Tuning

One can pass a custom tuning as an array of notes, e.g.:

const fretboard = new Fretboard({
  tuning: ['D2', 'G2', 'D3', 'G3', 'B3', 'D4'],
});

Note: the tuning starts from the lower note as per naming convention.

The option is used by renderScale() to populate the fretboard according to the tuning.
A set of common used tuning can be imported from the library itself:

import { GUITAR_TUNINGS } from '@moonwave99/fretboard.js';

/*
GUITAR_TUNINGS = {
    default: ["E2", "A2", "D3", "G3", "B3", "E4"],
    halfStepDown: ["Eb2", "Ab2", "Db3", "Gb3", "Bb3", "Eb4"],
    dropD: ["D2", "A2", "D3", "G3", "B3", "E4"],
    openG: ["D2", "G2", "D3", "G3", "B3", "D4"],
    DADGAD: ["D2", "A2", "D3", "G3", "A3", "D4"]
};
*/
}

Note: tuning.length and stringCount must match, so beware bassists, ukulelists and 7+stringers.

FAQ

Why don't you provide a more expressive API like .highlightMajorTriads()?

The aim of this library is to be as abstract as possible, and to make no assumptions besides the bare string/fret positioning. Since you can pass as many properties as you want to the position entries, you can provide full controlled and rich visualisations.