Page Format

Availability

Page-format controls require a plan that includes Document Page Format Controls. Projects without this feature use fixed A4 portrait pages and don't show these controls. Non-default values supplied through editor configuration, loadDesign, or setBodyValues are normalized back to A4 portrait for those projects.

The document builder lets end-users pick the paper size and orientation for their design. These two properties live on the body and surface in two places when displayMode is 'document':

• the body's property panel under Document → Size / Orientation, and
• the editor's top toolbar (the Size and Orientation dropdowns next to the device buttons).

The values flow through the design JSON as body.values.documentSize and body.values.documentOrientation, and the Export PDF endpoint reads them when rendering. Page margins are derived internally from the selected size (e.g. A5 uses a tighter margin than A4) and aren't user-configurable.

documentSize is the saved editor setting. To choose a paper size for one PDF export without changing the saved design, pass pageSize to exportPdf. See Export PDF for API availability.

You can customize both settings through the standard tools.bodies.properties configuration on unlayer.init, the same shape used for any other tool option. The body tool registers itself under the plural id bodies — tools.body (singular) is silently ignored.

Changing the Default Values

Set editor.defaultValue to change what new documents start with. End-users can still change the value from the property panel and top toolbar.

unlayer.init({
  displayMode: 'document',
  tools: {
    bodies: {
      properties: {
        documentSize: {
          editor: { defaultValue: 'Letter' },
        },
        documentOrientation: {
          editor: { defaultValue: 'landscape' },
        },
      },
    },
  },
});

Property	Type	Default
documentSize	'A3' | 'A4' | 'A5' | 'Legal' | 'Letter' | 'Tabloid'	'A4'
documentOrientation	'portrait' | 'landscape'	'portrait'

Restricting Available Choices

For the size and orientation pickers, set widgetParams.allowedValues to limit which options end-users can choose from. Labels are still pulled from the built-in schema, so locale and translations keep working. Both the property panel and the top toolbar honor the same list.

unlayer.init({
  displayMode: 'document',
  tools: {
    bodies: {
      properties: {
        documentSize: {
          editor: {
            defaultValue: 'Letter',
            widgetParams: { allowedValues: ['A4', 'Letter'] },
          },
        },
        documentOrientation: {
          editor: {
            widgetParams: { allowedValues: ['portrait'] },
          },
        },
      },
    },
  },
});

Hiding the Pickers

Pass widgetParams.allowedValues: [] to remove the picker from both the property panel and the top toolbar entirely. editor.defaultValue controls new documents and designs where the property is missing; it does not overwrite a value already stored in a loaded design.

unlayer.init({
  displayMode: 'document',
  tools: {
    bodies: {
      properties: {
        documentSize: {
          editor: {
            defaultValue: 'Letter',
            widgetParams: { allowedValues: [] }, // hide picker; default new documents to Letter
          },
        },
        documentOrientation: {
          editor: {
            defaultValue: 'portrait',
            widgetParams: { allowedValues: [] }, // hide picker; default new documents to portrait
          },
        },
      },
    },
  },
});

If you need to enforce one page format for existing designs as well, normalize the saved body.values.documentSize and body.values.documentOrientation before calling loadDesign, or call setBodyValues after loading. Hiding the controls only prevents end-users from changing the stored value in the editor UI.

info

These overrides set what end-users see in the editor. To render an existing design at a different page format from a single exportPdf call without changing the editor's defaults, use the per-call options described in Export PDF → Page Format.