Skip to content

Six HTML templates you can render to an image

Each template is a complete HTML document: one <style> block, no scripts, no images, no web fonts. The render on the left is that same HTML, drawn at its true size and scaled to fit. Change a field and both sides follow.

  • System fonts only

    Nothing is downloaded, so a render never catches a font half loaded. The letter shapes follow the machine that renders the page.

  • Only div and span

    They have no default margins, so a 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 in pixels, the margin is zero, and overflow is hidden, so a long value cannot change the size of the image.

  1. Recipe 1: Open Graph social card

    The image a chat app or social network shows when someone shares a link to an article. 1200 x 630 CSS pixels, 27 lines.

    1200 x 630Live render

    Type in a field: the render and the code change together.

    social-card.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>

    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.

  2. Recipe 2: Certificate of completion

    A landscape certificate with a name, a course and a date, for a course platform or an internal training. 1123 x 794 CSS pixels, 50 lines.

    1123 x 794Live render

    Type in a field: the render and the code change together.

    certificate.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>

    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.

  3. Recipe 3: Receipt

    A narrow payment receipt in the shape of a till roll, to attach to an email or show in an app. 420 x 540 CSS pixels, 56 lines.

    420 x 540Live render

    Type in a field: the render and the code change together.

    receipt.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>

    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.

  4. Recipe 4: Quote card

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

    1080 x 1080Live render

    Type in a field: the render and the code change together.

    quote-card.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>

    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.

  5. Recipe 5: Event ticket

    A ticket with a tear-off stub: the event, the date and the seat on the left, an admission strip on the right. 1000 x 400 CSS pixels, 58 lines.

    1000 x 400Live render

    Type in a field: the render and the code change together.

    event-ticket.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>

    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.

  6. Recipe 6: Stat card with a bar chart

    One number, how it changed, and seven bars of history, for a weekly report email or a status channel. 800 x 600 CSS pixels, 49 lines.

    800 x 600Live render

    Type in a field: the render and the code change together.

    stat-card.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>

    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.

Filling a template from code

Replace the sample text with your own values in any language, and escape &, <, >, " and ' first. The fields above do exactly that: type <b> into one and read the code.

What size should an HTML image template be?

An HTML image template is designed at its canvas size, rendered in a viewport of exactly that size, and multiplied by the device scale factor. The image is always viewport x scale, so sharpness is a setting of the render, not of the design.[2]

Canvas, viewport, device scale factor, image size and format for each template
TemplateCanvas, CSS pxScaleImage, viewport x scaleFormat
Open Graph social cardCanvas and viewport to request1200 x 630viewport_width=1200, viewport_height=630Device scale factor1Image, viewport x scale1200 x 630 px1200 x 1 = 1200, 630 x 1 = 630FormatPNGPlatforms 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 completionCanvas and viewport to request1123 x 794viewport_width=1123, viewport_height=794Device scale factor2Image, viewport x scale2246 x 1588 px1123 x 2 = 2246, 794 x 2 = 1588FormatPNGPeople 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.
ReceiptCanvas and viewport to request420 x 540viewport_width=420, viewport_height=540Device scale factor2Image, viewport x scale840 x 1080 px420 x 2 = 840, 540 x 2 = 1080FormatPNGSmall monospace text needs the extra pixels to stay readable. Black text on white, which PNG keeps exact.
Quote cardCanvas and viewport to request1080 x 1080viewport_width=1080, viewport_height=1080Device scale factor1Image, viewport x scale1080 x 1080 px1080 x 1 = 1080, 1080 x 1 = 1080FormatPNGThe type is large, so one pixel per CSS pixel is already sharp. Large type on one flat colour.
Event ticketCanvas and viewport to request1000 x 400viewport_width=1000, viewport_height=400Device scale factor2Image, viewport x scale2000 x 800 px1000 x 2 = 2000, 400 x 2 = 800FormatPNGThin dashes and bars blur at one pixel per CSS pixel. Hard edges and thin lines, which JPEG smears.
Stat card with a bar chartCanvas and viewport to request800 x 600viewport_width=800, viewport_height=600Device scale factor2Image, viewport x scale1600 x 1200 px800 x 2 = 1600, 600 x 2 = 1200FormatPNGThe day labels and thin baseline need the extra pixels on a dense screen. Solid bars and text.

The certificate is landscape A4 in pixels: 297 mm / 25.4 x 96 = 1123 px wide and 210 mm / 25.4 x 96 = 794 px tall, because CSS defines one inch as 96 px.[4] The social card stays at scale 1 on purpose. What each platform asks for, and the file size limits behind that choice, are in social preview image sizes, and the trade between formats is in PNG, JPEG, WebP or PDF.

How do you make an HTML template render right?

Eight rules cover almost every HTML template that looks right in your browser and wrong as an image. All six recipes follow them.

  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.

    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]

    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]

    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]

    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.

    &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.

    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]

    .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 the choice is made 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 another typeface, and a character that no installed font covers comes out as an empty box. That is why a font list should always end in a generic family.[1]

Emoji are characters too. A colour emoji font draws them, 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.

font-family: "Brand Sans", system-ui, sans-serif;

  1. 1"Brand Sans"Not installed on the render machine, so it is skipped.
  2. 2system-uiThe interface font of the machine. It has the Latin letters.
  3. 3sans-serifThe generic family, tried for characters the fonts before it lack.
  • Zsystem-uiLatin letter
  • osystem-uiLatin letter
  • ësystem-uiAccented letter
  • 你A CJK fontChinese character
  • 好A CJK fontChinese character
  • 🎉An emoji fontEmoji
An example of fallback for one line of text on a machine without the first font. The last tile is a real emoji: it is drawn by your own device, so it looks different for the next reader.

The four honest options for fonts in a rendered image

  • 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, which is one more reason to test the longest name.

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 on pixel work, and a design tool wins when a person should look at every image.

Three ways to make an image from data, compared
AspectHTML rendered in a browserCanvas or an image library, drawn in codeA template in a design tool
Text wrappingHTML rendered in a browserAutomatic. The browser breaks lines and can break a string that has no spaces.[7]Canvas or an image library, drawn in codeYours 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]A template in a design toolAutomatic inside a text box you draw. How the box grows depends on the tool.
Fonts and emojiHTML rendered in a browserAny font the machine has or can download, with fallback chosen one character at a time.[1]Canvas or an image library, drawn in codeFonts are registered with the library one by one. Fallback and colour emoji depend on the library.A template in a design toolYou pick fonts in the tool and the export matches what you saw.
LayoutHTML rendered in a browserFlexbox and grid place things relative to each other, so a longer title pushes the rest.Canvas or an image library, drawn in codeCoordinates you compute. A longer title means measuring text and moving everything below it in code.A template in a design toolPlaced by hand. Automatic layout exists in some tools and varies between them.
Filling in dataHTML rendered in a browserString templating in any language, plus escaping.Canvas or an image library, drawn in codeVariables in the drawing code.A template in a design toolBy hand, or through a bulk or API feature if the tool has one.
Speed per imageHTML rendered in a browserThe slowest in machine time: a browser has to load and paint a page.Canvas or an image library, drawn in codeThe fastest: no browser is involved.A template in a design toolHuman time when done by hand.
The better choice whenHTML rendered in a browserThe image is mostly text of unknown length, the team already writes CSS, and the images come from data.Canvas or an image library, drawn in codeThe layout is fixed, the volume is very high, or the work is on pixels: photos, filters, compositing.A template in a design toolThere 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, so any of the six templates becomes a file with one request. These are the facts of that request, as the API is built today.

Render recipe 1 at 1200 x 630
# 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 and the same card comes back at 2400 x 1260. The same request with another recipe and its size from the table renders the other five.

What the HTML input accepts

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.

Glossary of HTML to image terms

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 people ask

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. [1]MDN Web Docs, font-family. Checked .
  2. [2]MDN Web Docs, Window: devicePixelRatio property. Checked .
  3. [3]WHATWG, HTML Standard, Rendering: the page. Checked .
  4. [4]MDN Web Docs, <length>. Checked .
  5. [5]MDN Web Docs, Window: load event. Checked .
  6. [6]MDN Web Docs, Document: fonts property. Checked .
  7. [7]MDN Web Docs, overflow-wrap. Checked .
  8. [8]MDN Web Docs, CanvasRenderingContext2D: fillText() method. Checked .

Screenshot any page in one step

Paste an address into CurlShot and download the screenshot. A free account gives you 100 screenshots every month. No card needed.