The `Fretboard` class

The Fretboard class renders highly configurable fretboard diagrams in SVG format.

Check the complete Fretboard API reference for more details.

Installation


pnpm add @music-ui/fretboard


npm install @music-ui/fretboard


yarn add @music-ui/fretboard

Usage

Rendering a fretboard requires a target element:


<div id="fretboard"></div>

and the following setup code:


import { Fretboard } from "@music-ui/fretboard";
 
const fretboard = new Fretboard({ fretCount: 5, width: 600 });
fretboard.render();

Output:

Width behavior

The display option controls the <svg> element width behavior.

Allow horizontal overflow

display: "overflow" sets the <svg> width to the fretboard width (either the passed or the default one):


import { Fretboard } from "@music-ui/fretboard";
 
const fretboard = new Fretboard({
  display: "overflow",
});
fretboard.render();

Output:

Contained in the parent element

display: "contain" sets the <svg> width to min(100%, {width}px):


import { Fretboard } from "@music-ui/fretboard";
 
const fretboard = new Fretboard({
  display: "contain",
});
fretboard.render();

Output:

And with a smaller fretboard:


import { Fretboard } from "@music-ui/fretboard";
 
const fretboard = new Fretboard({
  display: "contain",
  fretCount: 5,
  width: 600,
});
fretboard.render();

Output:

Fill the available space

display: "cover" sets the <svg> width to 100%:


import { Fretboard } from "@music-ui/fretboard";
 
const fretboard = new Fretboard({
  display: "cover",
  fretCount: 5,
  width: 600,
});
fretboard.render();

Output:

Omitting the display option prevents from setting the <svg> element width property entirely, in case you want to control it from your CSS.

Displaying fretboard positions

An empty fretboard is not much useful. Let’s see how to display some positions on it and to customize their appearance:


import { Fretboard } from "@music-ui/fretboard";
 
const fretboard = new Fretboard({ fretCount: 5, width: 600 });
 
// a good ole open C cowboy chord
fretboard.setPositions([
  { string: 5, fret: 3 },
  { string: 4, fret: 2 },
  { string: 2, fret: 1 },
]);
 
fretboard.render();

The Fretboard.setPositions methods accepts an array of fretboard positions.

A FretboardPosition can hold multiple information, the minimum requirement being the string and the fret keys like in the example above.

Displaying the position text

Let’s display the full C major arpeggio in first position:


import { Fretboard } from "@music-ui/fretboard";
 
const fretboard = new Fretboard({ fretCount: 5, width: 600 });
 
fretboard.setPositions([
  { string: 6, fret: 0 },
  { string: 6, fret: 3 },
  { string: 5, fret: 3 },
  { string: 4, fret: 2 },
  { string: 3, fret: 0 },
  { string: 2, fret: 1 },
  { string: 1, fret: 0 },
  { string: 1, fret: 3 },
]);
 
fretboard.render();

Output:

That looks great! What about knowing which note corresponds to every position?

Let’s expand the position array with such information:


import { Fretboard } from "@music-ui/fretboard";
 
const fretboard = new Fretboard({ fretCount: 5, width: 600 });
 
fretboard.setPositions([
  { string: 6, fret: 0, note: "E" },
  { string: 6, fret: 3, note: "G" },
  { string: 5, fret: 3, note: "C" },
  { string: 4, fret: 2, note: "E" },
  { string: 3, fret: 0, note: "G" },
  { string: 2, fret: 1, note: "C" },
  { string: 1, fret: 0, note: "E" },
  { string: 1, fret: 3, note: "G" },
]);
 
fretboard.render();

Output:

Exactly, that doesn’t change anything automatically. The fretboard constructor accepts a positionText function that helps us to achieve our goal:


import { Fretboard } from "@music-ui/fretboard";
 
const fretboard = new Fretboard({
  fretCount: 5,
  width: 600,
  positionText: (position) => position.note,
});
 
fretboard.setPositions([
  { string: 6, fret: 0, note: "E" },
  { string: 6, fret: 3, note: "G" },
  { string: 5, fret: 3, note: "C" },
  { string: 4, fret: 2, note: "E" },
  { string: 3, fret: 0, note: "G" },
  { string: 2, fret: 1, note: "C" },
  { string: 1, fret: 0, note: "E" },
  { string: 1, fret: 3, note: "G" },
]);
 
fretboard.render();

That’s brilliant! positionText is a callback that exposes every position and allows us to return what we need.

In this example we compiled the position information manually. The @music-ui/fretboard package contains scale and arpeggio generation utilities.

Style the positions

Let’s highlight the root notes of the arpeggio with the Fretboard.style function:


import { Fretboard } from "@music-ui/fretboard";
 
const fretboard = new Fretboard({
  fretCount: 5,
  width: 600,
  positionText: (position) => position.note,
});
 
fretboard.setPositions([
  { string: 6, fret: 0, note: "E" },
  { string: 6, fret: 3, note: "G" },
  { string: 5, fret: 3, note: "C" },
  { string: 4, fret: 2, note: "E" },
  { string: 3, fret: 0, note: "G" },
  { string: 2, fret: 1, note: "C" },
  { string: 1, fret: 0, note: "E" },
  { string: 1, fret: 3, note: "G" },
]);
 
fretboard.render();
 
fretboard.style({
  fill: (position) => (position.note === "C" ? "orange" : "white"),
});

Output:

The Fretboard.style functions accepts a key-value list of stylable properties and their corresponding values / function generating values.

Another approach is to use the filter property:


import { Fretboard } from "@music-ui/fretboard";
 
const fretboard = new Fretboard({
  fretCount: 5,
  width: 600,
  positionText: (position) => position.note,
});
 
fretboard.setPositions([
  { string: 6, fret: 0, note: "E" },
  { string: 6, fret: 3, note: "G" },
  { string: 5, fret: 3, note: "C" },
  { string: 4, fret: 2, note: "E" },
  { string: 3, fret: 0, note: "G" },
  { string: 2, fret: 1, note: "C" },
  { string: 1, fret: 0, note: "E" },
  { string: 1, fret: 3, note: "G" },
]);
 
fretboard.render();
 
fretboard.style({
  filter: (position) => position.note === "C",
  fill: "orange",
});

Same output:

Rendering chord diagrams

The Fretboard class has a convenient renderChord method:


import { Fretboard } from "@music-ui/fretboard";
 
const fretboard = new Fretboard({ fretCount: 3 });
 
fretboard.renderChord({ input: "x32010" });

Output:

See the chord diagrams page for more details.

Rendering scale diagrams

The Fretboard class has also, guess what, a renderScale method:


import { Fretboard } from "@music-ui/fretboard";
 
const fretboard = new Fretboard();
 
fretboard.renderScale({ root: "C", type: "major" });

Output:

See the scale diagrams page for more details.

Constructor parameters

The Fretboard constructor accepts the following parameters:

Property	Type	Default	Description
`element`	`string` \| `HTMLElement`	`#fretboard`	The container element or a valid CSS selector
`display`	`"contain"` \| `"cover"` \| `"overflow` \| `undefined`	`undefined`	The width behavior
`tuning`	`string[]`	`["E2", "A2", "D3", "G3", "B3", "E4"]`	The instrument tuning
`stringCount`	`number`	6	The amount of strings to render
`stringWidth`	`number` \| `number[]`	1	The string thickness
`stringColor`	`string`	`#666`	The string color
`fretCount`	`number`	15	The amount of frets to render
`fretWidth`	`number`	1	The fret width
`fretColor`	`string`	`#666`	The fret color
`nutWidth`	`number`	1	The nut width
`nutColor`	`string`	`#666`	The nut color
`middleFretWidth`	`number`	3	The middle fret width
`middleFretColor`	`string`	`#ff636c`	The middle fret color
`paddingTop`	`number`	20	The top padding around the svg element
`paddingBottom`	`number`	15	The bottom padding around the svg element
`paddingLeft`	`number`	20	The left padding around the svg element
`paddingRight`	`number`	20	The right padding around the svg element
`width`	`number`	960	The desired element width
`height`	`number`	150	The desired element height
`positionSize`	`number`	20	The fretboard position size
`positionStrokeColor`	`string`	`#555`	The fretboard position stroke color
`positionStrokeWidth`	`number`	2	The fretboard position stroke width
`positionFill`	`string`	`white`	The fretboard position fill color
`positionTextSize`	`number`	12	The fretboard position text size
`positionText`	`(position) => string`	`() => ""`	The fretboard position text getter
`disabledOpacity`	`number`	0.9	The opacity of the disabled frets
`crop`	`boolean`	`false`	If true, renders just the frets with positions in them
`fretPaddingLeft`	`number`	0	How many empty frets to display before the first rendered position
`scaleFrets`	`boolean`	`true`	If true, the fret will be scales logarithmically
`showFretNumbers`	`boolean`	`true`	If true, shows the fret numbers below the fretboard
`fretNumbersHeight`	`number`	40	The fret numbers height
`fretNumbersMargin`	`number`	20	The fret numbers top margin
`fretNumbersColor`	`string`	`#666`	The fret numbers color
`font`	`string`	`Arial`	The fret numbers color
`barresColor`	`string`	`#666`	The barres color
`highlightPadding`	`number`	10	The highlight areas padding
`highlightRadius`	`number`	10	The highlight areas border radius
`highlightStroke`	`string`	`transparent`	The highlight areas stroke color
`highlightFill`	`string`	`dodgerblue`	The highlight areas fill color
`highlightBlendMode`	`string`	`color-burn`	The highlight areas blend mode

The Fretboard class

Installation

Usage

Width behavior

Allow horizontal overflow

Contained in the parent element

Fill the available space

Displaying fretboard positions

Displaying the position text

Style the positions

Rendering chord diagrams

Rendering scale diagrams

Constructor parameters

The `Fretboard` class