Skip to content

omnibrain/svguitar

master
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Files

Permalink
Failed to load latest commit information.

SVGuitar - JavaScript Guitar Chord Renderer

build styled with prettier Coveralls semantic-release Known Vulnerabilities Code Style

JavaScript (TypeScript) library to create beautiful SVG guitar chord charts directly in the browser.

To see this library in action check out chordpic.com, a free online chord diagram creator.

Demo: https://omnibrain.github.io/svguitar/ [ source ]

TypeScript API Documentation: https://omnibrain.github.io/svguitar/docs/

Example chord charts:

Example Chord Chart 1 Example Chord Chart 2 Example Chord Chart 3 Example Chord Chart 4

Getting Started

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

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

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

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

Of course you can also add SVGuitar as a dependency to your project:

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

# or
yarn add svguitar

And then import it in your project:

import { SVGuitarChord } from 'svguitar'

const chart = new SVGuitarChord('#chart')

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

Usage

The SVG charts are highly customizable. For a full API documentation have a look at the TypeScript documentation.

Chart configuration is completely optional, you don't have to pass any configuration or you can only override specific settings.

Here's an example of a very customized chart:

new SVGuitarChord('#some-selector')
  .chord({
    // array of [string, fret, text | options]
    fingers: [
      // finger at string 1, fret 2, with text '2'
      [1, 2, '2'],

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

      // finger is triangle shaped
      [3, 3, { shape: 'triangle' }],
      [6, 'x'],
    ],

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

    // title of the chart (optional)
    title: 'F# minor',

    // position (defaults to 1)
    position: 2,
  })
  .configure({
    // Customizations (all optional, defaults shown)

    /**
     * Orientation of the chord diagram. Chose between 'vertical' or 'horizontal'
     */
    orientation: 'vertical',

    /**
     * Select between 'normal' and 'handdrawn'
     */
    style: 'normal',

    /**
     * The number of strings
     */
    strings: 6,

    /**
     * The number of frets
     */
    frets: 4,

    /**
     * Default position if no positon is provided (first fret is 1)
     */
    position: 1,

    /**
     * These are the labels under the strings. Can be any string.
     */
    tuning: ['E', 'A', 'D', 'G', 'B', 'E'],

    /**
     * The position of the fret label (eg. "3fr")
     */
    fretLabelPosition: 'right',

    /**
     * The font size of the fret label
     */
    fretLabelFontSize: 38,

    /**
     * The font size of the string labels
     */
    tuningsFontSize: 28,

    /**
     * Size of a finger or barre relative to the string spacing
     */
    fingerSize: 0.65,

    /**
     * Color of a finger or barre
     */
    fingerColor: '#000',

    /**
     * The color of text inside fingers and barres
     */
    fingerTextColor: '#FFF',

    /**
     * The size of text inside fingers and barres
     */
    fingerTextSize: 22,

    /**
     * stroke color of a finger or barre. Defaults to the finger color if not set
     */
    fingerStrokeColor: '#000000',

    /**
     * stroke width of a finger or barre
     */
    fingerStrokeWidth: 0,

    /**
     * stroke color of a barre chord. Defaults to the finger color if not set
     */
    barreChordStrokeColor: '#000000',

    /**
     * stroke width of a barre chord
     */
    barreChordStrokeWidth: 0,

    /**
     * Height of a fret, relative to the space between two strings
     */
    fretSize: 1.5,

    /**
     * The minimum side padding (from the guitar to the edge of the SVG) relative to the whole width.
     * This is only applied if it's larger than the letters inside of the padding (eg the starting fret)
     */
    sidePadding: 0.2,

    /**
     * The font family used for all letters and numbers
     */
    fontFamily: 'Arial, "Helvetica Neue", Helvetica, sans-serif',

    /**
     * Default title of the chart if no title is provided
     */
    title: 'F# minor',

    /**
     * Font size of the title. This is only the initial font size. If the title doesn't fit, the title
     * is automatically scaled so that it fits.
     */
    titleFontSize: 48,

    /**
     * Space between the title and the chart
     */
    titleBottomMargin: 0,

    /**
     * Global color of the whole chart. Can be overridden with more specifig color settings such as
     * @link titleColor or @link stringColor etc.
     */
    color: '#000000',

    /**
     * The background color of the chord diagram. By default the background is transparent. To set the background to transparent either set this to 'none' or undefined
     */
    backgroundColor: 'none',

    /**
     * Barre chord rectangle border radius relative to the fingerSize (eg. 1 means completely round endges, 0 means not rounded at all)
     */
    barreChordRadius: 0.25,

    /**
     * Size of the Xs and Os above empty strings relative to the space between two strings
     */
    emptyStringIndicatorSize: 0.6,

    /**
     * Global stroke width
     */
    strokeWidth: 2,

    /**
     * The width of the nut (only used if position is 1)
     */
    nutWidth: 10,

    /**
     * If this is set to `true`, the starting fret (eg. 3fr) will not be shown. If the position is 1 the
     * nut will have the same width as all other frets.
     */
    noPosition: false,

    /**
     * The color of the title (overrides color)
     */
    titleColor: '#000000',

    /**
     * The color of the strings (overrides color)
     */
    stringColor: '#000000',

    /**
     * The color of the fret position (overrides color)
     */
    fretLabelColor: '#000000',

    /**
     * The color of the tunings (overrides color)
     */
    tuningsColor: '#000000',

    /**
     * The color of the frets (overrides color)
     */
    fretColor: '#000000',

    /**
     * When set to true the distance between the chord diagram and the top of the SVG stayes the same,
     * no matter if a title is defined or not.
     */
    fixedDiagramPosition: false,

    /**
     * Text of the watermark (text on the bottom of the chart)
     */
    watermark: 'some watermark',

    /**
     * Font size of the watermark
     */
    watermarkFontSize: 12,

    /**
     * Color of the watermark (overrides color)
     */
    watermarkColor: '#000000',

    /**
     * Font-family of the watermark (overrides fontFamily)
     */
    watermarkFontFamily: 'Arial, "Helvetica Neue", Helvetica, sans-serif',

    /**
     * The title of the SVG. This is not visible in the SVG, but can be used for accessibility.
     */
    svgTitle: 'Guitar chord diagram of F# minor',
  })
  .draw()

Contribute

Pull Requests are very welcome!

Projects using SVGuitar

Here are some projects that use svguitar:

Are you using SVGuitar? Create an issue to get your project listed here! Or simply create a pull request with your project added.