Polotno
Export & Import

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-import

It 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

OptionDefaultMeaning
idmlrequiredThe bytes of the file, as an ArrayBuffer or Uint8Array
dpi96Design dpi. One point is dpi / 72 px
fontsFont files (TTF or OTF)
resolveLinkReturns the bytes or the URL of a linked graphic
convertGraphicConverts a PDF, AI, PSD, EPS or TIFF graphic into a design or a picture
uploadAssetHosts a picture or a font and returns its URL. The default is data URLs
onWarningReceives 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 fonts when the family and the style agree, and the font goes into design.fonts. For other families, the importer uses the Google font of the same name. If there is none, it uses a similar family and sends FONT_SUBSTITUTED. A file in fonts that is not a readable TTF or OTF font is not used (FONT_UNREADABLE).
  • Links. resolveLink returns 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 sends GRAPHIC_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') at dpi. The design size is the size of the first page. A page of a different size has its own width and height.
  • 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.

CodeMeaning
FONT_SUBSTITUTEDA font is drawn in a different family
FONT_UNREADABLEA file in fonts is not used
TEXT_FEATURE_UNSUPPORTEDA text feature is approximated or dropped, such as glyph scaling, drop caps or tab stops
TEXT_OVERSETText that InDesign hides as overset is not imported; details.text shows its start
SHAPE_FEATURE_UNSUPPORTEDA shape feature, such as a corner option or a stroke type, is approximated
EFFECT_UNSUPPORTEDA transparency effect other than a drop shadow is not drawn
GRAPHIC_MISSINGA linked graphic is not available. A placeholder is drawn
GRAPHIC_UNSUPPORTEDA graphic is not drawn, or is drawn approximately
OBJECT_UNSUPPORTEDAn 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 }:

reasonMeaning
corruptNot 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)
unsupportedA zip file that is not an IDML package, or XML nested deeper than 256 levels
too-largeA 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.

On this page