Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/andresilva-cc/grafex/llms.txt

Use this file to discover all available pages before exploring further.

Custom typography is a core part of most image designs. Grafex supports font loading through the fonts field in CompositionConfig, which accepts an array of CSS stylesheet URLs. Each entry is injected as a <link rel="stylesheet"> tag in the HTML <head> before rendering, so Google Fonts URLs and any other CSS-serving endpoint work directly. Once loaded, the fonts are available anywhere in your composition — just reference the family name in your fontFamily style as you would in any web page.

​
Loading fonts via config.fonts

Add a fonts array to your config with one entry per font source. Each entry is passed to the browser as a stylesheet reference, so Google Fonts URLs and other CSS-serving endpoints work directly: 
// card.tsx
import type { CompositionConfig } from 'grafex';

export const config: CompositionConfig = {
  width: 800,
  height: 400,
  fonts: ['https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap'],
};

export default function WithFonts() {
  return (
    <div
      style={{
        width: '800px',
        height: '400px',
        fontFamily: 'Inter, system-ui, sans-serif',
        display: 'flex',
        alignItems: 'center',
        justifyContent: 'center',
      }}
    >
      <h1>Custom Font Composition</h1>
    </div>
  );
}
The font is loaded before the screenshot is taken, so the rendered image uses Inter wherever fontFamily references it. The fallback chain (system-ui, sans-serif) ensures the composition still renders legibly if the font URL is unreachable.

​
Loading multiple fonts

Pass multiple entries to load several families or weights at once: 
export const config: CompositionConfig = {
  width: 1200,
  height: 630,
  fonts: [
    'https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap',
    'https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;600&display=swap',
  ],
};

​
Self-hosted fonts via CSS @font-face

If you prefer to keep font files local — for offline builds, CI environments without internet access, or proprietary typefaces — define them with @font-face in an external CSS file and load that file via config.css instead of config.fonts. fonts.css: 
@font-face {
  font-family: 'MyFont';
  src: url('./fonts/MyFont-Regular.woff2') format('woff2');
  font-weight: 400;
  font-style: normal;
}

@font-face {
  font-family: 'MyFont';
  src: url('./fonts/MyFont-Bold.woff2') format('woff2');
  font-weight: 700;
  font-style: normal;
}
card.tsx: 
import type { CompositionConfig } from 'grafex';

export const config: CompositionConfig = {
  width: 1200,
  height: 630,
  css: ['./fonts.css'],
};

export default function Card() {
  return (
    <div
      style={{
        width: '100%',
        height: '100%',
        fontFamily: 'MyFont, system-ui, sans-serif',
        display: 'flex',
        alignItems: 'center',
        justifyContent: 'center',
      }}
    >
      Self-hosted font
    </div>
  );
}
The url() references inside fonts.css are treated as local asset paths — Grafex embeds the .woff2 files as base64 data URLs automatically, so the font is available even without a file server. See Local Images for details on how local asset embedding works.

​
Fonts in variants

The fonts array in a variant replaces the base config’s fonts array entirely — there is no merging. If a variant needs a different or additional font, list all required sources in that variant’s fonts field: 
export const config: CompositionConfig = {
  width: 1200,
  height: 630,
  fonts: ['https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap'],
  variants: {
    default: {},
    mono: {
      fonts: ['https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;600&display=swap'],
    },
  },
};
The default variant uses Inter. The mono variant uses only JetBrains Mono — the base Inter URL is not included unless you add it explicitly to the mono variant’s array.
For compositions that run in CI without internet access, self-hosted fonts via @font-face in a config.css file are the most reliable approach. Local font files are embedded at export time, so no network request is needed during rendering.

Build docs developers (and LLMs) love

Get started for freeTalk to us