Skip to Content
Takumi

Render images

Set the size, pixel density, format, and quality of the images takumi image writes.

takumi image renders an HTML file to a PNG, JPEG, WebP, or SVG:

takumi image card.html -o card.png --width 1200 --height 630

Set the size

--width and --height set the viewport in CSS pixels, the size the page lays out in. The width defaults to 1200. Without --height, the image is as tall as the content, which suits a page whose length you do not know ahead of time.

--dpr sets the device pixel ratio. --dpr 2 lays the page out at the same CSS size and writes twice as many pixels in each direction, for high-density screens:

takumi image card.html -o card@2x.png --width 1200 --height 630 --dpr 2

This writes a 2400×1260 image of the same layout. The ratio does not have to be a whole number. --dpr 1.5 writes 1800×945, rounded to whole pixels. An SVG has no pixels to scale, so --dpr is an error with .svg.

Choose the format

The output's extension picks the format:

ExtensionFormat
.pngPNG
.jpg or .jpegJPEG
.webpWebP
.svgSVG

--format overrides the extension, with the values png, jpeg (or jpg), webp, and svg. Writing to standard output has no extension, so it needs --format. See Use takumi in scripts.

Without --format, an output with any other extension stops before rendering, with exit code 2. With --format, takumi writes that format whatever the file is named. Use takumi pdf for a PDF.

Set the quality

--quality takes a number from 0 to 100:

  • JPEG defaults to 75.
  • WebP is lossless unless you pass --quality, which switches it to lossy at that quality.
  • PNG and SVG ignore it.
takumi image photo.html -o photo.webp --quality 80

Render one element

--selector keeps only the first element it matches that draws a box, at its own size, and drops the rest of the page:

takumi image page.html -o pricing.png --selector .pricing-card

The page still lays out at --width, so the element keeps the size it has there. --selector takes a type, #id, and .class written together, such as section.pricing-card or #hero. It reads no combinators or pseudo-classes, so give the element a class or an id to pick it. An inline element with no background or border draws no box of its own, so --selector skips it and can pick a later match. Give it display: inline-block to pick it. It writes PNG, JPEG, or WebP, not SVG.

Keep a transparent background

A page that paints no background renders transparent, so leave html and body without one for a badge or a sticker:

badge.html
<style>
  body {
    margin: 0;
  }

  .pill {
    width: 200px;
    height: 60px;
    border-radius: 30px;
    background: #16a34a;
  }
</style>
<div class="pill"></div>
takumi image badge.html -o badge.png --width 200 --height 60

PNG and WebP keep the transparency. JPEG has none, so give the page a background before you write a JPEG.

Render a dark variant

--color-scheme dark makes @media (prefers-color-scheme: dark) match, so a page that styles its dark colors there renders dark:

takumi image email.html -o email-dark.png --width 600 --color-scheme dark

Without the flag, the page renders light, and prefers-color-scheme: light matches.

light-dark() takes its first color in either scheme. For a dark variant, put the dark colors in a prefers-color-scheme: dark rule instead.

Draw SVG

An inline <svg> element draws as part of the page. An <img> whose src is an .svg file loads like any other image, within the directories the page may read.

Fonts and images in the page

The page loads the fonts and images it references, within the directories you allow. Use your fonts covers fonts, and Control file access covers which files a page can read.

Last updated on