Skip navigation

Skip to main content

API reference
Intents: design
API reference

overlay.registerOnCanOpen

API reference for the overlay.registerOnCanOpen method.

Registers a callback that runs when the canOpen state of an overlay target changes.

Usage

Register overlay handler

import { overlay } from "@canva/design";


overlay.registerOnCanOpen({
  target: 'image_selection',
  onCanOpen: async (event) => {
    if (event.canOpen) {
      // Can open overlay for selected image
    }
  }
});
TYPESCRIPT

Open image editing overlay

import { overlay } from "@canva/design";


overlay.registerOnCanOpen({
  target: 'image_selection',
  onCanOpen: async (event) => {
    if (event.canOpen) {
      const processId = await event.open({
        launchParameters: {
          mode: 'edit'
        }
      });
      // Overlay process started, with `processId`
    }
  }
});
TYPESCRIPT

Open overlay with filters

import { overlay } from "@canva/design";


overlay.registerOnCanOpen({
  target: 'image_selection',
  onCanOpen: async (event) => {
    if (event.canOpen) {
      await event.open({
        launchParameters: {
          mode: 'edit',
          filters: ['brightness', 'contrast', 'saturation']
        }
      });
    }
  }
});
TYPESCRIPT

Handle overlay unavailability

import { overlay } from "@canva/design";


overlay.registerOnCanOpen({
  target: 'image_selection',
  onCanOpen: async (event) => {
    if (!event.canOpen) {
      // Cannot open overlay, handle specific reasons
      switch (event.reason) {
        case 'no_selection':
          // No image is selected
          break;
        case 'invalid_selection':
          // Selected content cannot be edited
          break;
      }
    }
  }
});
TYPESCRIPT

Parameters

optsobject
Required

Options for configuring the callback.

targetTarget
Required

The target to check the canOpen state of.

This must be "image_selection".

onCanOpenfunction
Required

A callback that runs when the canOpen state of the specified target changes.

This callback fires immediately.

Parameters

eventOverlayOpenableEvent<Target>
Required

Information about whether or not an overlay can be opened for the specified target.

Information about an overlay that can't be opened for the specified target.

canOpenboolean
Required

Indicates that the overlay can't be opened for the specified target.

This must be false.

reasonstring
Required

Indicates the reason the overlay can't be opened for the specified target.

canOpenboolean
Required

Indicates that the overlay can be opened for the selected image.

This must be true.

openfunctionRead-only
Required

Opens an overlay for the selected image.

Parameters

optionsobject
Required
launchParametersunknown
Optional

Parameters to pass to the overlay when it opens.

This can be any type of structured data.

Returns

A unique identifier that references an app runtime process.

Promise<AppProcessId>

Returns

void

Returns

() => void