> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ogify.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# TemplateRenderer

The main class for managing templates and rendering images. Typically created via `createRenderer()`, but can be instantiated directly if needed.

<Note>
  For complete type definitions and interfaces, see the [Type
  Definitions](/api-reference/core/type-definitions) page.
</Note>

## Methods

### getTemplate

Retrieves a template by its unique ID.

```typescript theme={null}
getTemplate(id: string): OgTemplate | undefined
```

#### Parameters

<ParamField path="id" type="string" required>
  The template ID to look up
</ParamField>

#### Returns

<ResponseField name="template" type="OgTemplate | undefined">
  The template definition, or `undefined` if not found
</ResponseField>

***

### renderToImage

Renders a template to a PNG image buffer. This is the main method for generating OG images.

```typescript theme={null}
renderToImage<K extends keyof TMap>(
  templateId: K,
  params: TMap[K] | (() => Promise<TMap[K]>),
  options?: OgTemplateOptions
): Promise<Buffer>
```

#### Parameters

<ParamField path="templateId" type="string" required>
  The ID of the template to render
</ParamField>

<ParamField path="params" type="object | function" required>
  Parameters specific to the chosen template, or a function returning a Promise
  of parameters. User-provided parameters override shared parameters.
</ParamField>

<ParamField path="options" type="OgTemplateOptions">
  Rendering options

  <Expandable title="properties">
    <ParamField path="width" type="number" default={1200}>
      Width of the image in pixels. Templates always receive the original
      `width`/`height` — `scale` is applied during rasterisation.
    </ParamField>

    <ParamField path="height" type="number" default={630}>
      Height of the image in pixels
    </ParamField>

    <ParamField path="isRTL" type="boolean" default={false}>
      Whether to enable Right-to-Left support
    </ParamField>

    <ParamField path="fonts" type="OgFontConfig[]">
      Custom fonts override
    </ParamField>

    <ParamField path="scale" type="number" default={1}>
      Supersampling scale factor for higher-quality PNG output. Satori renders the
      SVG at the original `width × height`; Resvg rasterises it at
      `width × scale` pixels wide. Clamped to `[1, 4]`. Float values are
      supported (`1.5`, `2`, etc.). **Do not use for layout** — see
      [Scale & Supersampling](/api-reference/core/scale-supersampling).
    </ParamField>
  </Expandable>
</ParamField>

#### Returns

<ResponseField name="buffer" type="Promise<Buffer>">
  A promise that resolves to the PNG image buffer
</ResponseField>

#### Rendering process

<Steps>
  <Step title="Template Lookup">
    Looks up the template by ID in the internal registry
  </Step>

  <Step title="Parameter Merging">
    Merges shared params with user params

    **Priority:** Parameters are merged with the following precedence
    (highest to lowest):

    1. `params` passed to `renderToImage()`
    2. `sharedParams` from renderer configuration
    3. Template default parameters
  </Step>

  <Step title="Cache Checking">
    Generates a cache key and checks for a cached PNG buffer
  </Step>

  <Step title="Inflight Deduplication">
    If an identical render is already in progress, returns the shared in-flight
    promise instead of starting a duplicate render
  </Step>

  <Step title="Before Render Hook">
    Calls `beforeRender` hook if configured
  </Step>

  <Step title="Core Rendering">Delegates to the core rendering engine</Step>
  <Step title="Cache Storage">Caches the generated image</Step>
  <Step title="After Render Hook">Calls `afterRender` hook if configured</Step>
  <Step title="Return Buffer">Returns the PNG buffer</Step>
</Steps>

#### Examples

<CodeGroup>
  ```typescript Static Parameters theme={null}
  const buffer = await renderer.renderToImage("basic", {
    title: "Hello World",
    layout: "centered",
  });
  ```

  ```typescript Async Parameters theme={null}
  const buffer = await renderer.renderToImage("basic", async () => {
    const data = await fetchBlogPost();
    return {
      title: data.title,
      subtitle: data.excerpt,
    };
  });
  ```

  ```typescript RTL Support theme={null}
  const buffer = await renderer.renderToImage(
    "basic",
    {
      title: "مرحبا بالعالم",
    },
    {
      isRTL: true,
    }
  );
  ```

  ```typescript Custom Dimensions theme={null}
  const buffer = await renderer.renderToImage(
    "basic",
    {
      title: "Custom Size",
    },
    {
      width: 1600,
      height: 900,
    }
  );
  ```

  ```typescript High-Quality @2x (scale) theme={null}
  // Renders at 1200×630 layout, rasterised at 2400×1260 PNG
  const buffer = await renderer.renderToImage(
    "basic",
    {
      title: "Sharp Retina Image",
    },
    {
      scale: 2, // @2x — recommended for retina displays
    }
  );

  // Fine-grained float values also work
  const buffer2 = await renderer.renderToImage(
    "basic",
    { title: "Quality Boost" },
    { scale: 1.5 }
  );
  ```
</CodeGroup>

## Usage Example

```typescript theme={null}
import { createRenderer } from "@ogify/core";
import basicTemplate from "@ogify/templates/basic";
import type { TemplateParams } from "@ogify/templates/basic";

const renderer = createRenderer<{ basic: TemplateParams }>({
  templates: { basic: basicTemplate },
});

// Get template info
const template = renderer.getTemplate("basic");
console.log(template?.fonts);

// Render image
const buffer = await renderer.renderToImage("basic", {
  title: "My Page",
  subtitle: "A great description",
  layout: "centered",
});

// Save or return the buffer
await writeFile("og-image.png", buffer);
```