Bracket extend mode

Instrument brackets (the straight vertical lines that group staves of an ensemble) and grand-staff braces (the curly SMuFL glyph that joins the two hands of a piano) sit at the left edge of every system. bracketExtendMode picks the grouping rule — the same score can render with a bracket per track for the reader who wants to focus on one instrument, or with a single bracket across the two-guitar section when the arrangement should read as one instrument family.

• NoBrackets
• GroupStaves
• GroupSimilarInstruments

The three modes

score.stylesheet.bracketExtendMode takes a BracketExtendMode:

• NoBrackets — no brackets or braces are drawn. Use this for stripped-down handouts, single-track charts, or when brackets fight your custom left-margin layout.
• GroupStaves — draws a bracket per track and a brace across the two staves of a grand-staff track (piano). This is the default and matches Guitar Pro's out-of-the-box look.
• GroupSimilarInstruments — groups tracks that share the same MIDI program under a single bracket. Two distortion guitars end up under one bracket; a grand-staff piano still shows its brace and breaks any surrounding bracket. Grouping is program-based; there is no custom-group API today.

When to prefer each

Pick GroupStaves for the traditional per-track look. Pick GroupSimilarInstruments for ensemble scores where multiple players share an instrument family and the reader benefits from seeing that structure at a glance. Pick NoBrackets for single-track output or when the enclosing UI already communicates track grouping.

Show it in code

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

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

api.scoreLoaded.on((score) => {
  score.stylesheet.bracketExtendMode =
    alphaTab.model.BracketExtendMode.GroupSimilarInstruments;
  api.render();
});

getAlphaTabContainer() is a placeholder for the platform-specific step of obtaining the render target — a <div> on Web, an AlphaTab control on .NET, or an AlphaTabView on Android. Every other line runs unchanged on all three runtimes.

Where to look next

• Track name policies — the label block that sits next to the bracket.
• Multi-bar rests — how the bracket interacts with hidden or collapsed staves.
• System sign separator — the right-edge marker of a system boundary.
• bracketExtendMode and showSingleStaffBrackets on the RenderStylesheet reference.
• BracketExtendMode — the enum reference.
• scoreLoaded and render — the API surface used above.