SVG

SVG support lives in the optional Papyra.Svg package, so the core Papyra package stays dependency-lean. Install it next to Papyra - the two must always be updated together, since Papyra.Svg pins the exact core version it was built against:

dotnet add package Papyra.Svg

using Papyra.Svg;

doc.Svg(File.ReadAllBytes("logo.svg"), width: 120f);

Svg(...) works everywhere Image(...) does - the document body, table cells, row items, list items, paragraphs (ParagraphBuilder.Svg), header/footer bands (HeaderFooterBuilder.Svg) - and additionally as a page background (PageBackgroundBuilder.Svg, with the usual COVER / CONTAIN / STRETCH / TILE fits) and as a watermark (WatermarkBuilder.Svg, centered with the watermark’s opacity). Sizing and alignment follow the exact same rules as images: ImageFit.Width / ORIGINAL, explicit width/height (contain-in-box when both are set), and LEFT/CENTER/RIGHT alignment.

Malformed SVG data fails immediately at compose time with a clear error.

Vector where possible, raster where necessary

Papyra parses the SVG once at compose time and picks one of two rendering modes:

• Vector mode - shapes, paths (including Béziers and arcs), groups, transforms, use references, clip paths, solid fills and strokes (with opacity, dash patterns, caps and joins), and linear/radial gradients translate into native PDF vector operators. The result stays crisp at any zoom level and adds only a few hundred bytes per graphic.
• Raster mode - anything the PDF vector model cannot express faithfully (text, filters, masks, patterns, embedded raster images, blend modes, spreadMethod="repeat|reflect") is rendered pixel-perfectly by a full SVG engine instead and embedded as a high-resolution bitmap (3× the laid-out size, ~216 DPI effective). Nothing is rejected - every valid SVG renders.

The mode is chosen per document graphic, automatically. A logo with paths and gradients stays vector; an SVG containing <text> becomes a bitmap in PDF (convert text to paths in your editor to keep it vector).

Intrinsic size

SVG user units map 1:1 to points, matching Papyra’s “no DPI” convention:

1. Absolute root width/height attributes win (px ≡ pt; mm, cm, in, pc convert).
2. Otherwise the viewBox size applies - a single absolute dimension keeps the viewBox aspect ratio.
3. Otherwise the CSS replaced-element default of 300×150 is used.

Per-format behavior

• PDF - vector mode emits a Form XObject with real path operators and shadings; raster mode embeds the high-resolution PNG. Both stay conformant under PDF/A-2, PDF/A-3, and PDF/A-4.
• DOCX / XLSX - the original SVG is embedded natively (the same svgBlip representation Office itself writes) together with a high-resolution PNG fallback that older Office versions render. Watermarks and page backgrounds are VML constructs that cannot host SVG, so those degrade to the raster fallback.
• HTML - the original SVG bytes are embedded as a data: URI and rendered by the browser, so even graphics the PDF renderer rasterizes stay vector in HTML.

See also

• Images
• Feature support matrix