Skip to main content

Fonts

ChamevoJS uses the CSS Font Loading API to load fonts for canvas text rendering.

Configuration​

Define available fonts in options:

const options = {
    fonts: [
        // System font (already available)
        { name: 'Arial' },

        // Google Fonts
        { name: 'Roboto', url: 'google' },
        { name: 'Lobster', url: 'google' },
        { name: 'Playfair Display', url: 'google' },

        // Custom font files
        {
            name: 'My Custom Font',
            url: '/fonts/my-custom-font.woff2',
        },
    ],
};

Font Definition​

interface FontDefinition {
    /** Display name (also used as font-family value) */
    name: string;
    /** URL to font file, or 'google' for Google Fonts. Omit for system fonts. */
    url?: string;
    /**
     * Font variant files or availability flags.
     * Keys use CSS font-face shorthand:
     * - 'n7' — normal 700 (bold)
     * - 'i4' — italic 400
     * - 'i7' — italic 700 (bold italic)
     * Values are URLs to the font files (string) or boolean availability flags (for Google Fonts).
     */
    variants?: Record<string, string | boolean>;
}

Google Fonts​

Set url: 'google' to load from Google Fonts CDN. Google Fonts automatically include all four variants (regular, bold, italic, bold italic), so no variants mapping is needed.

{ name: 'Roboto', url: 'google' }

Custom Fonts​

Point to a WOFF2 (preferred), WOFF, TTF, or OTF file. If the customizer is served from a different origin than the font, use the proxyFileServer option to handle CORS.

Simple (single weight)​

For a custom font with only one weight, provide the file URL directly:

{
    name: 'My Custom Font',
    url: '/fonts/my-custom-font.woff2',
}

This registers the font as normal weight (400). Bold and italic text will be synthetically approximated by the browser, which often produces poor results.

To get proper bold, italic, and bold italic rendering, provide a variants object mapping variant keys to their font files:

{
    name: 'Josefin Sans',
    url: '/fonts/JosefinSans-Regular.ttf',
    variants: {
        n7: '/fonts/JosefinSans-Bold.ttf',
        i4: '/fonts/JosefinSans-Italic.ttf',
        i7: '/fonts/JosefinSans-BoldItalic.ttf',
    },
}

The variant keys follow CSS font-face shorthand:

KeyStyleWeightDescription
n7normal700Bold
i4italic400Italic
i7italic700Bold Italic
Variants are required for PDF export

When exporting to PDF, the PDF generator embeds font files directly. Without explicit variant files, bold and italic text will render as regular weight in the exported PDF — the browser's synthetic bold/italic is not available in the PDF context.

Always provide variants for custom fonts if your users will use bold or italic text formatting and you need accurate PDF output.

Loading Fonts Programmatically​

Use FontService directly:

// Via ChamevoJS
await chamevo.fontService.loadFont('Roboto', 'google');
await chamevo.fontService.loadFont('Custom', '/fonts/custom.woff2');

Checking Variant Availability​

Use getFontVariants() to check which variants are available for a font:

const variants = chamevo.fontService.getFontVariants('Josefin Sans', fonts);
// { bold: true, italic: true, boldItalic: true }

This is useful for conditionally enabling/disabling bold and italic buttons in the UI based on whether the font actually has those variants. For Google Fonts, variant availability is automatically detected from boolean flags. For custom fonts, availability is determined by the presence of variant files in the variants object.

Next Steps​