Chord diagrams and chord names

Chord information lives at two levels in a score — the diagram that shows the fingering and the inline chord name over a beat. alphaTab renders both, and the source file decides which appear where.

Chord names on beats

Any beat can carry a chord name — the shorthand Cmaj7 or G/B that sits above the staff on a lead sheet. alphaTab renders the name in the chord font directly above the beat, respecting sharp, flat, and slash-bass characters.

Chord diagrams above the first system

When a chord definition ships with a fretboard diagram — the six-string grid used in songbooks to show fingering — alphaTab draws it above the first system by default. The embed under the previous heading already shows the top-of-score layout. The same score can render each diagram inline above the bar that first references it instead, driven by two boolean fields on score.stylesheet; see the Chord diagrams on top stylesheet page for a live toggle between the two layouts.

Show it in code

Toggle whether diagrams collect above the first system or attach to each beat individually. The knobs live on the stylesheet, so apply them in a scoreLoaded handler:

import * as alphaTab from '@coderline/alphatab';

const container = getAlphaTabContainer();
const api = new alphaTab.AlphaTabApi(container, {
  core: { file: '/scores/song.gp' },
});

api.scoreLoaded.on((score) => {
  // Collect diagrams above the first system (the default):
  score.stylesheet.globalDisplayChordDiagramsOnTop = true;

  // Also render each diagram inline above the bar that first uses it:
  score.stylesheet.globalDisplayChordDiagramsInScore = true;

  api.render();
});

See Chord diagrams on top for the interactive demo that walks these two flags together.

To hide chord names or diagrams entirely, disable them through notation.elements:

api.settings.notation.elements.set(
  alphaTab.NotationElement.EffectChordNames,
  false,
);
api.settings.notation.elements.set(
  alphaTab.NotationElement.ChordDiagrams,
  false,
);
api.updateSettings();
api.render();

getAlphaTabContainer() is a placeholder for the platform-specific render target — a <div> on Web, an AlphaTab control on .NET, or an AlphaTabView on Android.

Where to look next

• Chord diagrams on top — the stylesheet policy that governs the diagrams-above-first-system layout, with a live toggle.
• Toggling notation elements off — hide chord names or diagrams score-wide.
• globalDisplayChordDiagramsOnTop and globalDisplayChordDiagramsInScore on the RenderStylesheet reference.
• NotationElement — every element key you can flip.