# react-ukelele

> Small add-on to add svg ukelele chords into your app

Latest version **0.4.9** (published 2026-03-06) · MIT license · 0 weekly downloads

## Install

```sh
npm install react-ukelele
pnpm add react-ukelele
yarn add react-ukelele
bun add react-ukelele
```

## Health

**Score 60/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.4.9 |
| Published | 2026-03-06 |
| First published | 2020-08-02 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 61.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Jordi Llobet |
| Maintainers | jordillobet |
| Keywords | ukelele, svg, music, chords |

## Links

- npm: https://www.npmjs.com/package/react-ukelele
- Repository: https://github.com/newpatriks/ukelele
- Issues: https://github.com/newpatriks/ukelele/issues
- npm.io page: https://npm.io/package/react-ukelele

## Recent versions

- 0.4.9 (latest) — 2026-03-06
- 0.4.8 — 2026-02-22
- 0.4.7 — 2026-02-22
- 0.4.6 — 2023-07-05
- 0.4.5 — 2023-05-03
- 0.4.4 — 2023-05-03
- 0.4.3 — 2023-04-24
- 0.4.2 — 2023-04-24
- 0.4.1 — 2023-04-24
- 0.3.2 — 2020-08-10
- 0.3.1 — 2020-08-09
- 0.3.0 — 2020-08-09
- 0.2.0 — 2020-08-09
- 0.1.1 — 2020-08-02
- 0.1.0 — 2020-08-02

## README

# react-ukelele

[![npm version](https://img.shields.io/npm/v/react-ukelele.svg)](https://www.npmjs.com/package/react-ukelele)
[![npm downloads](https://img.shields.io/npm/dm/react-ukelele.svg)](https://www.npmjs.com/package/react-ukelele)
[![license](https://img.shields.io/npm/l/react-ukelele.svg)](./LICENSE)

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

[Live demo](https://upbeat-mccarthy-d9d9b5.netlify.app/chords/A)

<img src="http://jllobet.me/wp-content/uploads/2020/05/react-ukelele.gif" width="350px" />

---

## Install

```bash
npm install react-ukelele
```

Requires React ≥ 16.8 as a peer dependency.

---

## Usage

```tsx
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:

```ts
// 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

```bash
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

---
_Source: https://npm.io/package/react-ukelele · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._