Custom Elements

Grigson provides a <grigson-chart> custom element for declarative chart rendering in HTML pages. Load the auto-registering bundle and drop the element anywhere in your markup — no JavaScript required for basic usage.

See Getting started for how to load the bundle.

Inline template

Place the chart source in a <template> child. The normalise attribute corrects enharmonic spelling for the detected key.

<grigson-chart normalise>
  <template>
---
title: Autumn Leaves
key: G minor
---
[A]
| Am7b5 | D7 | Gm | Gm |
| Am7b5 | D7 | Gm | Gm |
[B]
| Cm7 | F7 | Bbmaj7 | Bbmaj7 |
| Am7b5 | D7 | Gm | Gm |
  </template>
</grigson-chart>

External template — multi-key transposition

A single <template id="..."> can be referenced by multiple <grigson-chart> elements via the template attribute. This is useful for producing the same chart in different keys for different instruments:

• Concert pitch — no transposition
• Bb instruments (trumpet, clarinet, tenor sax) — sound a major 2nd lower than written, so transpose up 2 semitones
• Eb instruments (alto sax, baritone sax) — sound a major 6th lower than written, so transpose up 9 semitones

<template id="autumn-leaves">
---
title: Autumn Leaves
key: G minor
---
[A]
| Am7b5 | D7 | Gm | Gm |
...
</template>

<!-- Concert pitch -->
<grigson-chart template="autumn-leaves" normalise></grigson-chart>

<!-- Bb instruments: transpose +2 semitones -->
<grigson-chart template="autumn-leaves" normalise transpose-semitones="2"></grigson-chart>

<!-- Eb instruments: transpose +9 semitones -->
<grigson-chart template="autumn-leaves" normalise transpose-semitones="9"></grigson-chart>

Concert pitch

Bb instruments (+2 semitones)

Eb instruments (+9 semitones)

Explicit renderer — <grigson-html-renderer>

By default <grigson-chart> uses the built-in HTML renderer. You can make it explicit by adding a <grigson-html-renderer> child, which lets you target its CSS custom properties and shadow parts directly.

<grigson-chart normalise>
  <grigson-html-renderer style="
    --grigson-chord-root-color: steelblue;
    --grigson-chord-suffix-color: tomato;
  "></grigson-html-renderer>
  <template>
---
title: All The Things You Are
key: Ab major
---
[A]
| Fm7 | Bbm7 | Eb7 | Abmaj7 |
| Dbmaj7 | G7 | Cmaj7 | Cmaj7 |
  </template>
</grigson-chart>

Third-party renderer — <grigson-text-renderer>

Any element implementing the GrigsonRendererElement interface can be used as the renderer. <grigson-text-renderer> is a separate package that renders charts as plain text inside a <pre> element.

<!-- Load the separate package -->
<script defer src="/js/grigson-text-renderer-register.iife.js"></script>

<grigson-chart normalise>
  <grigson-text-renderer></grigson-text-renderer>
  <template>
---
title: Autumn Leaves
key: G minor
---
[A]
| Am7b5 | D7 | Gm | Gm |
  </template>
</grigson-chart>

Attributes reference

Changing any of these attributes via the DOM will automatically re-render the chart.

CSS API

CSS custom properties and shadow parts belong to the renderer element (<grigson-html-renderer> or a custom renderer), not to <grigson-chart> itself.

Custom properties

Shadow parts

grigson-chart::part(chord-root) {
  color: #d33;
  font-weight: bold;
}

grigson-chart {
  --grigson-font-family: 'Fira Code', monospace;
}

Responsive layout

<grigson-chart> sets container-type: inline-size on itself by default. There are two complementary tools for adapting to narrow containers:

• Auto-size font — add auto-size to <grigson-html-renderer> and the element will binary-search for the largest font size that fits all chord cells without clipping. Re-runs on every re-render and on container width changes. See HTML renderer — auto-size.
• Reflow bars — use @container queries with multiple renderers to switch between different bars-per-line values at different widths (shown below).

The two approaches compose: auto-size handles font fitting within a given bar layout, and container queries handle switching between bar layouts.

Here two HTML renderers are used — 4 bars per line on wide layouts and 2 bars per line on narrow ones:

<grigson-chart normalise>
  <style>
    .chart-4bar { display: none;  }
    .chart-2bar { display: block; }

    @container (min-width: 500px) {
      .chart-4bar { display: block; }
      .chart-2bar { display: none;  }
    }
  </style>
  <grigson-html-renderer class="chart-4bar" bars-per-line="4"></grigson-html-renderer>
  <grigson-html-renderer class="chart-2bar" bars-per-line="2"></grigson-html-renderer>
  <template>...</template>
</grigson-chart>

Resize the browser window to see it switch between layouts. Opt out of containment with container-type: normal on the element if needed.

Building a custom renderer element

Any element that implements renderChart(song) can be used as a renderer child. See the Renderer Interface for details.