IDML Import
Import Adobe InDesign (.idml) files into your web editor as editable elements with the @polotno/idml-import JavaScript package, in the browser or Node.js
The @polotno/idml-import package converts an Adobe InDesign .idml file into Polotno design JSON, in the browser or in Node.js. Text frames, shapes, lines, pictures and tables arrive as separate, editable elements, never as a flattened page image. Each InDesign page becomes one page.
Importing other formats? See PDF Import, PSD Import, PPTX Import and SVG Import for the equivalent packages.
Installation
npm install @polotno/idml-importIt runs in the browser and in Node.js 22.13 or newer.
Basic Usage
Browser – read bytes from a file input:
import { idmlToJson } from '@polotno/idml-import';
const file = input.files[0];
const json = await idmlToJson({
idml: await file.arrayBuffer(),
onWarning: (w) => console.warn(w.code, w.message, w.details),
});
store.loadJSON(json);Node.js – read bytes from disk:
import { readFile } from 'node:fs/promises';
import { idmlToJson } from '@polotno/idml-import';
const json = await idmlToJson({ idml: await readFile('./brochure.idml') });Options
| Option | Default | Meaning |
|---|---|---|
idml | required | The bytes of the file, as an ArrayBuffer or Uint8Array |
dpi | 96 | Design dpi. One point is dpi / 72 px |
fonts | Font files (TTF or OTF) | |
resolveLink | Returns the bytes or the URL of a linked graphic | |
convertGraphic | Converts a PDF, AI, PSD, EPS or TIFF graphic into a design or a picture | |
uploadAsset | Hosts a picture or a font and returns its URL. The default is data URLs | |
onWarning | Receives each feature that the importer approximated or dropped |
Fonts and Linked Graphics
An .idml file does not contain its linked pictures or its fonts. The InDesign command File → Package writes them into the Links and Document fonts folders. Pass both:
const json = await idmlToJson({
idml,
fonts: documentFontFiles,
// InDesign records the author's file path. Find the file by its name.
resolveLink: async ({ uri, name }) => linksFolder.get(name) ?? null,
});- Fonts. Text uses a font from
fontswhen the family and the style agree, and the font goes intodesign.fonts. For other families, the importer uses the Google font of the same name. If there is none, it uses a similar family and sendsFONT_SUBSTITUTED. A file infontsthat is not a readable TTF or OTF font is not used (FONT_UNREADABLE). - Links.
resolveLinkreturns bytes or{ url }. If it returns nothing, the importer uses the preview that InDesign stored in the file. If there is no preview, it draws a grey placeholder and sendsGRAPHIC_MISSING.
Placed PDF, AI and PSD Graphics
A browser cannot draw a placed PDF, Illustrator, Photoshop, EPS or TIFF file. convertGraphic receives each file once per placed page. Return a Polotno design to get editable elements in a group, for example with PDF Import and PSD Import:
import { pdfToJson } from '@polotno/pdf-import';
import { psdToJson } from '@polotno/psd-import';
const json = await idmlToJson({
idml,
resolveLink,
convertGraphic: async ({ bytes, mimeType }) => {
// An AI file saved with PDF content has the PDF type.
if (mimeType === 'application/pdf')
return { design: await pdfToJson({ pdf: bytes }) };
if (mimeType === 'image/vnd.adobe.photoshop')
return { design: await psdToJson({ psd: bytes }) };
return null;
},
});The request has bytes, mimeType, name and the 1-based page. Return { design }, PNG, JPEG or SVG bytes, or { url }. If you return nothing, the importer draws a placeholder and sends GRAPHIC_UNSUPPORTED.
Output
- The design is in pixels (
unit: 'px') atdpi. The design size is the size of the first page. A page of a different size has its ownwidthandheight. - Master page items are copied onto each page that uses the master, with
custom.idml.master: true. - Hidden layers, non-printing layers and hidden items are not imported.
- Each element has
custom.idml = { id, kind }: the InDesign id and the object type of its source. - A threaded story becomes one text element for each frame or column.
- CMYK swatches stay CMYK (
device-cmyk(...)).
Warnings
onWarning receives { code, message, details } for each feature that the importer approximated or dropped. A warning is sent one time for each code and details, and the import continues. Narrow on code to read details with their types; the type IdmlWarningDetailsMap in the package's declarations gives each field.
| Code | Meaning |
|---|---|
FONT_SUBSTITUTED | A font is drawn in a different family |
FONT_UNREADABLE | A file in fonts is not used |
TEXT_FEATURE_UNSUPPORTED | A text feature is approximated or dropped, such as glyph scaling, drop caps or tab stops |
TEXT_OVERSET | Text that InDesign hides as overset is not imported; details.text shows its start |
SHAPE_FEATURE_UNSUPPORTED | A shape feature, such as a corner option or a stroke type, is approximated |
EFFECT_UNSUPPORTED | A transparency effect other than a drop shadow is not drawn |
GRAPHIC_MISSING | A linked graphic is not available. A placeholder is drawn |
GRAPHIC_UNSUPPORTED | A graphic is not drawn, or is drawn approximately |
OBJECT_UNSUPPORTED | An object is approximated or not imported, or a part of the document cannot be read as written |
Limitations
- Line breaks agree with InDesign in most lines, not in all lines.
- Hyphenation is available for Basque, Bulgarian, Catalan, Croatian, Danish, Dutch, English, Estonian, French, Galician, German, Greek, Icelandic, Italian, Lithuanian, Norwegian, Polish, Portuguese, Russian, Slovak, Slovenian, Spanish, Swedish, Turkish and Ukrainian. Text in other languages is imported without automatic hyphens.
- Overset text: InDesign hides text that does not fit the frames of its story. This text is not imported.
- Tables become Polotno tables. Each cell is plain text in one style.
- Anchored objects: an object alone in its paragraph is imported. An object inside a line of text, or one with a custom position, is not.
- Text on a path becomes curved text on an arc.
- Text wrap around objects is not imported.
- Drop caps, glyph scaling, baseline shift and custom tab stops are approximated or dropped.
- Converted graphics: Polotno cannot clip a group or shear an element. An element that crosses the frame edge stays whole, and a sheared graphic is drawn without shear.
- A graphic rotated inside its frame is drawn without that rotation.
- Transparency effects: a drop shadow is drawn. Inner shadows, glows, bevels and feathers are not.
Error Handling
A file that cannot be imported rejects with code: 'IMPORT_FAILED' and details: { format: 'idml', reason }:
reason | Meaning |
|---|---|
corrupt | Not a zip file, or a damaged package. An .indd, .idms or .icml file is not a zip file: save the document as IDML in InDesign (Save As) |
unsupported | A zip file that is not an IDML package, or XML nested deeper than 256 levels |
too-large | A part of the package is larger than 383 MiB, or the parts together are larger than 1 GiB |
Use code and details.reason in your code, not the message. An error from resolveLink, convertGraphic or uploadAsset rejects idmlToJson unchanged. See Error Handling for the codes every package shares.