svguitar: rendering SVG guitar chord charts in the browser

Vector chord diagrams instead of exported images

Every guitar tutorial site faces the same small problem: how to show a chord. The usual answers are a PNG produced once by a designer, or a chunk of SVG copied by hand. Both age badly. The image cannot be restyled, cannot be translated, and cannot respond to the page around it. Hand-written SVG works until there are two hundred chords and the markup becomes the maintenance burden.

svguitar is a JavaScript library, written in TypeScript, that generates those charts as SVG directly in the browser. The output is live DOM, so it scales, takes colours from CSS, and can be changed when the chart is redrawn. That is the problem it solves, and it is aimed at developers building chord display into a web page: the library's own demo site and the chordpic.com chord diagram creator both exist to show what that looks like.

The scope is deliberate. The library is described as a renderer of charts, and the API reflects that. There is no catalogue of chord shapes, no theory engine, and no search. You decide what a C major looks like and the library draws it.

The chain is configure, chord, draw

The API is a small fluent chain, and the shape of it explains the design.

You create an SVGuitarChord instance with a CSS selector, then call configure with appearance settings, then chord with the musical content, then draw. Each call returns the instance, so the calls chain. The two data halves are deliberately separate: configuration is presentation and is entirely optional, while the chord argument is the shape itself.

The result is appended to the element your selector points at, which means the library owns the container it was given and does not require you to manage a separate SVG element. For a page that shows one chart, that is the whole integration. For a page that shows many, each instance targets its own selector.

Because the chart is drawn from data rather than parsed from a chord name, re-rendering with a different shape is just another call to chord followed by draw, and there is no image cache to invalidate.

Getting it into a page: script tag, npm, or the scoped package

The quickest way to see it work is a script tag and a div. The UMD build is served from the project's GitHub Pages, and the global it exposes is svguitar:

<!--container of the chart-->
<div id="chart"></div>

<!--load umd script -->
<script src="https://omnibrain.github.io/svguitar/js/svguitar.umd.js"></script>

With the container and the UMD bundle in place, the chart is created and drawn from a script tag:

<script>
  // initialize the chart
  var chart = new svguitar.SVGuitarChord('#chart')

  // draw the chart
  chart
    .configure({
      /* configuration */
    })
    .chord({
      /* chord */
    })
    .draw()
</script>

For a project with a build step, the package is a normal dependency:

# Add the dependency to your project
npm install --save svguitar

# or
yarn add svguitar

# or
pnpm add svguitar

The same package is also published under the scoped name @svguitar/core, which matters if you prefer a namespace, or if a plain svguitar name is taken on your registry. The import is the same either way:

import { SVGuitarChord } from 'svguitar'

const chart = new SVGuitarChord('#chart')

// draw the chart
chart
  .configure({
    /* configuration */
  })
  .chord({
    /* chord */
  })
  .draw()

The package ships type definitions at dist/types/svguitar.d.ts, and the API documentation is generated with typedoc and published as a site, so the editor and the docs page come from the same source.

Fingers and barres are arrays, not chord names

This is the part that decides whether the library fits your project. The chord argument is not a name. It is a list of finger positions, where each entry is a string number, a fret, and either a text label or an options object.

  .chord({
    // array of [string, fret, text | options]
    fingers: [
      // finger at string 2, fret 2, with text '2'
      [2, 2, '2'],

      // finger at string 3, fret 3, with text '4', colored red and has class 'red'
      [3, 3, { text: '4', color: '#F00', className: 'red' }],

      // finger at string 4, fret 3, with text '3', triangle shaped
      [4, 3, { text: '3', shape: 'triangle' }],

      // an 'x' above string 6 denotes it isn't played
      [6, 'x'],
    ],

A string index with a fret number is a pressed note, the third element is the finger number to print, and the string 'x' marks a string that is not played. The options object adds colour, a CSS class, and a shape. Because the class name is yours to choose, styling the chart from a stylesheet is a supported path rather than a hack.

Barre chords use a separate array, with a fromString and toString range, the fret, and their own colour and class options:

    // optional: barres for barre chords
    barres: [
      {
        fromString: 5,
        toString: 1,
        fret: 1,
        text: '1',
        color: '#0F0',
        textColor: '#F00',
        className: 'my-barre-chord',
        style: 'rectangle' // use 'arc' for an arc
      },
    ],

The trade is direct. You get total control over what is drawn and complete freedom in the shapes you support, but the chord knowledge has to live in your application.

Configuration covers orientation, handedness, labels and metrics

Presentation is a single options object, and every entry has a documented default. The guide lists every option with its default. orientation takes 'vertical' or 'horizontal', leftHanded mirrors the diagram for left handed players, where the string order is reversed in vertical orientation and the nut sits on the right in horizontal orientation while the text stays readable, and style selects between 'normal' and 'handdrawn'.

The rest of the options are numeric and positional, which is where the library is unusually explicit. strings defaults to 6 and frets to 4, so a four string bass diagram is a configuration change rather than a different library. position sets the starting fret, with the first fret numbered 1, and the same number appears as a label. tuning holds the string labels, and fretLabelPosition places the label on the right by default.

Labels are configurable in several ways. fretLabelFormat accepts 'fr' for a value like 5fr, 'number' for 5, 'roman' for V, 'ordinal' for 5th, or 'ordinal-with-fr' for 5th Fr, and it can also be a function that returns the label for a position, which is how you would render a custom naming scheme.

Sizes are relative where it makes sense: fingerSize is the size of a finger or barre relative to the string spacing, fretSize is the height of a fret relative to the space between strings, and sidePadding is minimum padding from the guitar to the edge of the SVG relative to the whole width, applied only when it is larger than the text inside the padding. Font sizes for the title, the string labels and the fret label are plain numbers, with the title size being an initial value that is scaled down automatically when the title does not fit.

Fonts ship with the package, and the build is typedoc plus rollup

Two details of the package layout are worth knowing before you bundle it.

The first is fonts. The published files include fonts/OpenSans-Regular.ttf, fonts/PatrickHand-Regular.woff2, and fonts/OFL.txt, which is the licence text for those fonts. Shipping the font files in the package rather than relying on a web font from a CDN means the handdrawn style and the default metrics render the same way offline and in an app, at the cost of a few hundred kilobytes in your bundle. The configuration also exposes a fontFamily option, so the chart can use a typeface you already load.

The second is the build. The package scripts break the build into four steps: build:tsc compiles the TypeScript to CommonJS, build:rollup produces the bundles through rollup.config.ts, build:typedoc generates the API documentation from src/svguitar.ts, and build:demo builds the demo site through a script in the tools directory. The entry points in package.json are main pointing at dist/svguitar.umd.js, module at dist/svguitar.es5.js, and typings at dist/types/svguitar.d.ts.

Testing is jest with coverage, linting is eslint with a project config, formatting is prettier, and husky and lint-staged are wired into the commit path. Releases are automated with semantic-release, and a conventional commit is driven by commitizen through git-cz.

Where it fits, and what it is not for

The honest limitation comes first: svguitar does not know any chords. It has no voicing database and no chord name parsing, so a page that wants to show whatever chord a user types has to bring that data itself, and the format for a shape is limited to the notations described above. For a site with a fixed set of shapes, that is exactly right, and the drawing is consistent. For a tool that accepts arbitrary chord names, it is a gap you would have to fill with a shapes library of your own.

The second limitation is that rendering happens in the browser. The library draws into the page, so it belongs in a client context. Anything that needs a chart as a server-side artefact, a PDF, or an image for social sharing needs a different route, and the repository does not document one.

The alternative to using this library is to generate the SVG yourself, which is what many sites did before, and the difference in approach is where the value sits. Hand-written markup gives you a single fixed chart with no configuration surface. A static image pipeline gives you charts that are fixed at generation time and cannot react to the page. svguitar takes the diagram geometry and makes it a function of data plus options, which is why the same library serves a four string bass, a left handed player, and a handdrawn style without separate assets.

Maintenance is recent and busy. The last push was on 2026-10-17, the same day that v2.10.0 and v2.10.1 were published, with v2.9.0 a little over a week earlier. The licence is MIT, and one oddity is worth knowing about: the version field in the checked-in package.json still reads 1.0.0-development, because semantic-release computes the published version from commit messages rather than from that file.

Editorial conclusion

svguitar suits anyone building a chord display into a web page who wants vector output they can restyle with CSS and JavaScript rather than a static image, and it is the wrong tool for a quick lookup of chord shapes, because the library has no database of chord voicings and expects you to pass finger and barre positions yourself. Before adopting it, check the shapes you need against the fingers array format, since an 'x' marker and a numeric fret are the only two notations it understands, and confirm the version you install, because the published package now sits in the 2.10 line while the checked-in package.json still carries a development placeholder.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. omnibrain/svguitar on GitHub
4. README
5. Releases