Units and Measures
How Polotno uses pixels, setting UI units, converting values, and export DPI
What metrics are using in Polotno?
Polotno stores dimensions such as width, height, and fontSize in design pixels. The default store.dpi is 72. At that setting, one design pixel maps to one PDF point. This is a design-unit conversion, not the CSS ratio between px and pt.
Use store.setUnit() to change the units shown in the editor and the DPI used for physical-size conversion.
store.setUnit({
unit: 'mm', // mm, cm, in, pt, px
dpi: 300,
});How to display units in custom UI?
Also you can use special functions to convert units to pixels and back:
import { pxToUnitRounded, unitToPx, pxToUnit } from 'polotno/utils/unit';
// convert 100 pixels to mm with 300 DPI
var mm = pxToUnit({
px: 100,
unit: 'mm',
dpi: 300,
});
// do the same, but with 2 digits rounding, so number doesn't look ugly long in UI
var mm = pxToUnitRounded({
px: 100,
unit: 'mm',
precious: 2,
dpi: 300,
});
// convert 30 mm to pixels with 300 DPI
var pixels = unitToPx({
unit: 'mm',
dpi: 300,
unitVal: 30,
});Exports and DPI
For the built-in store.saveAsPDF() and store.toPDFDataURL() methods, page size uses the export dpi option, then store.dpi. The initial store DPI is 72. Increasing only DPI makes the physical page smaller without adding pixels. To increase raster export quality:
Use a higher pixelRatio, for example store.saveAsPDF({ pixelRatio: 2 }). This adds raster pixels without changing the physical page size. If you instead increase design dimensions, scale element coordinates and sizes by the same factor. Increase DPI by that factor to preserve the physical size.
DPI Metadata in PNG and JPEG Exports
For PNG and JPEG exports, Polotno can embed DPI resolution metadata directly into the image file. This is useful for print workflows where downstream software needs to know the intended print resolution.
// Embed 300 DPI metadata
await store.saveAsImage({ dpi: 300 });
// Control when metadata is embedded
await store.toDataURL({
dpi: 300,
dpiMetadata: 'auto' // 'auto' | 'always' | 'never'
});Behavior:
dpiMetadata: 'auto'(default): Embeds DPI only when it differs from 72dpiMetadata: 'always': Always embeds DPI metadatadpiMetadata: 'never': Never embeds DPI metadata
The dpi parameter defaults to store.dpi if not specified. DPI metadata embedding only works with PNG and JPEG formats, not PDF or other formats.
Common Questions
How do I create print-ready designs?
Use store.setUnit({ unit: 'mm', dpi: 300 }) to work in print units. For export quality, increase pixelRatio in PDF export.
Why doesn't changing DPI improve export quality?
DPI only affects UI display and page dimensions, not render quality. Use pixelRatio in export functions to increase quality.
Can I mix units in a design?
The canvas editor internally uses pixels. Units are for display only. Use conversion functions to work with different units programmatically.