A reusable react component that displays a fretboard, and lets you select notes, chords and scales.
yarn add react-fretboard
or
npm install react-fretboard
Besides the Fretboard component, this lib exports several functions (see API) that
help you select notes, chords, etc. react-fretboard uses the Tonal music theory library internally, and adopts it's naming conventions for notes, chords, etc. Check out Tonal, because you might want to use it together with react-fretboard
import React from 'react'
import Fretboard, { chordNotes } from 'react-fretboard'
const App = () =>
<div>
<Fretboard
skinType="strings"
selectedNotes={['C3', 'E3', 'G3']}
/>
</div>
export default AppThere's a live demo with many examples here: https://react-fretboard-demo.herokuapp.com
You can also clone the repo and run styleguidist (yarn styleguide), which will show interactive examples so you can experiment with the props.
tuning
arrayOf(string)
Array of pitch strings, from which all the fret notes are calculated. You can provide any tuning you want. Additionally the number of notes in the tuning array determine how many strings the fretboard will display.
The default is standard tuning for a 6 string guitar.
Example: tuning={['E2', 'A2', 'D3', 'G3', 'B3', 'E4']}
nrOfFrets
number
This sets the width of the fretboard. The number includes the open position, so 12 frets will need nrOfFrets={13}. 13 is also the default.
skinType
oneOf(['boxes', 'strings'])
Determines the overall look of the fretboard. 'boxes' displays the frets as divs with a border, and 'strings' looks more like a standard fretboard diagram.
Default is 'boxes'
noteType
oneOf(['pc', 'pitch'])
Sets what type of note is displayed in the frets, f.i.: C (pc, short for pitch class), or C4 (pitch). This is purely a visual setting, you can still select pc's or pitches. (see selectedNotes below)
Default is 'pitch'
showNotes
bool
Determines whether to show the (unselected) note names in the fretboard, or not. (This is overridden by a label of a selected note if showSelectionLabels is true)
Default is false
showSelectionLabels
bool
Determines whether to show the selected note label. (This overrides the showNotes prop)
Default is true
highlightOctaves
bool
Determines whether to show a fret's octave background color. (Is overridden by highlightSelections). You can provide your own octave colors with the theme prop.
Default is false
highlightSelections
bool
Determines wether to show a selected fret's background color. (This overrides the octave color). (see selectedNotes below for more information)
Default is true
showEnharmonics
bool
If a note has a (simple) enharmonic, like C#, this prop lets you choose to display just 'C#' or 'C#/Db'. The note name may become too large for the smaller frets, in which case it is clipped. Check the theme's fontSize property for a bit more control of fitting a note name in a fret.
Default is false
showPositionLabels
bool
Shows the position markers underneath the fretboard (like: I, III, VII, X).
Default is true
selectedNotes
arrayOf(oneOfType([
string,
shape({
note: string.isRequired,
status: string, // optional, default 'selected'
label: string, // optional, default note name
})
]))
This can get complicated, but basic usage is very simple. There are two ways to select notes:
- array of note names. Examples:
selectedNotes={['C']}, selects all C notes.
selectedNotes={['A3', 'D4']}, selects all A3 and D4 notes.
If you have highlightSlections true, it will look in the theme.statusMap.selected for the specified color, and use it to highlight the frets. If you have showSelectionLabels true, it will display note names. - array of note objects. Examples of note objects:
{ note: 'C', label: 'root', status: 'root' }, will select all C's, label them with 'root', and use theme.statusMap.root for the highlight color (which you'll need to specify)
{ note: 'C', status: 'root' }, will select all C's, label them with 'C', and use the color under theme.statusMap.root.
An example of a C3 triad could be:
selectedNotes={[{ note: 'C3', label: 'root', status: 'root' }, { note: 'E3', label: '3M', status: '3M' }, { note: 'G3', label: '5P', status: '5P' }]}
react-fretboardexports a couple of functions that help with generating these note objects.
selectedLocations
arrayOf(oneOfType([
shape({
str: number.isRequired,
pos: number.isRequired,
}),
shape({
loc: shape({
str: number.isRequired,
pos: number.isRequired,
}).isRequired,
status: string,
label: string,
})
]))
Lets you select frets based on their location on the fretboard. The top (1st) string is str: 0, and bottom string is str: tuning.length - 1.
This prop behaves almost identically to selectedNotes, except that instead of the note string, you'd use a loc object.
theme
Specify a theme to customize the style of the fretboard. (see CSS)
clickAction
func
Provide a callback that will be called when a fret is clicked. The arg passed is an object with props: { note, loc }
These are convenience functions, and you may not need to use them. F.i: these props have the equivalent result on the fretboard:
selectedNotes={['C', 'E']}
selectedNotes={intervalNotes('C', 4)}
or these:
selectedNotes={['C', 'E', 'G']}
selectedNotes={Tonal.Chord.notes('CM')} using the Tonal library
selectedNotes={chordNotes('CM')}
They become more useful when, instead of note names, you want to show the relative intervals of selected notes, by using the useIvlLabel and useIvlStatus params. With useIvlLabel = true the selection labels will be set to interval names. With useIvlStatus = true the highlight color will be theme.statusMap.[ivlName]. Check the examples below.
intervalNotes(note, ivl, useIvlLabel = false, useIvlStatus = false)
Examples:
intervalNotes('C', 4) - returns array of note objects, C and E, with label set to note name and status 'selected'
intervalNotes('C', 4, true) - returns array of note objects, C and E, with labels set to 1P and 3M, and status 'selected'.
intervalNotes('C', 4, true, true) - returns array of note objects, C and E, with labels and status set to 1P and 3M.
chordNotes(chord, useIvlLabel = false, useIvlStatus = false)
Examples:
chordNotes('CM') - returns array of note objects, C, E and G, with label set to note name and status 'selected'
chordNotes('CM', true) - returns array of note objects, C, E and G, with labels set to 1P, 3M and 5P, and status 'selected'.
chordNotes('CM', true, true) - returns array of note objects, C, E and G, with labels and status set to 1P, 3M and 5P.
scaleNotes(tonic, scale, useIvlLabel = false, useIvlStatus = false)
Examples:
scaleNotes('C', 'major') - returns array of note objects of the C major scale, with label set to note name and status 'selected'
scaleNotes('C', 'major', true) - returns array of note objects of the C major scale, with labels set to their respective interval names, and status 'selected'.
scaleNotes('C', 'major', true, true) - returns array of note objects of the C major scale, with labels and status set to their respective interval names.
react-fretboard uses styled-components for it's styling. You can provide your own theme by passing it through the theme prop. This is the default theme:
{
background: 'white',
statusMap: {
selected: 'rgb(255, 252, 127)',
unselected: 'white',
'1P': '#1a0500',
'2m': '#4d0f00',
'2M': '#801a00',
'3m': '#cc2900',
'3M': '#e62e00',
'4P': '#ff3300',
'4A': '#ff5c33',
'5P': '#ff704d',
'6m': '#ff9980',
'6M': '#ffb199',
'7m': '#ffd8cc',
'7M': '#ffebe6',
},
octaveMap: {
2: 'rgb(95, 190, 244)',
3: 'rgb(135, 219, 244)',
4: 'rgb(205, 240, 247)',
5: 'rgb(242, 246, 247)',
},
fontSize: 12,
dimensions: {
openWidth: 10,
nutWidth: 0.75,
stringHeight: 30,
},
skins: {
strings: {
highlightSize: 85,
highlightBorder: '1px solid gray',
},
},
}fontSize - in px
dimensions.openWidth - percentage width of the open position
dimensions.nut - percentage width of the nut
dimensions.stringHeight - height of strings in px
skins.strings.highlightSize - percentage of stringHeight
You can specify any theme attribute you want, as long as you keep the theme structure. It will be merged against the default theme.