Introduction

Displaying guitar chord diagrams is a common requirement for music‑learning apps, songbooks, and practice trackers. The flutter_guitar_chord package provides a vector‑based, fully customizable widget that draws standard six‑string chord charts using CustomPainter. Because the diagrams are rendered on the canvas, they scale perfectly on any screen density without the need for external image assets.

When to Choose flutter_guitar_chord

  • You need static chord diagrams that match your app’s theme.
  • You want a lightweight solution that works on all Flutter platforms (iOS, Android, web, desktop).
  • You prefer full control over colors, sizes, and finger‑number labels.

If you require an editable fretboard or a built‑in chord database, consider alternative packages such as chord_diagram or flutter_chord.

Installation

Add the package to your project with the Flutter CLI:

Code
flutter pub add flutter_guitar_chord

After the command completes, run flutter pub get to fetch the dependency.

Basic Usage – A Beginner‑Friendly Example

The following example shows a minimal app that renders a C‑major chord diagram. Copy the code into lib/main.dart and run flutter run:

Dart / Flutter
import 'package:flutter/material.dart';
import 'package:flutter_guitar_chord/flutter_guitar_chord.dart';

class ChordDemo extends StatelessWidget {
  const ChordDemo({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('C Major Chord')),
      body: Center(
        child: FlutterGuitarChord(
          chordName: 'C',
          // Positions are given from low‑E (string 6) to high‑E (string 1)
          positions: [0, 3, 2, 0, 1, 0],
          barre: null, // No barre for C major
          fingerNumbers: [null, 3, 2, null, 1, null],
          size: 200,
          backgroundColor: Colors.white,
          fretColor: Colors.black,
          stringColor: Colors.black,
        ),
      ),
    );
  }
}

void main() => runApp(const MaterialApp(home: ChordDemo()));

Key properties explained:

  • chordName: The label displayed above the diagram.
  • positions: A list of six integers (or null) indicating which fret to press on each string. 0 means an open string, -1 (or null) means the string is muted.
  • barre: Optional BarreInfo object describing a finger that presses multiple strings across a single fret. Omit for chords without a barre.
  • fingerNumbers: Optional overlay showing which finger (1‑5) is used for each pressed string.
  • size: Controls the overall width/height of the diagram (the widget is square).
  • Color properties let you match the diagram to dark or light themes.

Advanced Customization

Because the widget is built on CustomPainter, you can fine‑tune almost every visual aspect. The package exposes the following optional parameters (check the official docs for the latest list):

  • fretCount: Number of frets displayed (default is 5).
  • stringCount: Usually 6, but you can render 4‑string ukulele diagrams.
  • showNut: Whether to draw the nut at the top of the fretboard.
  • nutColor, fretColor, stringColor, dotColor, textStyle: Full control over colors and text appearance.

Tip: When you need a dark‑mode friendly diagram, set backgroundColor to Colors.transparent and provide contrasting fretColor and stringColor values.

Common Mistakes to Avoid

  • Mismatched list lengths: positions and fingerNumbers must contain exactly six elements (or the number defined by stringCount). Providing fewer items will throw a runtime error.
  • Using negative fret numbers: The package expects -1 (or null) to indicate a muted string. Supplying -2 or any other negative value is undefined.
  • Forgetting to import the package: The widget lives in package:flutter_guitar_chord/flutter_guitar_chord.dart. A missing import will cause a compile‑time error.
  • Hard‑coding sizes: While size is convenient, consider wrapping the widget in a LayoutBuilder or using FractionallySizedBox for responsive layouts.

Testing the Widget

Because the widget is pure UI, you can write a widget test that verifies it builds without throwing. Example:

Code
testWidgets('renders C major chord', (WidgetTester tester) async {
  await tester.pumpWidget(const MaterialApp(
    home: Scaffold(
      body: FlutterGuitarChord(
        chordName: 'C',
        positions: [0, 3, 2, 0, 1, 0],
        barre: null,
        fingerNumbers: [null, 3, 2, null, 1, null],
        size: 150,
      ),
    ),
  ));
  expect(find.text('C'), findsOneWidget);
});

Running flutter test should pass, confirming the widget integrates correctly.

Where to Find More Information

For the most up‑to‑date API reference, visit the package page on pub.dev:

If you encounter unexpected behavior, verify the version you are using matches the documentation, as breaking changes may be introduced in newer releases.

Conclusion

The flutter_guitar_chord package offers a clean, vector‑based solution for rendering static guitar chord diagrams. By following the installation steps, using the concise data model, and paying attention to list lengths and color choices, you can add professional‑looking chord charts to any Flutter music app.

Frequently Asked Questions

Do I need any additional assets to use flutter_guitar_chord?

No. The widget draws the diagram entirely with CustomPainter, so you don't need image files or SVG assets.

Can flutter_guitar_chord display barre chords?

Yes. Provide a <code>BarreInfo</code> object via the <code>barre</code> property to indicate the fret and the range of strings the barre covers.

Is the package compatible with Flutter web and desktop?

The package relies only on Flutter's core rendering engine, so it works on iOS, Android, web, macOS, Windows, and Linux.

How can I change the number of frets displayed?

Use the optional <code>fretCount</code> parameter when constructing <code>FlutterGuitarChord</code>. The default is 5 frets.

Where can I find a list of all available customization options?

Refer to the official documentation on pub.dev at https://pub.dev/packages/flutter_guitar_chord for the complete API reference.