Chord diagrams

Manually passing an array of positions to a Fretboard can be tedious.

The Fretboard.renderChord method accepts a shorthand input, in the format found in chord/tab websites.

The shorthand format

The convention are the following:

the input must have 6 entries (one per string) if all the frets are single digits;
for double digits frets, the entries must be hyphen separated.
the entries are read from the 6th string up to the 1st;
every entry stands for the fret at the corresponding string;
a 0 stands for the corresponding open string;
a x mutes the corresponding string.

Some examples:

x32010 is an open C chord;
133211 is an F chord in first position;
x-10-12-12-11-10 is a G minor in tenth position.

Rendering a C major open chord

Setup code:


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

Output:

Displaying note names

The renderChord method associates the corresponding note name to every position.

We can access it in the positionText option:


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

Output:

When the initChords function is used, you can directly set data-text-property="note" on the element to display the note name.

Render the right note names (sharps vs. flats)

Being the guitar a tempered instrument, notes like Eb and D# coincide on the fretboard.

In order to display the right note name, we have to pass the chord name to the renderChord method:


import { Fretboard } from "@music-ui/fretboard";
 
const fretboard = new Fretboard({
  fretCount: 3,
  positionText: ({ name }) => name,
});
 
fretboard.renderChord({ input: "133111", chordName: "F minor" });

Output:

Without the chordName parameter, sharps are the default:


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

Output:

Another example that includes both sharp and flat symbols, e.g. D7b9:


import { Fretboard } from "@music-ui/fretboard";
 
const fretboard = new Fretboard({
  fretCount: 5,
  positionText: ({ name }) => name,
});
 
fretboard.renderChord({ input: "x5454x", chordName = "D7b9" });

Output:

Note: the enharmonic equivalents are preferred in altered scenarios like a 7#9 chord, see:


import { Fretboard } from "@music-ui/fretboard";
 
const fretboard = new Fretboard({
  fretCount: 5,
  positionText: ({ name }) => name,
});
 
fretboard.renderChord({ input: "x5456x", chordName = "D7#9" });

Output:

The F should be spelled as E#, but a fretboard diagram is not a music score.
So if you tell me to accent the F double sharp on the Hendrix chord, we cannot jam together dude.

Include open strings

You can display the open string positions by passing includeOpenStrings: true to the renderChord method.
This is useful if you want to show all notes being played.


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

Output:

Displaying barre indications

Some chords require barres (fretting multiple strings with one finger).
Usually this is indicated with a vertical line across all the covered frets.

The renderChord method accepts a barres parameter, that can be either:

a single Barre;
an array of Barres;
a shorthand string.

Examples:


// single barre on the 2nd fret, from the fourth string to the second
{ fret: 2, stringFrom: 4, stringTo: 2 }
 
// array of barres
[
  { fret: 2, stringFrom: 5 }, // no stringTo means up to the 1st string
  { fret: 4, stringFrom: 4, stringTo: 2 },
]
 
// shorthand string - a comma separated list of {fret}:{stringFrom?}:{stringTo?}
// the array above can be serialized as follows:
"2:5,4:4:2"

This is the code to display an F major chord in first position, with a barre across the whole first fret (remember how much you struggled getting it right on your awfully setup first acoustic):


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

Output:

Partial barres

You can display partial barres with the stringFrom and stringTo properties of the Barre type:


import { Fretboard } from "@music-ui/fretboard";
 
const fretboard = new Fretboard({ fretCount: 3 });
 
fretboard.renderChord({ input: "xx1211", barres: { fret: 1, stringFrom: 4 } });

Output:

Multiple barres

Need to play that pesky F7#9 in first position? No worries!


import { Fretboard } from "@music-ui/fretboard";
 
const fretboard = new Fretboard({ fretCount: 3 });
 
fretboard.renderChord({
  input: "131244",
  barres: [
    { fret: 1, stringTo: 4 },
    { fret: 4, stringFrom: 2 },
  ],
});

Output:

Cropping to the desired frets

We want to focus on the chord position, without displaying the empty frets before it.

Pass crop: true and showFretNumbers: true to the Fretboard constructor to show just the relevant frets with the corresponding fret numbers.

This renders a C minor chord in third position:


import { Fretboard } from "@music-ui/fretboard";
 
const fretboard = new Fretboard({
  fretCount: 3,
  crop: true,
  showFretNumbers: true,
});
 
fretboard.renderChord({
  input: "x35543",
  barres: { fret: 3, stringFrom: 5 },
});

Output:

The `initChords` function

If you need a quick way to set up your chord diagrams, you can use the initChords function.

By default, it selects all [data-chord] elements on the page, and extracts the needed configuration from their data attributes:


<div
  data-chord
  data-input="x32010"
  data-chord-name="C major"
  data-text-property="note"
  data-include-open-strings
/>
<div
  data-chord
  data-input="x5454x"
  data-chord-name="D7b9"
  data-text-property="note"
  data-crop
  data-show-fret-numbers
/>
<div
  data-chord
  data-input="131244"
  data-chord-name="F7#9"
  data-barres="1:6:4,4:2"
  data-text-property="note"
  data-show-fret-numbers
/>

Setup code:


import { initChords } from "@music-ui/fretboard";
 
initChords();

Output:

C major

D7b9

F7#9

Custom selection

You can pass a custom selector or collection of elements via the selection option. In this example we’ll select all .chord elements:


<div
  class="chord"
  data-input="x32010"
  data-chord-name="C major"
  data-text-property="note"
  data-include-open-strings
/>

Setup code:


import { initChords } from "@music-ui/fretboard";
 
// via selector string
initChords({ selection: ".chord" });
 
// via actual DOM selection
initChords({ selection: document.querySelectorAll(".chord") });

Render options

The following data attributes are supported:

Attribute	Type	Description
`data-input`	`string`	The chord input (e.g. x32010).
`data-chord-name`	`string`	The chord name (e.g. C major, A7b9).
`data-crop`	`boolean`	Crops the fretboard to the used positions only
`data-include-open-strings`	`boolean`	Shows the open string notes.
`data-text-property`	`"note"` \| `"degree"` \| `"interval"`	The position property to display
`data-show-fret-numbers`	`boolean`	Shows the fret numbers.
`data-barres`	`string`	The chord barres.

Chord diagrams

The shorthand format

Rendering a C major open chord

Displaying note names

Render the right note names (sharps vs. flats)

Include open strings

Displaying barre indications

Partial barres

Multiple barres

Cropping to the desired frets

The initChords function

Custom selection

Render options

The `initChords` function