Component Reference

This page documents the options accepted and values returned from the <Score> component and getScore() function.

<Score>

import { Score } from "astro-lilypond";

interface ScoreProps {
  content: LilypondScore;
  format?: "svg" | "png";
  crop?: boolean;
  pageLimit?: number;
  class?: string;
  style?: string;
  alt?: string;
}

MyComponent.astro

---
import { Score } from "astro-lilypond";
import bachInvention from "./bach-invention.ly";
---

<Score content={bachInvention} />

content

Type: LilypondScore

The score’s source text and derived metadata. You get one from:

• Importing a .ly/.ily/.lilypond file directly.
• A lilypondLoader() content-collection entry; entry.data is a LilypondScore.

format

Type: "svg" | "png"
Default: the integration’s defaults.format ("svg" unless configured otherwise)

Output format for the rendered image.

crop

Type: boolean
Default: false

Crops the score to a single tightly-fit image instead of full pages — see cropping.

pageLimit

Type: number

Render only the first n pages. If omitted, all pages render. See limiting rendered pages.

class

Type: string

Class name(s) applied to the rendered <img> (or <ol>, for multi-page scores). See the styling guide.

style

Type: string

Inline styles applied directly to the rendered element.

alt

Type: string

Overrides the automatically-derived alt text. Takes precedence over any title/composer found in the .ly file’s \header block. See also: alt text.

getScore()

import { getScore } from "astro-lilypond";

function getScore(
  score: LilypondScore,
  options?: GetScoreOptions,
): Promise<GetScoreResult>;

score

Type: LilypondScore

Same as <Score />’s content above.

options

Type: GetScoreOptions

options.format

Type: "svg" | "png"
Default: the integration’s defaults.format ("svg" unless configured otherwise)

Output format for Score.

options.crop

Type: boolean
Default: false

Crops Score to a single tightly-fit image instead of returning full pages. See the component guide.

options.pdf

Type: boolean
Default: false

When true, also renders a downloadable PDF of the same score, returned as pdf.

ScoreWithPdf.astro

---
import { getScore } from "astro-lilypond";
import bachInvention from "./bach-invention.ly";

const { Score, pdf, meta } = await getScore(
  bachInvention,
  { crop: true, pdf: true }
);
---

<h3>{meta.title}</h3>
<Score />
<a href={pdf.src} download>Download PDF</a>

Return value

Type: GetScoreResult

interface GetScoreResult {
  Score: AstroComponentFactory;
  pages: LilypondPage[];
  meta: LilypondMetadata;
  raw: string;
  pdf?: LilypondPdfResult;
}

Score

Type: AstroComponentFactory

Accepts all the same props as <Score>, except for format and crop; pass those to the options argument of getScore().

pages

Type: LilypondPage[]

interface LilypondPage {
  src: string;
  width?: number;
  height?: number;
}

Every rendered page’s src/width/height, exposed so you can compose your own markup instead of using the markup from Score.

meta

Type: LilypondMetadata

Fields parsed from the score’s \header block(s) — see the LilypondMetadata type below.

raw

Type: string

Your LilyPond source code as a string, exactly as passed to getScore() (including any \version prepended via defaults.version). Use it wherever you need to show the text itself, rather than the rendered image.

pdf

Type: LilypondPdfResult | undefined

interface LilypondPdfResult {
  src: string;
}

Present only when options.pdf is true.

LilypondMetadata type

Fields parsed from the score’s \header block(s) — the shape of meta on getScore() results.

interface LilypondMetadata {
  arranger?: string;
  composer?: string;
  copyright?: string;
  dedication?: string;
  instrument?: string;
  meter?: string;
  opus?: string;
  piece?: string;
  poet?: string;
  subsubtitle?: string;
  subtitle?: string;
  tagline?: string;
  title?: string;

  // Any other unknown or uncommon fields
  [field: string]: string | undefined;
}