# @chordsketch/vue
[](https://www.npmjs.com/package/@chordsketch/vue)
Vue 3 components for [ChordPro](https://www.chordpro.org/) — the plain-text format that writes chords above lyrics (`[C]Hello`) — powered by [ChordSketch](https://github.com/koedame/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`](https://www.npmjs.com/package/@chordsketch/react); both render the same output from the same engine.
## Installation
```bash
npm install @chordsketch/vue vue
```
`vue` (3.3 or newer) is a peer dependency. `@chordsketch/wasm` comes along as a dependency; `` additionally needs the heavier export bundle, which is an **optional** peer — install it only if you export PDFs:
```bash
npm install @chordsketch/wasm-export
```
The package ships one stylesheet — import it once at your app root (see Quick start).
## Quick start
```vue
```
`` 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:
```css
.chordsketch-sheet__content { max-width: none; }
```
## API
### Components
| Component | Props | Events | Slots |
|---|---|---|---|
| `` | `source` (required), `transpose`, `config`, `format` (`html` \| `text`, default `html`) | — | `loading`, `error` (`{ error }`) |
| `` | `modelValue` / `defaultValue`, `transpose`, `config`, `previewFormat`, `readOnly`, `debounceMs` (default `250`), `placeholder`, `textareaAriaLabel`, `transposeMin` / `transposeMax` | `update:modelValue`, `update:transpose` | `loading`, `error` (forwarded to the preview) |
| `` | `chord` (required), `instrument` (default `guitar`), `defines`, `orientation`, `compact` | — | `loading`, `not-found` (`{ chord, instrument }`), `error` (`{ error }`) |
| `` | `modelValue` (required), `min` (default `-6`), `max` (default `+6`), `step`, `label`, `formatValue` | `update:modelValue` | — |
| `` | `source` (required), `filename`, `options`, `disabled` | `exported` (filename), `error` (Error) | default (label), `error` (`{ error }`) |
`` and `` inject markup produced by the Rust renderer from a fixed template — no consumer HTML is ever injected.
### Composables
| Composable | Signature | Returns |
|---|---|---|
| `useChordRender` | `(source, options?) ` | `{ output, loading, error }` — refs; `options` takes `format` / `transpose` / `config` and may be a ref or getter |
| `useChordDiagram` | `(chord, options?)` | `{ svg, loading, error }` — refs; `options` takes `instrument` / `defines` / `orientation` / `compact` |
| `usePdfExport` | `()` | `{ exportPdf(source, filename, options?), loading, error }` |
| `useTranspose` | `(options?)` | `{ value, increment, decrement, reset, setValue }`; `options` takes `initial` / `min` / `max` (default `±11`) |
| `useDebounced` | `(value, delay)` | a ref that follows `value` once `delay` ms have passed without a change |
| `version` | `()` | the installed package version |
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 `` renders its `not-found` slot.
## Options
`transpose` and `config` are forwarded to the renderer wherever they appear (``, ``, ``, `useChordRender`, `usePdfExport`):
| Option | Type | Meaning |
|---|---|---|
| `transpose` | `number` | Semitone offset, reduced modulo 12 by the renderer. Omitted or `0` renders the written chords. |
| `config` | `string` | Configuration preset name (`"guitar"`, `"ukulele"`, …) or an inline [RRJSON](https://www.chordpro.org/chordpro/chordpro-configuration/) configuration string. |
## Differences from `@chordsketch/react`
The component and prop names match [`@chordsketch/react`](https://www.npmjs.com/package/@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 `` to suppress an inline fallback, which is what `errorFallback={null}` does in React.
- **Callbacks become events.** `onChange` is `update:modelValue` (so `` binds with `v-model`), `onTransposeChange` is `update:transpose`, and ``'s `onExported` / `onError` are the `exported` / `error` events.
- **Composables take an options object** instead of React's positional hook arguments, and return refs.
- **`` 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:
- Playground:
- Documentation:
- Issues:
## License
MIT