updateLayout

API reference for the "updateLayout" method.

Updates the layout of the element in the user's design.

The layout defines:

  • The dimensions of the element.

  • The position of the element (relative to the page).

  • The rotation of the element.

  • The visible section—the crop box—of the element.

Calling the updateLayout method triggers the onLayoutChange callback.

Notes

  • Some elements have properties that lock them in place in the Canva document, such as grids and images set as a document background. With these elements, it's only possible to modify the following layout properties:

    • cropBox.top

    • cropBox.left

    • height

    • width

  • After calling the updateLayout method, always use the data in the onLayoutChange callback as the source of truth. You can then determine when only some of the properties have changed.

  • If you only update the layout's width and height, Canva keeps the element centered on its original origin. If the existing layout has a crop box, Canva automatically scales the crop box to maintain the element's appearance.

Usage

const { imageHelpers } = window.canva;
const canva = window.canva.init();
canva.onReady(async (opts) => {
// Change the rotation of the user's image
opts.element.layout.rotation += 90;
// Update the layout to render the rotation
canva.updateLayout({ layout: opts.element.layout });
// Handle save requests
canva.onSaveRequest(async () => {
return opts.element;
});
// Exit the extension
canva.exit();
});

Parameters

Name

Type

Required

Description

opts

object

Yes

Options for updating the element's layout.

opts.layout

Partial<CanvaElementLayout>

Yes

The updated layout of the element. If you pass through an incomplete layout, Canva uses the existing values in place of the missing values.

Returns

void