chord-component
Advanced tools
Lit-based web components for displaying musical chord diagrams and chord lists
Lit-based web components for displaying musical chord diagrams and chord lists across various string instruments.
npm install chord-component
<!DOCTYPE html>
<html>
<head>
<script type="module">
import 'chord-component';
</script>
</head>
<body>
<!-- Single chord diagram -->
<chord-diagram chord="C" instrument="Standard Ukulele"></chord-diagram>
<!-- Chord list -->
<chord-list
instrument="Standard Ukulele"
chords='["C", "F", "G", "Am"]'>
</chord-list>
</body>
</html>
import 'chord-component/chord-diagram';
import 'chord-component/chord-list';
import 'chord-component/chord-editor';
import {
instruments,
chordToNotes,
systemDefaultChords,
chordDataService, // Data management service
indexedDBService // IndexedDB wrapper
} from 'chord-component';
<chord-diagram>Displays a single chord diagram with fretboard visualization.
chord (string, required): The chord name (e.g., "C", "Am7", "F#dim")instrument (string, optional): The instrument type (default: "Standard Ukulele")<!-- Basic usage -->
<chord-diagram chord="C"></chord-diagram>
<!-- Guitar chord -->
<chord-diagram chord="Em" instrument="Standard Guitar"></chord-diagram>
<!-- Complex chord -->
<chord-diagram chord="Cmaj7" instrument="Standard Ukulele"></chord-diagram>
<chord-list>Displays multiple chord diagrams in a responsive grid layout.
instrument (string, optional): The instrument type (default: "Standard Ukulele")chords (string|array, required): JSON string or array of chord names<!-- Array of chords -->
<chord-list
instrument="Standard Ukulele"
chords='["C", "F", "G", "Am"]'>
</chord-list>
<!-- More complex chord progression -->
<chord-list
instrument="Standard Guitar"
chords='["Cmaj7", "Dm7", "G7", "Em7", "Am7"]'>
</chord-list>
<chord-editor> ✨ NEWInteractive editor for creating and customizing chord diagrams.
Create custom chord fingerings with visual and text-based editing. All custom chords are automatically saved to IndexedDB and persist across sessions.
chord (string, required): The chord name to editinstrument (string, optional): The instrument type (default: "Standard Ukulele")chord-saved: Fired when user saves a custom chordchord-reset: Fired when user resets to default<!-- Basic editor -->
<chord-editor chord="C" instrument="Standard Ukulele"></chord-editor>
<!-- Listen for save events -->
<script type="module">
const editor = document.querySelector('chord-editor');
editor.addEventListener('chord-saved', (e) => {
console.log('Saved:', e.detail.chord, e.detail.data);
});
</script>
See CHORD_EDITOR.md for complete documentation.
import { chordDataService } from 'chord-component';
// Programmatically save a custom chord
await chordDataService.saveUserChord('Standard Ukulele', 'C', {
fingers: [[4, 0], [3, 0], [2, 0], [1, 3]],
barres: []
});
// Get all user-defined chords
const userChords = await chordDataService.getAllUserChords();
// Delete a custom chord (revert to default)
await chordDataService.deleteUserChord('Standard Ukulele', 'C');
git clone <repository-url>
cd chord-components
npm install
npm run dev
This starts a development server with the demo page at http://localhost:5173/demo/
npm run build
npm run lint
The easiest way to create custom chords is using the interactive <chord-editor> component:
<chord-editor chord="Csus2" instrument="Standard Ukulele"></chord-editor>
Custom chords are automatically saved to IndexedDB and will be used by all <chord-diagram> components.
See the interactive demo for hands-on examples.
import { chordDataService } from 'chord-component';
// Save a custom chord
await chordDataService.saveUserChord('Standard Ukulele', 'Csus2', {
barres: [],
fingers: [[4, 0], [3, 2], [2, 3], [1, 0]]
});
// Get chord data (user override if exists, otherwise system default)
const chord = await chordDataService.getChord('Standard Ukulele', 'C');
You can also extend the system defaults (not recommended for user preferences):
import { systemDefaultChords } from 'chord-component';
// Add to system defaults
systemDefaultChords["Standard Ukulele"]["Csus2"] = {
barres: [],
fingers: [[4, 0], [3, 2], [2, 3], [1, 0]]
};
The components use CSS custom properties for theming. You can override the default dark theme:
chord-diagram {
--chord-bg-color: #ffffff;
--chord-text-color: #000000;
--chord-border-color: #cccccc;
}
The package exports several utility functions for working with music theory:
import {
instruments, // Array of supported instruments
chordToNotes, // Convert chord name to note array
parseChords, // Parse chords from ChordPro notation
scaleTones, // Get notes in a scale
findBase // Find note index in chromatic scale
} from 'chord-component';
// Example usage
const chordData = chordToNotes("Cmaj7");
console.log(chordData); // { name: "Cmaj7", notes: ["C", "E", "G", "B"] }
The package includes services for managing chord data:
import { chordDataService, indexedDBService } from 'chord-component';
// Chord Data Service
await chordDataService.getChordData('Standard Ukulele');
await chordDataService.saveUserChord(instrument, chord, data);
await chordDataService.getAllUserChords();
await chordDataService.clearCache();
// IndexedDB Service (low-level)
await indexedDBService.saveUserChord(instrument, chord, data);
await indexedDBService.getUserChord(instrument, chord);
See DATA_SERVICE.md for complete API documentation.
Comprehensive guides for advanced features:
Run the demo locally:
npm run dev
Then visit:
http://localhost:5173/demo/ - Chord diagram and list exampleshttp://localhost:5173/demo/editor.html - Interactive chord editorMIT
Contributions are welcome! Please feel free to submit issues and pull requests.
For questions and support, please open an issue on the GitHub repository.
FAQs
Lit-based web components for displaying musical chord diagrams and chord lists
The npm package chord-component receives a total of 0 weekly downloads. As such, chord-component popularity was classified as not popular.
We found that chord-component demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.