# HTML to image: six templates you can copy

> Six copyable HTML and CSS templates: social card, certificate, receipt, quote card, ticket and stat card, with sizes and the rules that make them render right.

Cookbook by Serghei Pogor, founder of CurlShot (https://curlshot.com/about/serghei-pogor). Published 25 October 2026. Page for people: https://curlshot.com/blog/html-to-image-templates

To generate an image from HTML and CSS, write the design as a small web page with a fixed canvas (set width and height in pixels on body and zero its margin), then render it in a headless browser with a viewport of exactly that size. The image is viewport x device scale factor: a 1200 x 630 social card at scale 2 is 2400 x 1260 pixels. This page has six complete templates to start from, each under 60 lines, and CurlShot renders any of them from one POST request with the HTML in the html field.

## Key facts

- Six self-contained templates: a 1200 x 630 social card, a 1123 x 794 certificate (landscape A4 at 96 px per inch), a 420 x 540 receipt, a 1080 x 1080 quote card, a 1000 x 400 ticket and an 800 x 600 stat card.
- Image size is viewport x device scale factor. Request the canvas size as the viewport, then use scale 2 for anything with small text: 800 x 600 becomes 1600 x 1200.
- Browsers give body an 8px default margin. A template that does not set margin to 0 is shifted 8px right and down, and loses 8px on the right and at the bottom.
- Fonts fall back one character at a time, so a server without your font, a CJK font or an emoji font draws something else or an empty box.
- Escape the five characters & < > " and ' in every value you put into a template.
- The canvas fillText call does not wrap text. A browser does, which is the main reason to make text-heavy images from HTML.

## Six HTML templates you can render to an image

Each template below is a complete, self-contained HTML document: one `<style>` block, no scripts, no images and no web fonts. On the web page every one of them is rendered live next to its code, and two or three fields let you type your own values. Three choices keep them portable:

- **System font stacks only.** Nothing is downloaded, so a render never shows a blank or half-loaded font. The exact letter shapes follow the machine that renders the page.
- **Only `div` and `span` elements.** They carry no default margins, so the template looks the same with or without a CSS reset. An image has no document outline to protect.
- **A fixed canvas on `body`.** Width and height are set in pixels, the margin is zero, and `overflow: hidden` keeps a long value from changing the image size.

To fill a template from code, replace the sample text with your own values and escape `&`, `<`, `>`, `"` and `'` first.

### 1. Open Graph social card (1200 x 630)

The image a chat app or social network shows when someone shares a link to an article. Canvas: 1200 x 630 CSS pixels. The usual size of a link preview image.

Fields to fill in: Title (default "How we cut our build time in half", up to 80 characters); Author (default "Ada Example", up to 40 characters); Site (default "example.com", up to 40 characters).

How it works: A flex column with `justify-content: space-between` pins the site name to the top and the author to the bottom, whatever the length of the title.

```html
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<style>
  * { box-sizing: border-box; }
  body {
    margin: 0; width: 1200px; height: 630px; padding: 64px 80px; overflow: hidden;
    display: flex; flex-direction: column; justify-content: space-between;
    font-family: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
    line-height: 1.2; color: #0f172a; background: #f8fafc; border-left: 20px solid #2563eb;
  }
  .site { font-size: 30px; font-weight: 600; color: #2563eb; }
  .title { font-size: 76px; font-weight: 700; line-height: 1.08; letter-spacing: -0.02em; overflow-wrap: anywhere; }
  .foot { display: flex; align-items: center; gap: 20px; font-size: 30px; color: #475569; }
  .avatar { flex: none; width: 56px; height: 56px; border-radius: 50%; background: #2563eb; }
</style>
</head>
<body>
  <div class="site">example.com</div>
  <div class="title">How we cut our build time in half</div>
  <div class="foot">
    <div class="avatar"></div>
    <div class="author">Ada Example</div>
  </div>
</body>
</html>
```

### 2. Certificate of completion (1123 x 794)

A landscape certificate with a name, a course and a date, for a course platform or an internal training. Canvas: 1123 x 794 CSS pixels. Landscape A4, 297 x 210 mm, at the CSS rate of 96 px to the inch.

Fields to fill in: Name (default "Ada Example", up to 36 characters); Course (default "Practical CSS layout", up to 48 characters); Date (default "25 October 2026", up to 24 characters).

How it works: One `border` plus an `outline` with `outline-offset` draws the double frame without an extra element, and `margin-top: auto` pushes the signature row to the bottom.

```html
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<style>
  * { box-sizing: border-box; }
  body {
    margin: 0; width: 1123px; height: 794px; padding: 40px; overflow: hidden;
    font-family: Georgia, "Times New Roman", Times, serif;
    line-height: 1.3; color: #1f2937; background: #fffdf7;
  }
  .sheet {
    height: 100%; padding: 56px 80px 44px; display: flex; flex-direction: column; align-items: center;
    text-align: center; border: 3px solid #b08d57; outline: 1px solid #b08d57; outline-offset: 10px;
  }
  .heading { font-size: 48px; font-weight: 700; letter-spacing: 0.01em; }
  .line { margin-top: 32px; font-size: 22px; color: #6b7280; }
  .name {
    margin-top: 12px; padding: 0 48px 10px; max-width: 100%; font-size: 68px; font-style: italic; line-height: 1.1;
    overflow-wrap: anywhere; border-bottom: 2px solid #b08d57;
  }
  .course { margin-top: 10px; font-size: 34px; font-weight: 700; overflow-wrap: anywhere; }
  .signs { margin-top: auto; width: 100%; display: flex; justify-content: space-between; align-items: flex-end; }
  .sign { width: 260px; }
  .value { padding-bottom: 8px; font-size: 24px; border-bottom: 1px solid #9ca3af; }
  .label { margin-top: 8px; font-size: 18px; color: #6b7280; }
  .seal { width: 92px; height: 92px; border-radius: 50%; border: 8px double #b08d57; }
</style>
</head>
<body>
  <div class="sheet">
    <div class="heading">Certificate of completion</div>
    <div class="line">This certifies that</div>
    <div class="name">Ada Example</div>
    <div class="line">has successfully completed</div>
    <div class="course">Practical CSS layout</div>
    <div class="signs">
      <div class="sign">
        <div class="value">25 October 2026</div>
        <div class="label">Date</div>
      </div>
      <div class="seal"></div>
      <div class="sign">
        <div class="value">Grace Sample</div>
        <div class="label">Instructor</div>
      </div>
    </div>
  </div>
</body>
</html>
```

### 3. Receipt (420 x 540)

A narrow payment receipt in the shape of a till roll, to attach to an email or show in an app. Canvas: 420 x 540 CSS pixels. A narrow column, like a till roll. Change the height to fit your rows.

Fields to fill in: Business (default "Corner Coffee", up to 28 characters); Item (default "Bag of espresso beans", up to 40 characters); Amount (default "18.50", up to 12 characters).

How it works: Every line is a flex row with `justify-content: space-between`, so the amounts line up on the right without a table.

```html
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<style>
  * { box-sizing: border-box; }
  body {
    margin: 0; width: 420px; height: 540px; padding: 40px 32px; overflow: hidden;
    font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, "Liberation Mono", monospace;
    font-size: 16px; line-height: 1.6; color: #111827; background: #ffffff;
  }
  .shop { font-size: 24px; font-weight: 700; line-height: 1.25; text-align: center; overflow-wrap: anywhere; }
  .center { text-align: center; font-size: 14px; color: #6b7280; }
  .rule { margin: 20px 0; border-top: 2px dashed #d1d5db; }
  .row { display: flex; justify-content: space-between; gap: 16px; }
  .item { min-width: 0; overflow-wrap: anywhere; }
  .amount { flex: none; }
  .muted { color: #6b7280; }
  .total { font-size: 22px; font-weight: 700; }
  .paid {
    margin: 28px auto 0; width: 96px; padding: 4px 0; text-align: center; font-weight: 700; color: #15803d;
    border: 2px solid #15803d; border-radius: 6px; transform: rotate(-4deg);
  }
  .thanks { margin-top: 28px; text-align: center; font-size: 14px; color: #6b7280; }
</style>
</head>
<body>
  <div class="shop">Corner Coffee</div>
  <div class="center">Receipt no. 1042</div>
  <div class="rule"></div>
  <div class="row muted">
    <span>Date</span>
    <span>25 Oct 2026, 09:41</span>
  </div>
  <div class="row muted">
    <span>Paid by</span>
    <span>Card ending 4242</span>
  </div>
  <div class="rule"></div>
  <div class="row">
    <span class="item">Bag of espresso beans</span>
    <span class="amount">18.50</span>
  </div>
  <div class="row muted">
    <span>Tax included</span>
    <span>0.00</span>
  </div>
  <div class="rule"></div>
  <div class="row total">
    <span>Total</span>
    <span class="amount">18.50</span>
  </div>
  <div class="paid">Paid</div>
  <div class="thanks">Thank you. Keep this for your records.</div>
</body>
</html>
```

### 4. Quote card (1080 x 1080)

A square card with one sentence and who said it, for a social feed or a slide. Canvas: 1080 x 1080 CSS pixels. A square, for a feed or a slide.

Fields to fill in: Quote (default "Design the image like a web page, then render it like a screenshot.", up to 140 characters); Name (default "Ada Example", up to 36 characters); Role (default "Engineering lead", up to 44 characters).

How it works: The opening quotation mark is a text character set very large in a serif font, and `margin-top: auto` keeps the attribution on the bottom edge.

```html
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<style>
  * { box-sizing: border-box; }
  body {
    margin: 0; width: 1080px; height: 1080px; padding: 96px; overflow: hidden;
    display: flex; flex-direction: column;
    font-family: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
    line-height: 1.25; color: #0f172a; background: #eef4ff;
  }
  .open { height: 150px; font-family: Georgia, "Times New Roman", serif; font-size: 300px; line-height: 1; color: #2563eb; }
  .quote { margin-top: 28px; font-size: 72px; font-weight: 600; letter-spacing: -0.015em; overflow-wrap: anywhere; }
  .by { margin-top: auto; padding-top: 36px; border-top: 4px solid #2563eb; }
  .author { font-size: 38px; font-weight: 700; }
  .role { margin-top: 6px; font-size: 30px; color: #475569; }
</style>
</head>
<body>
  <div class="open">“</div>
  <div class="quote">Design the image like a web page, then render it like a screenshot.</div>
  <div class="by">
    <div class="author">Ada Example</div>
    <div class="role">Engineering lead</div>
  </div>
</body>
</html>
```

### 5. Event ticket (1000 x 400)

A ticket with a tear-off stub: the event, the date and the seat on the left, an admission strip on the right. Canvas: 1000 x 400 CSS pixels. A 5:2 strip that fits the width of an email or a phone screen.

Fields to fill in: Event (default "Front-end meetup, autumn edition", up to 48 characters); Date (default "Sat 14 Nov 2026", up to 20 characters); Seat (default "Row F, seat 12", up to 18 characters).

How it works: The perforation is a dashed `border-left`, the two notches are `::before` and `::after` circles in the page colour, the facts are a three-column grid with the labels in the first row, and the bars are one `repeating-linear-gradient`. The bars are decoration: they encode nothing and no scanner can read them.

```html
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<style>
  * { box-sizing: border-box; }
  body {
    margin: 0; width: 1000px; height: 400px; padding: 40px; overflow: hidden;
    font-family: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
    line-height: 1.2; color: #0f172a; background: #e8edf5;
  }
  .ticket { height: 100%; display: flex; background: #ffffff; border-radius: 24px; }
  .main { flex: 1; min-width: 0; padding: 36px 40px; display: flex; flex-direction: column; }
  .kind { font-size: 20px; font-weight: 600; color: #6d28d9; }
  .event { margin-top: 8px; font-size: 44px; font-weight: 800; line-height: 1.1; letter-spacing: -0.02em; overflow-wrap: anywhere; }
  .facts { margin-top: auto; display: grid; grid-template-columns: repeat(3, auto); justify-content: start; gap: 4px 48px; }
  .label { font-size: 16px; color: #64748b; }
  .value { font-size: 24px; font-weight: 700; white-space: nowrap; }
  .stub {
    position: relative; flex: none; width: 230px; padding: 32px 28px; display: flex; flex-direction: column;
    justify-content: space-between; align-items: center; border-left: 4px dashed #cbd5e1;
  }
  .stub::before, .stub::after { content: ""; position: absolute; left: -18px; width: 32px; height: 32px; border-radius: 50%; background: #e8edf5; }
  .stub::before { top: -16px; }
  .stub::after { bottom: -16px; }
  .admit { font-size: 22px; font-weight: 700; }
  .bars {
    width: 100%; height: 110px;
    background: repeating-linear-gradient(90deg, #0f172a 0 4px, transparent 4px 7px, #0f172a 7px 9px, transparent 9px 15px, #0f172a 15px 16px, transparent 16px 20px);
  }
  .serial {
    font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, "Liberation Mono", monospace;
    font-size: 16px; letter-spacing: 0.15em; color: #475569;
  }
</style>
</head>
<body>
  <div class="ticket">
    <div class="main">
      <div class="kind">Admission ticket</div>
      <div class="event">Front-end meetup, autumn edition</div>
      <div class="facts">
        <div class="label">Date</div>
        <div class="label">Doors</div>
        <div class="label">Seat</div>
        <div class="value">Sat 14 Nov 2026</div>
        <div class="value">19:00</div>
        <div class="value">Row F, seat 12</div>
      </div>
    </div>
    <div class="stub">
      <div class="admit">Admit one</div>
      <div class="bars"></div>
      <div class="serial">0042 7781</div>
    </div>
  </div>
</body>
</html>
```

### 6. Stat card with a bar chart (800 x 600)

One number, how it changed, and seven bars of history, for a weekly report email or a status channel. Canvas: 800 x 600 CSS pixels. A 4:3 card that sits well in an email column.

Fields to fill in: Metric (default "Weekly signups", up to 32 characters); Value (default "1,284", up to 9 characters); Change (default "+12% on last week", up to 24 characters).

How it works: The chart is a flex row with `align-items: flex-end`. Each bar takes its height from a `--h` custom property set in its `style` attribute, so your code changes seven percentages and nothing else.

```html
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<style>
  * { box-sizing: border-box; }
  body {
    margin: 0; width: 800px; height: 600px; padding: 56px; overflow: hidden;
    display: flex; flex-direction: column;
    font-family: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
    line-height: 1.2; color: #0f172a; background: #ffffff;
  }
  .label { font-size: 26px; font-weight: 600; color: #475569; }
  .figure { margin-top: 8px; display: flex; flex-wrap: wrap; align-items: baseline; gap: 8px 20px; }
  .value { font-size: 104px; font-weight: 800; line-height: 1; letter-spacing: -0.03em; }
  .change { padding: 6px 16px; border-radius: 999px; font-size: 24px; font-weight: 700; color: #166534; background: #dcfce7; }
  .bars { margin-top: auto; height: 210px; display: flex; align-items: flex-end; gap: 18px; border-bottom: 2px solid #e2e8f0; }
  .bar { flex: 1; height: var(--h); border-radius: 8px 8px 0 0; background: #bfdbfe; }
  .bar.now { background: #2563eb; }
  .days { margin-top: 10px; display: flex; gap: 18px; font-size: 18px; color: #64748b; text-align: center; }
  .days span { flex: 1; }
</style>
</head>
<body>
  <div class="label">Weekly signups</div>
  <div class="figure">
    <div class="value">1,284</div>
    <div class="change">+12% on last week</div>
  </div>
  <div class="bars">
    <div class="bar" style="--h: 38%"></div>
    <div class="bar" style="--h: 52%"></div>
    <div class="bar" style="--h: 45%"></div>
    <div class="bar" style="--h: 61%"></div>
    <div class="bar" style="--h: 70%"></div>
    <div class="bar" style="--h: 58%"></div>
    <div class="bar now" style="--h: 100%"></div>
  </div>
  <div class="days">
    <span>Mon</span>
    <span>Tue</span>
    <span>Wed</span>
    <span>Thu</span>
    <span>Fri</span>
    <span>Sat</span>
    <span>Sun</span>
  </div>
</body>
</html>
```

## What size should an HTML image template be?

Design at the canvas size, request a viewport of exactly that size, and multiply by the device scale factor to get the image size. The image is always viewport x scale.

| Template | Canvas (CSS px) | Viewport to request | Device scale factor | Image (viewport x scale) | Format | Why |
| --- | --- | --- | --- | --- | --- | --- |
| Open Graph social card | 1200 x 630 | viewport_width=1200, viewport_height=630 | 1 | 1200 x 1 = 1200, 630 x 1 = 630: 1200 x 630 px | PNG | Platforms resize the card anyway, and a larger file is slower to fetch. Flat colour and text. Switch to JPEG when the card holds a photo. |
| Certificate of completion | 1123 x 794 | viewport_width=1123, viewport_height=794 | 2 | 1123 x 2 = 2246, 794 x 2 = 1588: 2246 x 1588 px | PNG | People zoom in on their own name, and may print it. Sharp text and thin rules. For a printer, a PDF keeps the text as text. |
| Receipt | 420 x 540 | viewport_width=420, viewport_height=540 | 2 | 420 x 2 = 840, 540 x 2 = 1080: 840 x 1080 px | PNG | Small monospace text needs the extra pixels to stay readable. Black text on white, which PNG keeps exact. |
| Quote card | 1080 x 1080 | viewport_width=1080, viewport_height=1080 | 1 | 1080 x 1 = 1080, 1080 x 1 = 1080: 1080 x 1080 px | PNG | The type is large, so one pixel per CSS pixel is already sharp. Large type on one flat colour. |
| Event ticket | 1000 x 400 | viewport_width=1000, viewport_height=400 | 2 | 1000 x 2 = 2000, 400 x 2 = 800: 2000 x 800 px | PNG | Thin dashes and bars blur at one pixel per CSS pixel. Hard edges and thin lines, which JPEG smears. |
| Stat card with a bar chart | 800 x 600 | viewport_width=800, viewport_height=600 | 2 | 800 x 2 = 1600, 600 x 2 = 1200: 1600 x 1200 px | PNG | The day labels and thin baseline need the extra pixels on a dense screen. Solid bars and text. |

Landscape A4 in pixels: 297 mm / 25.4 x 96 = 1123 px and 210 mm / 25.4 x 96 = 794 px, because CSS defines 1 in as 96 px [4]. For the sizes each social platform asks for, see [social preview image sizes](https://curlshot.com/blog/social-preview-image-sizes.md).

## How do you make an HTML template render right?

Eight rules cover almost every template that looks right in your browser and wrong as an image.

1. **Set an explicit canvas size on body.** A template has no window of its own, so give `body` a fixed `width` and `height` in pixels and ask the renderer for a viewport of the same size. The image is then the same wherever it is rendered. Without it, the layout follows whatever window the renderer opens by default. Example: `body { width: 1200px; height: 630px; }`
2. **Zero the margins.** Browsers give `body` a default margin of 8px on every side. Left in place, it shifts a 1200px canvas 8px right and down: everything sits off centre, and the last 8px on the right and at the bottom fall outside the image. [3] Example: `body { margin: 0; }`
3. **Use system fonts, or embed the font.** A font named in `font-family` is used only if it is installed on the machine that renders the page or can be downloaded. Otherwise the browser moves down the list. End every list with a generic family such as `sans-serif`, and either accept the system font or load your own. [1] Example: `font-family: system-ui, -apple-system, "Segoe UI", Roboto, Arial, sans-serif;`
4. **Wait for images and fonts.** The `load` event fires when the page and its dependent resources, including stylesheets and images, have loaded. A screenshot taken earlier has holes where the images go. Web fonts can arrive later still: `document.fonts.ready` resolves when the fonts the page uses have loaded and been laid out. [5][6]
5. **Do not size the canvas in viewport units.** `1vh` is 1% of the height of the viewport, so a layout built on `100vh` changes shape when the requested viewport changes and grows with the page in a full-page capture. Inside a fixed canvas, `px` always means the same thing. [4] Example: `height: 630px;  /* not 100vh */`
6. **Escape every piece of user text.** A name such as `Tom & <b>Jerry</b>` is HTML to a browser. Replace `&`, `<`, `>`, `"` and `'` with their entities before the text goes into the template, or a title can break the layout or run a script in the renderer. Example: `&amp;  &lt;  &gt;  &quot;  &#39;`
7. **Keep text inside a safe area.** Apps crop and round the corners of images they show. The six templates keep every word at least 32px from the edge, and the two wide cards at least 64px, so a crop takes background and not letters. Example: `body { padding: 64px 80px; }`
8. **Test the longest name.** A template that looks right with "Ada Example" has to survive a 36-character name and a word with no spaces. `overflow-wrap: anywhere` lets the browser break an otherwise unbreakable string, and `overflow: hidden` on the canvas keeps a runaway value from changing the size of the image. [7] Example: `.title { overflow-wrap: anywhere; }`

## Why does a rendered image show the wrong font or a missing emoji?

A browser can only draw a font that is installed on the machine it runs on, or that the page downloads. The `font-family` property is a priority list, and selection is done one character at a time: when a font has no glyph for a character, the next fonts in the list are tried [1]. A server usually has far fewer fonts than a laptop, so the same HTML can come out in a different typeface, and a character no installed font covers comes out as an empty box.

Example, with `font-family: "Brand Sans", system-ui, sans-serif` and the text "Zoë 你好" followed by an emoji:

| Character | Kind | Supplied by |
| --- | --- | --- |
| Z | Latin letter | system-ui |
| o | Latin letter | system-ui |
| ë | Accented letter | system-ui |
| 你 | Chinese character | A CJK font |
| 好 | Chinese character | A CJK font |
| 🎉 | Emoji | An emoji font |

Emoji are characters too. They are drawn by a colour emoji font, and every platform ships its own drawings, so an emoji rendered on a Linux server does not look like the same emoji on a phone.

The honest options:

| Option | How | Trade-off |
| --- | --- | --- |
| A system font stack | Name `system-ui` and a few common fonts, then end with a generic family. Nothing is downloaded. | Fastest and never blank, but the letters are whatever each machine calls its interface font, so line breaks can move by a few pixels between your laptop and a Linux server. All six templates take this route. |
| A web font by link | Add a stylesheet or `@font-face` rule with a full `https://` address, and wait for the font before the capture. | Your own typeface everywhere, at the price of one more download per render and a failure mode: if the font is slow, the fallback is what gets captured. |
| A font embedded in the HTML | Put the font file in an `@font-face` rule as a `data:` address. | No network at render time. Base64 text is 4/3 the size of the file, so a 300 KB font adds about 400 KB to every request. |
| A render machine you control | Install the fonts on the machine that runs the browser. | Exact and fast, and you now maintain that machine and its fonts. |

The render machines of CurlShot are Linux servers set up with the Noto families (including Chinese, Japanese and Korean, and colour emoji), Liberation and DejaVu. On them `system-ui` is a Linux font, not the one on your Mac or Windows laptop.

## HTML, canvas or a design tool: which should make the image?

HTML rendered in a browser is the better choice when the image is mostly text of unknown length. Drawing in code wins on speed and pixel work, and a design tool wins when a person should look at every image.

| | HTML rendered in a browser | Canvas or an image library, drawn in code | A template in a design tool |
| --- | --- | --- | --- |
| Text wrapping | Automatic. The browser breaks lines and can break a string that has no spaces. [7] | Yours to write. The canvas `fillText` call draws one string at one point, and its `maxWidth` argument condenses or shrinks the text. Some image libraries add a text box that wraps. [8] | Automatic inside a text box you draw. How the box grows depends on the tool. |
| Fonts and emoji | Any font the machine has or can download, with fallback chosen one character at a time. [1] | Fonts are registered with the library one by one. Fallback and colour emoji depend on the library. | You pick fonts in the tool and the export matches what you saw. |
| Layout | Flexbox and grid place things relative to each other, so a longer title pushes the rest. | Coordinates you compute. A longer title means measuring text and moving everything below it in code. | Placed by hand. Automatic layout exists in some tools and varies between them. |
| Filling in data | String templating in any language, plus escaping. | Variables in the drawing code. | By hand, or through a bulk or API feature if the tool has one. |
| Speed per image | The slowest in machine time: a browser has to load and paint a page. | The fastest: no browser is involved. | Human time when done by hand. |
| The better choice when | The image is mostly text of unknown length, the team already writes CSS, and the images come from data. | The layout is fixed, the volume is very high, or the work is on pixels: photos, filters, compositing. | There are a handful of images, a designer owns them, and each one deserves a look. |

## How to send HTML to the CurlShot API

CurlShot renders HTML in a real browser and returns the image. These are the facts of the request:

- **Parameter:** `html`, a string holding the whole document. `markdown` works the same way.
- **Method:** POST with a JSON body and the header `Content-Type: application/json`. GET takes the same options, but HTML is long and full of characters that are awkward in a URL.
- **Size limit:** 2 MB for `html`. A larger value is refused before any rendering starts.
- **One source:** Exactly one of `url`, `html` or `markdown`. Two together return `invalid_options`.
- **Relative addresses:** They do not load: the HTML arrives as text and has no address of its own. Write full `https://` addresses, put CSS in a `<style>` tag, or use `data:` addresses for small images.
- **External files:** They must be reachable from the public internet. Addresses on `localhost` or a private network are blocked and left out of the image.
- **Canvas:** The viewport is 1280 x 1024 unless you set `viewport_width` (100 to 3840) and `viewport_height` (100 to 4320).
- **Sharpness:** `device_scale_factor` from 1 to 3. The default is 1.
- **Transparent background:** Supported: `omit_background=true` with `format=png` or `format=webp`, and no background on `html` or `body`. With JPEG the request is refused.
- **Formats:** PNG (the default), JPEG, WebP and PDF for a still image or document.

One request that renders recipe 1 at 1200 x 630:

```bash
# card.html is recipe 1. jq puts it into the JSON body.
jq -n --rawfile html card.html \
  '{html: $html, viewport_width: 1200, viewport_height: 630, format: "png"}' \
| curl -X POST "https://curlshot.com/api/v1/screenshot" \
    -H "X-Access-Key: YOUR_ACCESS_KEY" \
    -H "Content-Type: application/json" \
    -d @- \
    --output card.png
```

The result is `card.png`, 1200 x 630 pixels. Add `"device_scale_factor": 2` to the body for 2400 x 1260. More: [HTML to image](https://curlshot.com/tools/html-to-image), [Open Graph image generator](https://curlshot.com/tools/open-graph-image-generator), [HTML and Markdown input](https://curlshot.com/docs/html-and-markdown).

## Glossary

- **Canvas size:** The width and height of the template in CSS pixels, fixed on `body`. It is the size the design is drawn at, before any scaling. (Not the HTML `<canvas>` element.)
- **Device scale factor:** How many physical pixels are used to draw one CSS pixel, along each side. At 2, a 1200 x 630 canvas becomes a 2400 x 1260 image with the same layout. Browsers call the same ratio the device pixel ratio. [2]
- **Safe area:** The part of the canvas, inside a margin, where text and logos are allowed. Whatever an app crops off the edge is then only background.
- **System font stack:** A `font-family` list made of fonts that ship with operating systems, ending in a generic family. It needs no download, and each machine uses the first entry it has. [1]
- **Template:** An HTML document with fixed layout and styling and a few named places where values go.
- **Data binding:** Putting values from a record (a name, a date, an amount) into those places, with the text escaped, to get one finished document per record.

## Questions

### How do I convert HTML and CSS to an image?

Render the HTML in a browser and take a screenshot of it. Fix the canvas on body (for example width 1200px, height 630px, margin 0), open it in a headless browser with a viewport of the same size, and capture the viewport. With CurlShot that is one POST request with the document in the html field and viewport_width and viewport_height set to the canvas size.

### What size should an HTML template for an Open Graph image be?

Use a canvas of 1200 x 630 CSS pixels and render it at device scale factor 1, which gives a 1200 x 630 pixel image. That is the usual size of a link preview image. Keep the text at least 64 pixels from the edges, because apps crop and round the corners.

### Why does my rendered image use a different font than my browser?

The machine that rendered it does not have the font. A browser uses the first font in the font-family list that is installed or can be downloaded, and falls back one character at a time. Use a system font stack that ends in a generic family, link a web font with a full https address and wait for it, or embed the font in the HTML as a data address.

### How do I make an image rendered from HTML sharper?

Raise the device scale factor, not the canvas. At scale 2 every CSS pixel is drawn with 2 x 2 physical pixels, so a 1000 x 400 ticket becomes a 2000 x 800 image with exactly the same layout. Making the canvas bigger changes the layout and makes the text smaller relative to the image.

### Can I render HTML to a PNG with a transparent background?

Yes, if the renderer supports it and the HTML sets no background on html or body. In CurlShot the option is omit_background=true with format png or webp. JPEG cannot store transparency, so that combination is refused.

### Can a CSS barcode on a ticket be scanned?

No. The bars on the ticket template are a repeating CSS gradient: a pattern that looks like a barcode and encodes nothing. A ticket that has to be scanned needs a real barcode or QR code generated from its data by a barcode library, placed in the template as an image or inline SVG.

## Sources

1. MDN Web Docs, "font-family": https://developer.mozilla.org/en-US/docs/Web/CSS/font-family (checked 11 October 2026)
2. MDN Web Docs, "Window: devicePixelRatio property": https://developer.mozilla.org/en-US/docs/Web/API/Window/devicePixelRatio (checked 11 October 2026)
3. WHATWG, "HTML Standard, Rendering: the page": https://html.spec.whatwg.org/multipage/rendering.html#the-page (checked 11 October 2026)
4. MDN Web Docs, "<length>": https://developer.mozilla.org/en-US/docs/Web/CSS/length (checked 11 October 2026)
5. MDN Web Docs, "Window: load event": https://developer.mozilla.org/en-US/docs/Web/API/Window/load_event (checked 11 October 2026)
6. MDN Web Docs, "Document: fonts property": https://developer.mozilla.org/en-US/docs/Web/API/Document/fonts (checked 11 October 2026)
7. MDN Web Docs, "overflow-wrap": https://developer.mozilla.org/en-US/docs/Web/CSS/overflow-wrap (checked 11 October 2026)
8. MDN Web Docs, "CanvasRenderingContext2D: fillText() method": https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/fillText (checked 11 October 2026)

## Go deeper

- [HTML to image](https://curlshot.com/tools/html-to-image)
- [Open Graph image generator](https://curlshot.com/tools/open-graph-image-generator)
- [HTML to PDF](https://curlshot.com/tools/html-to-pdf)
- [HTML and Markdown input](https://curlshot.com/docs/html-and-markdown)

## Read next

- [Social preview image sizes: the OG cheat sheet](https://curlshot.com/blog/social-preview-image-sizes.md): Open Graph image sizes for Facebook, LinkedIn, WhatsApp, iMessage, Discord, Slack and Google Discover, drawn to scale, with the tags and the fixes.
- [PNG, JPEG, WebP or PDF for website screenshots](https://curlshot.com/blog/png-jpeg-webp-pdf-for-screenshots.md): A decision flow, a comparison table and our own file-size measurements for choosing PNG, JPEG, WebP or PDF when you save a screenshot of a web page.
- [Why website screenshots look wrong, and the fixes](https://curlshot.com/blog/why-website-screenshots-look-wrong.md): A field guide to 11 ways a website screenshot goes wrong, from blank lazy images to cookie banners and cut-off pages, with the cause and the fix for each.
