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.

RenderOptions is the options object accepted by the render() and renderAll() library functions. Every field is optional — omit any field you want to inherit from the composition’s config export instead. Options passed here take the highest precedence in the merge chain, overriding both the base CompositionConfig and any matched VariantConfig. 
import type { RenderOptions } from 'grafex'

​
Interface

interface RenderOptions {
  props?: Record<string, unknown>;
  width?: number;
  height?: number;
  scale?: number;
  format?: 'png' | 'jpeg';
  quality?: number;
  browser?: 'webkit' | 'chromium';
  variant?: string;
}

​
Fields

​
props
Record<string, unknown>
Props to pass to the composition’s default-export component. These are shallow-merged with any props defined in the matching VariantConfig — RenderOptions props override variant props for any overlapping keys. Keys present only in the variant props are preserved.
const result = await render('./card.tsx', {
  props: { title: 'Hello World', author: 'Alice' },
});
​
width
number
Override the composition viewport width in logical pixels. Supersedes width defined in CompositionConfig or the matched VariantConfig. The physical output width equals width × scale.
​
height
number
Override the composition viewport height in logical pixels. Supersedes height defined in CompositionConfig or the matched VariantConfig. The physical output height equals height × scale.
​
scale
number
default:"1"
Device pixel ratio to apply to the viewport. A value of 2 produces high-DPI (retina) output: the layout still sees the logical width × height viewport, but the exported image contains width × scale by height × scale physical pixels.
Use scale: 2 when your composition will be displayed on retina screens — for example, in social media previews or email headers where high-DPI devices are common.
​
format
'png' | 'jpeg'
default:"'png'"
Output image format. 'png' is lossless and supports transparency. 'jpeg' is lossy but produces smaller files — useful for photographs or gradient-heavy backgrounds where pixel-perfect fidelity is not required.
​
quality
number
default:"90"
JPEG compression quality from 1 (lowest quality, smallest file) to 100 (highest quality, largest file). Only applied when format is 'jpeg'. This field has no effect on PNG output.
Setting quality without also setting format: 'jpeg' has no effect. The default format is 'png', which ignores this option.
​
browser
'webkit' | 'chromium'
default:"'webkit'"
Browser engine used for rendering. WebKit is installed automatically when you npm install grafex and is the default. Chromium is an alternative if you encounter CSS compatibility issues — it must be installed separately before use.
npx playwright install chromium

const result = await render('./card.tsx', { browser: 'chromium' });
Chromium is not installed by default. Calling render() with browser: 'chromium' without first running npx playwright install chromium will throw an error.
​
variant
string
Name of a single variant to render from the composition’s config.variants map. When provided, Grafex merges the named VariantConfig with the base CompositionConfig before applying the remaining RenderOptions. When omitted, the base config is used directly without any variant merge.
// Render only the 'twitter' variant
const result = await render('./card.tsx', { variant: 'twitter' });
The variant field is not available on renderAll(). That function renders every variant defined in config.variants and accepts Omit<RenderOptions, 'variant'> — the variant key is excluded from its options type.

​
Usage examples

​
Basic render with props

import { render, close } from 'grafex';
import { writeFileSync } from 'node:fs';

const result = await render('./card.tsx', {
  props: { title: 'My Post', author: 'Alice' },
  format: 'png',
  scale: 2,
});

writeFileSync('card.png', result.buffer);
await close();

​
Override dimensions at call time

const result = await render('./card.tsx', {
  width: 800,
  height: 400,
  format: 'jpeg',
  quality: 85,
});

​
Render a specific variant

const result = await render('./card.tsx', {
  variant: 'square',
  props: { theme: 'dark' },
});

​
Render all variants (no variant field)

import { renderAll, close } from 'grafex';
import { writeFileSync } from 'node:fs';

// RenderOptions without 'variant' — applies to every variant
const all = await renderAll('./card.tsx', {
  scale: 2,
  format: 'png',
});

for (const [name, result] of all) {
  writeFileSync(`${name}.${result.format}`, result.buffer);
}

await close();

Build docs developers (and LLMs) love

Get started for freeTalk to us