react-ukelele

react-ukelele

Renders ukulele chord diagrams as inline SVG. No canvas, no images — just a React component.

Live demo

---

Install

npm install react-ukelele

Requires React ≥ 16.8 as a peer dependency.

---

Usage

import Ukelele from 'react-ukelele';

function App() {
  return <Ukelele chord="A" />;
}

Props

Prop	Type	Default	Description
chord	string	"A"	Chord name to display (see list below)
width	number	300	SVG width in pixels
height	number	300	SVG height in pixels
showLabel	boolean	true	Show the chord name label inside the SVG

Returns null if the chord name is not recognised.

---

Available chords

Root	Variants
A	A, Amaj, Am, Am7, Amaj7, A7sus4
B	B, Bmaj, Bm, Bm7, Bmaj7, Bb
C	C, Cmaj, Cm, Cm7, Cmaj7, Cadd9
D	D, Dmaj, Dm, Dm7, Dmaj7, Dsus4
E	E, Emaj, Em, Em7, Emaj7
F	F, Fmaj, Fm, Fmaj7, F#, F#m
G	G, Gmaj, Gm, Gm7, Gmaj7

Solfège names are also accepted (Do, Re, Mi, Fa, Sol, La, Si and their minor/7th variants).

---

Adding custom chords

Each chord is a list of finger positions. Each finger specifies which strings it covers (1 = highest, 4 = lowest), the fret, and an id:

// Simple chord — one finger on one string
const C = [{ string: [1], fret: 2, fingerId: 1 }];

// Complex chord — multiple fingers
const G = [
  { string: [1], fret: 2, fingerId: 1 },
  { string: [3], fret: 2, fingerId: 2 },
  { string: [2], fret: 3, fingerId: 3 },
];

Add entries to src/constants/chords.ts and the component will pick them up automatically.

---

Development

npm run dev          # start Vite dev server with live demo
npm run type-check   # TypeScript type checking
npm run lint         # ESLint
npm run test         # Vitest test suite
npm run build        # production build → dist/

---

Contributing

1. Fork the repo and create a branch
2. Make your changes with tests where relevant
3. Run npm run type-check && npm run lint && npm run test — all must pass
4. Open a pull request

---

License

MIT Jordi Llobet