Image
Embeds an image asset declared in assets. The image is never stretched: with one size set, the other follows its proportions, and with both set they are a maximum. With width="fill" it is as wide as the room it has.
Asset declaration
Section titled “Asset declaration”Images must be declared in assets before use. The src attribute is the path of the image file, which the SDK reads from the machine that renders the PDF. To supply the bytes yourself, call loadImage on the engine and leave src out (see Installation). The name uses lowercase letters, digits and -.
<lpdf version="1"> <assets> <image name="logo" src="logo.png"/> </assets> <document size="letter"> <section> <layout margin="48pt"> <img name="logo" width="120pt"/> </layout> </section> </document></lpdf>L.document({ size: 'letter', assets: { images: [{ name: 'logo', src: 'logo.png' }] } }, [ L.section(NoAttr, [ L.layout({ margin: '48pt' }, [ L.img({ name: 'logo', width: '120pt' }), ]), ]),])L.document(DocumentAttr(size='letter', assets=DocumentAssets(images=[ImageAttr(name='logo', src='logo.png')])), [ L.section(NoAttr, [ L.layout(LayoutAttr(margin='48pt'), [ L.img(ImgAttr(name='logo', width='120pt')) ]) ])])L.document(new DocumentAttr().size("letter").assets(new DocumentAssets().images(List.of(new ImageAttr().name("logo").src("logo.png")))), List.of( L.section(NoAttr, List.of( L.layout(new LayoutAttr().margin("48pt"), List.of( L.img(new ImgAttr().name("logo").width("120pt")) )) ))))L.Document(new() { Size = "letter", Assets = new DocumentAssets(Images: [new ImageAttr { Name = "logo", Src = "logo.png" }]) }, [ L.Section(NoAttr, [ L.Layout(new() { Margin = "48pt" }, [ L.Img(new() { Name = "logo", Width = "120pt" }), ]), ]),])L::document(new DocumentAttr(size: 'letter', assets: new DocumentAssets(images: [new ImageAttr(name: 'logo', src: 'logo.png')])), [ L::section(NoAttr, [ L::layout(new LayoutAttr(margin: '48pt'), [ L::img(new ImgAttr(name: 'logo', width: '120pt')), ]), ]),])Formats
Section titled “Formats”An image is a JPEG, PNG, WebP, GIF, TIFF, BMP or SVG file. The engine tells the format from the file’s bytes, whatever its name. Transparency is kept: an alpha channel, a GIF’s transparent color, and a PNG’s transparent color or palette entries. An SVG is drawn as vector: see SVG.
A JPEG goes into the PDF as it is. The other raster formats go in as their pixels, compressed without loss, so a photo saved as a lossy WebP takes several times its file’s size in the PDF: save it as a JPEG where the size of the PDF matters. Their pixels count toward the render’s memory limit.
A raster image draws one picture, and the engine reads the kinds of file below. The others are refused with an error that names the image and says how to save it instead:
- JPEG: gray or RGB, written as it is. A JPEG in CMYK is refused: save it in RGB.
- PNG: gray, RGB and RGBA at 8 or 16 bits, and a palette at 8 bits, with the transparent color of a gray or RGB PNG and the transparent entries of a palette. A PNG of gray with alpha, of fewer than 8 bits, or interlaced is refused: save an interlaced one without interlacing.
- TIFF: gray or RGB at 8 or 16 bits a sample, with alpha or without, and gray without alpha at 1, 2 or 4 bits, uncompressed or compressed with LZW, Deflate, PackBits or Group 4 fax. Samples of 32 bits, or of signed or floating-point numbers, a TIFF in CMYK, a TIFF whose pixels are compressed as JPEG, a Group 3 fax, a TIFF with a color palette, a gray TIFF with alpha that stores white as zero, and one that keeps each color in a plane of its own (Photoshop’s “Per Channel” pixel order) are refused. A TIFF of several pages is refused too; a thumbnail stored in it is not a page.
- GIF and WebP: a still image. An animated one is refused.
- BMP: palettes of 1, 4 and 8 bits, run-length encoded or not, and 16, 24 and 32 bits to a pixel, with alpha when the file has an alpha mask. A BMP that holds a JPEG or a PNG is refused: load that file instead.
AVIF, HEIC and JPEG 2000 are refused.
Every format goes in a PDF/A, PDF/UA or PDF/X file. What combines with what has what each kind of file holds, and Color and print what a PDF/X file does with an RGB image.
An SVG is drawn as vector: it stays sharp at any size, the PDF holds its shapes and not pixels, and an SVG used again is written once. The engine reads each SVG when it is loaded and refuses one it can’t draw, when a document uses it, with an error that names the image, the tag and, where it can say, its line.
<lpdf version="1"> <assets> <image name="chart" src="chart.svg"/> </assets> <document size="letter"> <section> <layout margin="48pt"> <img name="chart" width="300pt" alt="Sales by month"/> </layout> </section> </document></lpdf>L.document({ size: 'letter', assets: { images: [{ name: 'chart', src: 'chart.svg' }] } }, [ L.section(NoAttr, [ L.layout({ margin: '48pt' }, [ L.img({ name: 'chart', width: '300pt', alt: 'Sales by month' }), ]), ]),])L.document(DocumentAttr(size='letter', assets=DocumentAssets(images=[ImageAttr(name='chart', src='chart.svg')])), [ L.section(NoAttr, [ L.layout(LayoutAttr(margin='48pt'), [ L.img(ImgAttr(name='chart', width='300pt', alt='Sales by month')) ]) ])])L.document(new DocumentAttr().size("letter").assets(new DocumentAssets().images(List.of(new ImageAttr().name("chart").src("chart.svg")))), List.of( L.section(NoAttr, List.of( L.layout(new LayoutAttr().margin("48pt"), List.of( L.img(new ImgAttr().name("chart").width("300pt").alt("Sales by month")) )) ))))L.Document(new() { Size = "letter", Assets = new DocumentAssets(Images: [new ImageAttr { Name = "chart", Src = "chart.svg" }]) }, [ L.Section(NoAttr, [ L.Layout(new() { Margin = "48pt" }, [ L.Img(new() { Name = "chart", Width = "300pt", Alt = "Sales by month" }), ]), ]),])L::document(new DocumentAttr(size: 'letter', assets: new DocumentAssets(images: [new ImageAttr(name: 'chart', src: 'chart.svg')])), [ L::section(NoAttr, [ L::layout(new LayoutAttr(margin: '48pt'), [ L::img(new ImgAttr(name: 'chart', width: '300pt', alt: 'Sales by month')), ]), ]),])Size. The picture is as large as the width and height of its root svg element, else its viewBox. A size in pt, pc, in, mm or cm is the size it says: a root that says width="72pt" draws 72pt wide, and width="210mm" draws 595.3pt, when the <img> gives no width. A size in pixels, or with no unit, is a pixel to the point, as for any image. When the two are in different units, the width’s unit is read for both, so the picture keeps its proportions; the height’s is read when the width is no length. An SVG with none of the three is as large as what it draws. width and height on the <img> size it as they do any image.
Drawn:
- Shapes:
path,line,polyline,polygon,rect,circleandellipse, and amarkerdrawn at each vertex of its path. - Structure:
svg,g,defs,useof an element of the same file, andclipPath, withtransformon any element. - Painting:
fill,stroke,stroke-width,stroke-linecap,stroke-linejoin,stroke-miterlimit,stroke-dasharray,stroke-dashoffset,fill-rule,opacity,fill-opacityandstroke-opacity, as attributes, in astyleattribute or in a<style>block. Theopacityof a group fades its shapes together. - Colors:
#rgb,#rrggbb,rgb(), a color name,noneandcurrentColor, which is the color of the text where the image sits: thecolorof the nearest box, else thetextcolor of the tokens. The one picture is drawn in each place in that place’s color. Acolorthe SVG sets on its root element is kept.
Left out of the picture, since a still picture shows none of it: title, desc, metadata, comments, script, the tags of drawing programs and animation. An SVG that only appears through its animation is drawn blank.
Refused, with an error that names the tag and, where it can say, its line: text (convert the text to outlines), an image inside the SVG, foreignObject, a gradient, mask, filter, pattern, mix-blend-mode, a clipPath whose shapes have different clip-rule values or whose bounding boxes overlap, a clip-path on a shape of a clipPath, and any reference to another file or a URL: a use of another file, an feImage that names anything but an element of the file, a url() outside the file, an @import, an entity that names a file, and a parameter entity. A gradient, mask, filter or pattern the SVG defines but never uses is no reason to refuse it.
Limits. An SVG that expands to more than 100,000 elements, once its use, marker and clip path references are followed, or has more than 1,000,000 path commands, or nests more than 100 levels, use included, or is written with more than 400,000 XML nodes, text between the tags counted, or has entities that expand to more than 1,000,000 bytes, is refused with an error that names the limit. A use that refers to itself is refused too.
A picture in a PDF/A, PDF/X or PDF/UA file keeps the standard: in PDF/UA it is a figure with the alt of its <img>, which it needs, as any image does.
Attributes
Section titled “Attributes”| Attribute | Type | Default | Description |
|---|---|---|---|
name |
string | — | Required. Asset name declared in assets |
data-name |
string | — | Dot-path: picks the image from the data, among the assets declared in assets. See Attributes from data |
alt |
string | — | What the image shows, which a screen reader reads in a tagged document, with pdfua or a pdfa of level a; alt="" marks it as decoration. A PDF/UA document needs it on each image outside a header or a footer; at level a without pdfua, an image without it is decoration. A document that is not tagged ignores it |
width |
token/length/fill |
— | Width, or fill: as wide as the room the image has. See Fill the slot. Without height, the height follows the image’s proportions |
height |
token/length | — | Height: a length, or a name from the height row of tokens. Without width, the width follows the image’s proportions. With width="fill", a limit |
padding |
spacing | — | Space around the picture, inside the box. See Box around the picture |
background |
color | — | Background of the box around the picture |
border |
string | — | Border, drawn on the edge of the box |
radius |
token/length | — | Corner radius: rounds the box, and clips the picture to rounded corners |
paginate |
string | — | Page breaks: no break-before break-after keep-next. See Page breaks |
ocg |
string | — | print or screen: shown only in print, or only on screen. See Print and screen content |
Fixed width
Section titled “Fixed width”<img name="logo" width="100pt"/>L.img({ name: 'logo', width: '100pt' })L.img(ImgAttr(name='logo', width='100pt'))L.img(new ImgAttr().name("logo").width("100pt"))L.Img(new() { Name = "logo", Width = "100pt" })L::img(new ImgAttr(name: 'logo', width: '100pt'))Fixed height
Section titled “Fixed height”<img name="photo" height="200pt"/>L.img({ name: 'photo', height: '200pt' })L.img(ImgAttr(name='photo', height='200pt'))L.img(new ImgAttr().name("photo").height("200pt"))L.Img(new() { Name = "photo", Height = "200pt" })L::img(new ImgAttr(name: 'photo', height: '200pt'))Both sizes: a maximum
Section titled “Both sizes: a maximum”With both width and height, they are a maximum. The image takes the largest size that fits in them with its own proportions, and its box becomes that size. The parent’s align places it, as for any child.
<img name="logo" width="200pt" height="80pt"/>L.img({ name: 'logo', width: '200pt', height: '80pt' })L.img(ImgAttr(name='logo', width='200pt', height='80pt'))L.img(new ImgAttr().name("logo").width("200pt").height("80pt"))L.Img(new() { Name = "logo", Width = "200pt", Height = "80pt" })L::img(new ImgAttr(name: 'logo', width: '200pt', height: '80pt'))To give images slots of one size, such as a row of logos each in an 80 × 40pt cell, wrap each in a frame of that size, which centres its child:
<row gap="m"> <frame width="80pt" height="40pt"><img name="logo" width="80pt" height="40pt"/></frame> <frame width="80pt" height="40pt"><img name="photo" width="80pt" height="40pt"/></frame></row>L.row({ gap: 'm' }, [ L.frame({ width: '80pt', height: '40pt' }, [ L.img({ name: 'logo', width: '80pt', height: '40pt' }), ]), L.frame({ width: '80pt', height: '40pt' }, [ L.img({ name: 'photo', width: '80pt', height: '40pt' }), ]),])L.row(RowAttr(gap='m'), [ L.frame(FrameAttr(width='80pt', height='40pt'), [ L.img(ImgAttr(name='logo', width='80pt', height='40pt')) ]), L.frame(FrameAttr(width='80pt', height='40pt'), [ L.img(ImgAttr(name='photo', width='80pt', height='40pt')) ])])L.row(new RowAttr().gap("m"), List.of( L.frame(new FrameAttr().width("80pt").height("40pt"), List.of( L.img(new ImgAttr().name("logo").width("80pt").height("40pt")) )), L.frame(new FrameAttr().width("80pt").height("40pt"), List.of( L.img(new ImgAttr().name("photo").width("80pt").height("40pt")) ))))L.Row(new() { Gap = "m" }, [ L.Frame(new() { Width = "80pt", Height = "40pt" }, [ L.Img(new() { Name = "logo", Width = "80pt", Height = "40pt" }), ]), L.Frame(new() { Width = "80pt", Height = "40pt" }, [ L.Img(new() { Name = "photo", Width = "80pt", Height = "40pt" }), ]),])L::row(new RowAttr(gap: 'm'), [ L::frame(new FrameAttr(width: '80pt', height: '40pt'), [ L::img(new ImgAttr(name: 'logo', width: '80pt', height: '40pt')), ]), L::frame(new FrameAttr(width: '80pt', height: '40pt'), [ L::img(new ImgAttr(name: 'photo', width: '80pt', height: '40pt')), ]),])Fill the slot
Section titled “Fill the slot”width="fill" makes the picture as wide as the room it has, and its height follows its proportions. The room is the width of the column the image is in, what the line of a row leaves after the other children, or a table cell. A picture smaller than its room grows to fill it.
<row gap="m" align="center"> <img name="photo" width="fill"/> <text width="90pt">The picture takes what is left of the line.</text></row>L.row({ gap: 'm', align: 'center' }, [ L.img({ name: 'photo', width: 'fill' }), L.text({ width: '90pt' }, ['The picture takes what is left of the line.']),])L.row(RowAttr(gap='m', align='center'), [ L.img(ImgAttr(name='photo', width='fill')), L.text(TextAttr(width='90pt'), ['The picture takes what is left of the line.'])])L.row(new RowAttr().gap("m").align("center"), List.of( L.img(new ImgAttr().name("photo").width("fill")), L.text(new TextAttr().width("90pt"), List.of("The picture takes what is left of the line."))))L.Row(new() { Gap = "m", Align = "center" }, [ L.Img(new() { Name = "photo", Width = "fill" }), L.Text(new() { Width = "90pt" }, ["The picture takes what is left of the line."]),])L::row(new RowAttr(gap: 'm', align: 'center'), [ L::img(new ImgAttr(name: 'photo', width: 'fill')), L::text(new TextAttr(width: '90pt'), ['The picture takes what is left of the line.']),])Several fill children on one line share it equally, as in any row, so two pictures with width="fill" are two halves of the line.
A height limits the picture. It takes the largest size that fits the room and the height with its own proportions, and the parent’s align places it, as with a width and a height:
<img name="photo" width="fill" height="50pt"/>L.img({ name: 'photo', width: 'fill', height: '50pt' })L.img(ImgAttr(name='photo', width='fill', height='50pt'))L.img(new ImgAttr().name("photo").width("fill").height("50pt"))L.Img(new() { Name = "photo", Width = "fill", Height = "50pt" })L::img(new ImgAttr(name: 'photo', width: 'fill', height: '50pt'))Box around the picture
Section titled “Box around the picture”An image that sets padding, background or border is drawn as a box around its picture. width and height size the picture, as they do for any image (one size, or both as a maximum), and the box is larger than the picture by the padding. The border is drawn on the edge of the box and takes no room, as on every box. With width="fill" the box takes the room, and the picture fills what the padding leaves of it.
radius rounds the box and clips the picture to rounded corners: the box’s radius less the smallest padding, never below 0, so the picture follows the inside of the box. With no padding, background or border, radius clips the picture alone.
<row gap="m" align="center"> <img name="photo" width="96pt" padding="s" background="#f5f7fa" border="xs #dde3ed" radius="m"/> <img name="avatar" width="64pt" height="64pt" padding="3pt" border="2pt #1763cf" radius="35pt"/></row>L.row({ gap: 'm', align: 'center' }, [ L.img({ name: 'photo', width: '96pt', padding: 's', background: '#f5f7fa', border: 'xs #dde3ed', radius: 'm' }), L.img({ name: 'avatar', width: '64pt', height: '64pt', padding: '3pt', border: '2pt #1763cf', radius: '35pt' }),])L.row(RowAttr(gap='m', align='center'), [ L.img(ImgAttr(name='photo', width='96pt', padding='s', background='#f5f7fa', border='xs #dde3ed', radius='m')), L.img(ImgAttr(name='avatar', width='64pt', height='64pt', padding='3pt', border='2pt #1763cf', radius='35pt'))])L.row(new RowAttr().gap("m").align("center"), List.of( L.img(new ImgAttr().name("photo").width("96pt").padding("s").background("#f5f7fa").border("xs #dde3ed").radius("m")), L.img(new ImgAttr().name("avatar").width("64pt").height("64pt").padding("3pt").border("2pt #1763cf").radius("35pt"))))L.Row(new() { Gap = "m", Align = "center" }, [ L.Img(new() { Name = "photo", Width = "96pt", Padding = "s", Background = "#f5f7fa", Border = "xs #dde3ed", Radius = "m" }), L.Img(new() { Name = "avatar", Width = "64pt", Height = "64pt", Padding = "3pt", Border = "2pt #1763cf", Radius = "35pt" }),])L::row(new RowAttr(gap: 'm', align: 'center'), [ L::img(new ImgAttr(name: 'photo', width: '96pt', padding: 's', background: '#f5f7fa', border: 'xs #dde3ed', radius: 'm')), L::img(new ImgAttr(name: 'avatar', width: '64pt', height: '64pt', padding: '3pt', border: '2pt #1763cf', radius: '35pt')),])Rounded image
Section titled “Rounded image”<img name="avatar" width="48pt" height="48pt" radius="xxl"/>L.img({ name: 'avatar', width: '48pt', height: '48pt', radius: 'xxl' })L.img(ImgAttr(name='avatar', width='48pt', height='48pt', radius='xxl'))L.img(new ImgAttr().name("avatar").width("48pt").height("48pt").radius("xxl"))L.Img(new() { Name = "avatar", Width = "48pt", Height = "48pt", Radius = "xxl" })L::img(new ImgAttr(name: 'avatar', width: '48pt', height: '48pt', radius: 'xxl'))A picture that is not square is rounded at its own size: a radius larger than half its shorter side makes a pill, so give a square size for a circle.