@paul-joy/react-guitar-chords

A lightweight React component to render SVG guitar chord diagrams. Inspired by @tombatossals/react-chords and modernized for React 19 with ESM/CJS builds and TypeScript types.

Install

npm i @paul-joy/react-guitar-chords
# or
yarn add @paul-joy/react-guitar-chords
# or
pnpm add @paul-joy/react-guitar-chords
# or
bun add @paul-joy/react-guitar-chords

Requires React 19 in your app.

Quick start

import React from "react";
import Chord from "@paul-joy/react-guitar-chords";

const instrument = {
  tunings: { standard: ["E", "A", "D", "G", "B", "E"] },
  strings: 6,
  fretsOnChord: 5,
};

// Example: A minor (positions are from low-E to high-e; -1 = muted)
const chord = {
  frets: [0, 0, 2, 2, 1, 0],
  fingers: [0, 0, 3, 2, 1, 0],
  barres: [],
  baseFret: 1,
};

export default function Example() {
  return <Chord chord={chord} instrument={instrument} />;
}

Barre chords

const eMajorBarreOn7 = {
  frets: [7, 9, 9, 8, 7, 7],
  fingers: [1, 3, 4, 2, 1, 1],
  barres: [7],
  capo: true,
  baseFret: 1,
};

<Chord chord={eMajorBarreOn7} instrument={instrument} />;

Lite mode and theming

// Minimal rendering (hides labels and extras)
<Chord chord={chord} instrument={instrument} lite />;

// Customize colors
const theme = {
  primaryColor: "#222",
  textColor: "#fff",
  fretPositionColor: "#888",
};

<Chord chord={chord} instrument={instrument} theme={theme} />;

API

• Default export: Chord

• Props

  • chord: object describing the fingering
    • frets: number[] — fret per string, from low‑E to high‑e; 0 = open, -1 = muted
    • barres?: number[] — fret numbers that are barred
    • capo?: boolean — show capo style on the first barre (if any)
    • fingers?: number[] — finger numbers per string
    • baseFret: number — base fret index for display (1 = nut)
  • instrument: object describing the instrument layout
    • tunings.standard: string[] — e.g. ["E","A","D","G","B","E"]
    • strings: number — number of strings
    • fretsOnChord: number — how many frets to render in the viewport
  • lite?: boolean — simplified rendering
  • theme?: object — colors used for rendering
    • primaryColor: string
    • textColor: string
    • fretPositionColor: string

TypeScript helper types (simplified):

type ChordType = {
  frets: number[];
  barres?: number[];
  capo?: boolean;
  fingers?: number[];
  baseFret: number;
};

type InstrumentType = {
  tunings: { standard: string[] };
  strings: number;
  fretsOnChord: number;
};

type ThemeType = {
  primaryColor: string;
  textColor: string;
  fretPositionColor: string;
};

Import styles

// ESM
import Chord from "@paul-joy/react-guitar-chords";

// CommonJS
const Chord = require("@paul-joy/react-guitar-chords").default;

License

MIT © paul-joy