Options
All
  • Public
  • Public/Protected
  • All
Menu

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.

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 nut relative to the string spacing
     */
    nutSize: 0.65,

    /**
     * Color of a finger / nut
     */
    nutColor: '#000',

    /**
     * The color of text inside nuts
     */
    nutTextColor: '#FFF',

    /**
     * The size of text inside nuts
     */
    nutTextSize: 22,

    /**
     * stroke color of a nut. Defaults to the nut color if not set
     */
    nutStrokeColor: '#000000',

    /**
     * stroke width of a nut
     */
    nutStrokeWidth: 0,

    /**
     * stroke color of a barre chord. Defaults to the nut 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 nutSize (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 top fret (only used if position is 1)
     */
    topFretWidth: 10,

    /**
     * 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,
  })
  .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.

Index

Type aliases

AnyFunction

AnyFunction: (...args: any) => any

Type declaration

    • (...args: any): any
    • Parameters

      • Rest ...args: any

      Returns any

ApiExtension

ApiExtension: {}

Type declaration

  • [key: string]: any

Barre

Barre: { className?: undefined | string; color?: undefined | string; fret: number; fromString: number; strokeColor?: undefined | string; strokeWidth?: undefined | number; text?: undefined | string; textColor?: undefined | string; toString: number }

Type declaration

  • Optional className?: undefined | string
  • Optional color?: undefined | string
  • fret: number
  • fromString: number
  • Optional strokeColor?: undefined | string
  • Optional strokeWidth?: undefined | number
  • Optional text?: undefined | string
  • Optional textColor?: undefined | string
  • toString: number

Chord

Chord: { barres: Barre[]; fingers: Finger[]; position?: undefined | number; title?: undefined | string }

Type declaration

  • barres: Barre[]

    The barre chords

  • fingers: Finger[]

    The fingers (nuts)

  • Optional position?: undefined | number

    Position (defaults to 1). Can also be provided via ChordSettings.

  • Optional title?: undefined | string

    Title of the chart. Can also be provided via ChordSettings.

Constructor

Constructor<T>: {}

Type parameters

  • T

Type declaration

Finger

Finger: [number, number | OpenString | SilentString, undefined | string | FingerOptions]

OpenString

OpenString: 0

ReturnTypeOf

ReturnTypeOf<T>: T extends AnyFunction ? ReturnType<T> : T extends AnyFunction[] ? UnionToIntersection<ReturnType<T[number]>> : never

Type parameters

SVGuitarPlugin

SVGuitarPlugin: (instance: SVGuitarChord) => ApiExtension | undefined

Type declaration

SilentString

SilentString: "x"

UnionToIntersection

UnionToIntersection<Union>: (Union extends any ? (argument: Union) => void : never) extends (argument: infer Intersection) => void ? Intersection : never

Type parameters

  • Union

Variables

Const FONT_FAMLILY

FONT_FAMLILY: "Patrick Hand" = "Patrick Hand"

Currently the font is hard-coded to 'Patrick Hand' when using the handdrawn chord diagram style. The reason is that the font needs to be base64 encoded and embedded in the SVG. In theory a web-font could be downloaded, base64 encoded and embedded in the SVG but that's too much of a hassle. But if the need arises it should be possible.

Const OPEN

OPEN: OpenString = 0

Value for an open string (O)

Const SILENT

SILENT: SilentString = "x"

Value for a silent string (X)

Functions

isNode

  • isNode(): boolean

range

  • range(length: number, from?: number): number[]
  • Parameters

    • length: number
    • Default value from: number = 0

    Returns number[]

Object literals

Const constants

constants: object

width

width: number = 400

The viewbox width of the svg

Const defaultSettings

defaultSettings: object

barreChordRadius

barreChordRadius: number = 0.25

barreChordStrokeWidth

barreChordStrokeWidth: number = 0

color

color: string = "#000"

emptyStringIndicatorSize

emptyStringIndicatorSize: number = 0.6

fontFamily

fontFamily: string = "Arial, "Helvetica Neue", Helvetica, sans-serif"

fretLabelFontSize

fretLabelFontSize: number = 38

fretLabelPosition

fretLabelPosition: RIGHT = FretLabelPosition.RIGHT

fretSize

fretSize: number = 1.5

frets

frets: number = 5

nutSize

nutSize: number = 0.65

nutStrokeWidth

nutStrokeWidth: number = 0

nutTextColor

nutTextColor: string = "#FFF"

nutTextSize

nutTextSize: number = 24

orientation

orientation: vertical = Orientation.vertical

position

position: number = 1

shape

shape: CIRCLE = Shape.CIRCLE

sidePadding

sidePadding: number = 0.2

strings

strings: number = 6

strokeWidth

strokeWidth: number = 2

style

style: normal = ChordStyle.normal

titleBottomMargin

titleBottomMargin: number = 0

titleFontSize

titleFontSize: number = 48

topFretWidth

topFretWidth: number = 10

tuning

tuning: never[] = []

tuningsFontSize

tuningsFontSize: number = 28

Legend

  • Constructor
  • Method
  • Private property
  • Private method
  • Static property
  • Static method
  • Property
  • Protected property

Generated using TypeDoc