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

# Text overlays

> Render dynamic text, OG card titles, badges, shadows, strokes, and custom fonts directly on CDN URLs.

Add `text=…` to composite typography on the resized image — ideal for Open Graph cards, social previews, and dynamic badges.

<Frame caption="Text badge — `?text=Hello+world&textSize=64&textBg=%23000000aa`.">
  <img src="https://cdn.convertly.sh/cvly/o/convertly-site/docs/cdn-transforms/examples/text-overlay.webp?v=docs-20260717&format=auto&q=auto:eco" alt="Image with a text overlay badge" className="w-full rounded-xl" />
</Frame>

<Frame caption="Editorial multiline — `?text=Summer+Sale%0A50%25+Off&textFont=serif&textLetterSpacing=6`.">
  <img src="https://cdn.convertly.sh/cvly/o/convertly-site/docs/cdn-transforms/examples/text-advanced.webp?v=docs-20260717&format=auto&q=auto:eco" alt="Premium multiline text overlay with soft shadow" className="w-full rounded-xl" />
</Frame>

## Core parameters

| Param          | Value                                                                                                                                                                                                                           | Default         |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
| `text`         | URL-encoded text (max 500 chars). Use `%0A` for line breaks.                                                                                                                                                                    | —               |
| `textColor`    | Hex color (`#fff`, `#ffffff`, or with alpha `#ffffff80`).                                                                                                                                                                       | `#ffffff`       |
| `textSize`     | Font size in pixels (8–256).                                                                                                                                                                                                    | `48`            |
| `textPosition` | `top-left`, `top-center`, `top-right`, `center`, `bottom-left`, `bottom-center`, `bottom-right`.                                                                                                                                | `bottom-center` |
| `textFont`     | `sans`, `serif`, `mono`, or aliases like `arial`, `georgia`, `courier`.                                                                                                                                                         | `sans`          |
| `textAlign`    | Horizontal alignment for multiline text: `left`, `center`, `right`. Applies when `textPosition` is a horizontal center anchor (`top-center`, `center`, `bottom-center`). Corner positions anchor the text block to that corner. | `center`        |
| `textShadow`   | Drop shadow as `dx,dy,blur,#color` (e.g. `2,2,4,#000000aa`).                                                                                                                                                                    | none            |
| `textBg`       | Optional hex background pill behind text.                                                                                                                                                                                       | none            |

```
?w=1200&h=630&text=Hello%0Aworld&textSize=64&textColor=%23ffffff&textPosition=bottom-left&textAlign=left&textShadow=2,2,4,%2300000080&textBg=%23000000aa
```

## Advanced typography

| Param                            | Value                                                                  |
| -------------------------------- | ---------------------------------------------------------------------- |
| `textFontUrl`                    | Public HTTPS URL to a WOFF/WOFF2/TTF/OTF file embedded at render time. |
| `textWidth`                      | Max text block width in pixels (enables wrapping).                     |
| `textStroke` / `textStrokeColor` | Outline width and hex colour.                                          |
| `textLetterSpacing`              | Letter spacing in SVG units (`-20` to `80`).                           |

## OG image pattern

Vary only the title per page while a [preset](/docs/image-cdn/presets-and-signing#named-presets) locks canvas size, font, and colours:

```html theme={"system"}
<meta property="og:image" content="https://cdn.convertly.sh/assets-acme/{fileIdOrSlug}?preset=og-card&text=My+latest+post" />
```

For image watermarks (second raster layer), see [Watermarks](/docs/image-cdn/transforms/watermarks).