ProductUse casesPricingBlogSign inStart free
ImageConfiguration

Events

Respond to save, export, close, and error events.

The editor tells your code about four moments: a design is saved, a design is exported, the editor closes, and something goes wrong. You receive them as callback props. The custom element also sends them as DOM events.

This page shows every callback and every event:

index.html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Image editor</title>
  </head>
  <body>
    <media-editor-image id="editor" style="position: fixed; inset: 0"></media-editor-image>

    <script type="module">
      import './node_modules/@layermetry/media-editor/dist/embed.modern.js';

      const editor = document.getElementById('editor');
      editor.props = {
        licenseKey: 'YOUR_LICENSE_KEY',
        onExport(file) {
          console.log(`onExport: ${file.name}`);
        },
        onClose() {
          console.log('onClose');
        },
        async onSaveTemplate({ template }) {
          console.log(`onSaveTemplate: ${template.id}`);
        },
        onLicenseState(report) {
          console.log(`onLicenseState: ${report.state.status}`);
        },
      };

      // The same moments, as DOM events. They bubble, so a listener on document also works.
      editor.addEventListener('templatesave', (event) => {
        console.log(`templatesave: saved=${event.detail.saved}`);
      });
      editor.addEventListener('close', () => {
        console.log('close event');
      });
    </script>
  </body>
</html>
CallbackDOM eventWhen
onSaveTemplatetemplatesaveThe user saves a template or a draft.
onExportexportThe user presses Save & Exit or Share in the export panel.
onClosecloseThe user closes the editor, and after Save & Exit.
onBrandChangebrandchangeThe editor opens with a brand kit, and the user switches the kit. See Brand kits.
onLicenseStatenoneThe state of the license changes.
onUploadAssetnoneThe editor needs to store a picture. See Asset storage.

The DOM events bubble, and they cross shadow DOM boundaries, so a listener on document also receives them.

Save

onSaveTemplate({ ...metadata, template }) saves the design. The editor waits for the promise that it returns, so a DOM event cannot replace it. See Saving and loading.

After each save, the element also sends templatesave, with detail: { template, saved }. saved is false when the save failed or took more than 30 seconds. template is null when the editor could not prepare the design.

editor.addEventListener('templatesave', (event) => {
  console.log(`templatesave: saved=${event.detail.saved}`);
});

Export

onExport(file, extras) receives the finished design as a File. See Export for the formats.

onExport={(file) => console.log(`${file.name}: ${file.size} bytes, ${file.type}`)}

extras is present when the user presses Share, or when the editor was opened with a defaultTemplate. extras.email is { to, name }: the address and the name that the user typed. extras.templateID is the id of the defaultTemplate. Read each field with a check, such as extras?.email?.to.

callback is an older name for onExport. The editor calls both, so use only one of them.

The custom element sends one export event for each export. event.detail is the File. The extras object is not in the event: read it from the second argument of onExport.

The Download button in the export panel saves the file on the user's computer and calls no callback.

Close

onClose() is required. The editor calls it when the user presses the close button in the top bar, and after Save & Exit. Remove or hide the editor when it runs.

onClose={() => setIsOpen(false)}

The custom element also sends a close event. Do not read its detail: after Save & Exit it is empty, and after the close button it is the editor's own click event.

The close button does not ask the user to save first. Save the design in onClose if your product needs it, for example with a draft. See Drafts.

Errors

The editor has no single error callback. Each kind of problem reaches you in its own way:

ProblemHow you learn about it
The license is refused or cannot be confirmedonLicenseState, with state.status 'blocked' and a reason. See License validation.
A save failsYour own onSaveTemplate promise rejects, and templatesave has saved: false.
A picture cannot be storedYour own onUploadAsset promise rejects. The save stops.
An AI request failsThe editor shows the error in the AI box. Your proxy or requestFn sees the failure first. See Custom AI endpoint.
The ai setting is wrongThe console shows "[MediaEditor] ai is not usable, so AI stays off:" and the reason.
onLicenseState={(report) => {
  if (report.state.status === 'blocked') {
    console.error(`License blocked (${report.state.reason}): ${report.reference}`);
  }
}}

report.reference is a short line for your support team. It never contains the license key. See Error codes for every reason.

On this page

SaveExportCloseErrors