@chordsketch/vue

@chordsketch/vue

Vue 3 components for ChordPro — the plain-text format that writes chords above lyrics ([C]Hello) — powered by ChordSketch's Rust engine compiled to WebAssembly. It ships a chord-sheet preview, a split-pane editor, chord diagrams, a transposition control and a PDF export button, plus the composables behind them, and lives on npm as @chordsketch/vue. It is the Vue counterpart of @chordsketch/react; both render the same output from the same engine.

Installation

npm install @chordsketch/vue vue

vue (3.3 or newer) is a peer dependency. @chordsketch/wasm comes along as a dependency; <PdfExport> additionally needs the heavier export bundle, which is an optional peer — install it only if you export PDFs:

npm install @chordsketch/wasm-export

The package ships one stylesheet — import it once at your app root (see Quick start).

Quick start

<script setup lang="ts">
import { ref } from 'vue';
import { ChordSheet, Transpose, useTranspose } from '@chordsketch/vue';
import '@chordsketch/vue/styles.css';

const source = ref(`{title: Silent Night}
{key: C}

[C]Silent night, [G7]holy [C]night`);

const { value: transpose } = useTranspose();
</script>

<template>
  <Transpose v-model="transpose" />
  <ChordSheet :source="source" :transpose="transpose" />
</template>

<ChordSheet format="html"> renders the engine's chord-over-lyrics markup and injects the engine's own stylesheet, rewritten so every rule applies only inside .chordsketch-sheet__content — the component styles itself, and nothing leaks onto the surrounding page. Override the reading column with your own CSS if you want a different width:

.chordsketch-sheet__content { max-width: none; }

API

Components

<ChordSheet> and <ChordDiagram> inject markup produced by the Rust renderer from a fixed template — no consumer HTML is ever injected.

Composables

Every composable input accepts a plain value, a ref, or a getter, and the work re-runs when a reactive input changes. Unknown chords are not errors: useChordDiagram resolves svg to null and <ChordDiagram> renders its not-found slot.

Options

transpose and config are forwarded to the renderer wherever they appear (<ChordSheet>, <ChordTextarea>, <PdfExport options>, useChordRender, usePdfExport):

Differences from @chordsketch/react

The component and prop names match @chordsketch/react wherever the two frameworks agree. Where they do not:

• Render props become slots. React's loadingFallback / errorFallback / notFoundFallback props are the loading / error / not-found slots here. Pass an empty <template #error /> to suppress an inline fallback, which is what errorFallback={null} does in React.
• Callbacks become events. onChange is update:modelValue (so <ChordTextarea> binds with v-model), onTransposeChange is update:transpose, and <PdfExport>'s onExported / onError are the exported / error events.
• Composables take an options object instead of React's positional hook arguments, and return refs.
• <ChordSheet format="html"> renders the engine's HTML (render_html_body plus the engine stylesheet), where the React package walks the AST into React elements. The output is the same chord-over-lyrics layout; the React-only interaction props built on that walker (in-preview chord selection, drag-to-reposition, chord audio) have no equivalent here.

Links

• Repository: https://github.com/koedame/chordsketch
• Playground: https://chordsketch.koeda.me
• Documentation: https://chordsketch.koeda.me/docs/
• Issues: https://github.com/koedame/chordsketch/issues

License

MIT