Canva Dev Docs

Appearance

Apps SDK — Platform API ​

App Process ​

API reference for the appProcess namespace.

Provides methods for interacting with an app process.

Properties ​

<Prop.List> <Prop name="current" required readonly type="CurrentAppProcess" sourceLineNumbers={[9]}> The current app process.

For more information, see [appProcess.current](/docs/apps/api/latest/platform-app-process-current/).

</Prop> </Prop.List>

Methods ​

<Prop.List> <Prop name="requestClose" required type="function" sourceLineNumbers={[56]}> Requests the termination of the specified app process.

For more information, see [appProcess.requestClose](/docs/apps/api/latest/platform-app-process-request-close/).

</Prop>

<Prop name="registerOnStateChange" required type="function" sourceLineNumbers={[97]}> Registers a callback that runs when the state of the specified app process changes.

For more information, see [appProcess.registerOnStateChange](/docs/apps/api/latest/platform-app-process-register-on-state-change/).

</Prop>

<Prop name="registerOnMessage" required type="function" sourceLineNumbers={[120]}> Registers a callback that listens for broadcasted messages.

For more information, see [appProcess.registerOnMessage](/docs/apps/api/latest/platform-app-process-register-on-message/).

</Prop>

<Prop name="broadcastMessage" required type="function" sourceLineNumbers={[174]}> Broadcasts a message to all of the app's active processes, not including the current process.

For more information, see [appProcess.broadcastMessage](/docs/apps/api/latest/platform-app-process-broadcast-message/).

</Prop> </Prop.List>

App Process Current ​

API reference for the appProcess.current property.

Provides methods for interacting with the current app process.

Methods ​

<Prop.List> <Prop name="getInfo" required type="function" sourceLineNumbers={[293]}> Returns information about the current app process.

For more information, see [appProcess.current.getInfo](/docs/apps/api/latest/platform-app-process-current-get-info/).

</Prop>

<Prop name="requestClose" required type="function" sourceLineNumbers={[339]}> Requests the termination of the current process.

For more information, see [appProcess.current.requestClose](/docs/apps/api/latest/platform-app-process-current-request-close/).

</Prop>

<Prop name="setOnDispose" required type="function" sourceLineNumbers={[369]}> Registers a callback that runs when the current app process is about to close.

For more information, see [appProcess.current.setOnDispose](/docs/apps/api/latest/platform-app-process-current-set-on-dispose/).

</Prop> </Prop.List>

Get Process Info ​

API reference for the appProcess.current.getInfo method.

Returns information about the current app process.

Usage ​

Get current process information ​

typescript
import { appProcess } from '@canva/platform';

const currentProcess = appProcess.current;
const processInfo = currentProcess.getInfo();

Check current process surface type ​

typescript
import { appProcess } from '@canva/platform';

const currentProcess = appProcess.current;
const { surface } = currentProcess.getInfo();

if (surface === 'object_panel') {
  // This app is running in the object panel
}

Read current process launch parameters ​

typescript
import { appProcess } from '@canva/platform';

type MyLaunchParams ={
  mode: 'edit' | 'view';
  id: string;
}

const currentProcess = appProcess.current;
const { launchParams } = currentProcess.getInfo<MyLaunchParams>();

if (launchParams) {
  const { mode, id } = launchParams;
  // Use launch parameters
}

Returns ​

Information about an app process.

<Prop.List> <Prop name="surface" required type="AppSurface" sourceLineNumbers={[199]}> The surface on which the app process is running.

&lt;Prop.Extras&gt;
  **Available values**:

  * `"object_panel"`
  * `"selected_image_overlay"`
  * `"headless"`
&lt;/Prop.Extras&gt;

</Prop>

<Prop name="processId" required type="AppProcessId" sourceLineNumbers={[203]}> The unique identifier of the app process. </Prop>

<Prop name="launchParams" type="T" sourceLineNumbers={[207]}> Parameters passed to the app process when it was opened. </Prop> </Prop.List>

Request Close ​

API reference for the appProcess.current.requestClose method.

Requests the termination of the current process.

Once called, this method:

  1. Transitions the state of the process to "closing".
  2. Invokes all registered setOnDispose callbacks.
  3. Waits for the process to finish closing.
  4. Transitions the state of the process to "closed".

Each time the state changes, all of the registerOnStateChange callbacks are called.

Usage ​

Close current process ​

typescript
import { appProcess } from '@canva/platform';

await appProcess.current.requestClose({ reason: 'completed' });

Pass structured data to current process as it closes ​

typescript
import { appProcess, type CloseParams } from '@canva/platform';

type DetailedCloseParams = CloseParams & {
  metadata: {
    savePoint: string;
    timestamp: number;
    userInitiated: boolean;
  }
};

await appProcess.current.requestClose<DetailedCloseParams>({
  reason: 'completed',
  metadata: {
    savePoint: 'auto_backup_1',
    timestamp: Date.now(),
    userInitiated: true
  }
});

Parameters ​

<Prop.List> <Prop name="params" required type="T" sourceLineNumbers={[339]}> Parameters to pass to the setOnDispose callback. Any structured data can be passed via this property.

&lt;PillAccordion defaultExpanded={true} title={&lt;&gt;Properties of &lt;strong&gt;params&lt;/strong&gt;&lt;/&gt;}&gt;
  &lt;Prop.List&gt;
    &lt;Prop name="reason" required type="CloseReason" sourceLineNumbers={[231]}&gt;
      The reason the app process is closing.

      &lt;Prop.Extras&gt;
        **Available values**:

        * `"completed"`
        * `"aborted"`
      &lt;/Prop.Extras&gt;
    &lt;/Prop&gt;
  &lt;/Prop.List&gt;
&lt;/PillAccordion&gt;

</Prop> </Prop.List>

Returns ​

Promise&lt;void&gt;

Broadcast Message ​

API reference for the appProcess.broadcastMessage method.

Broadcasts a message to all of the app's active processes, not including the current process.

Usage ​

Broadcast primitive values ​

typescript
import { appProcess } from '@canva/platform';

// Broadcasting a string
appProcess.broadcastMessage('REFRESH_REQUESTED');

// Broadcasting a number
appProcess.broadcastMessage(42);

// Broadcasting a boolean
appProcess.broadcastMessage(true);

Broadcast simple objects ​

typescript
import { appProcess } from '@canva/platform';

appProcess.broadcastMessage({
  id: 'user-123',
  name: 'John Doe',
  active: true
});

Broadcast complex objects ​

typescript
import { appProcess } from '@canva/platform';

appProcess.broadcastMessage({
  type: 'DOCUMENT_UPDATE',
  timestamp: Date.now(),
  payload: {
    documentId: 'doc-123',
    version: 2,
    metadata: {
      title: 'Project Alpha',
      tags: ['draft', 'review-needed'],
      collaborators: [
        { id: 'user-1', role: 'editor' },
        { id: 'user-2', role: 'viewer' }
      ]
    }
  }
});

Parameters ​

<Prop.List> <Prop name="message" required type="any" sourceLineNumbers={[174]}> The message to be broadcasted. This can be any kind of structured data. </Prop> </Prop.List>

Returns ​

void

Features Register on Support Change ​

API reference for the features.registerOnSupportChange method.

Registers a callback that runs when the context changes and an SDK method becomes supported or unsupported.

Usage: Monitoring feature support changes ​

typescript
import { features } from '@canva/platform';
import { addElementAtPoint } from '@canva/design';

const supportDisposer = features.registerOnSupportChange(() => {
  const isNowSupported = features.isSupported(addElementAtPoint);
  // Update UI based on new support status
});

// Later: cleanup the listener
await supportDisposer();

Parameters ​

<Prop.List> <Prop name="onSupportChange" required type="function" sourceLineNumbers={[438]}> The callback that runs when the support status of an SDK method changes.

**Returns**

`void`

</Prop> </Prop.List>

Returns ​

Disposes an event listener.

() => void

Get Platform Info ​

API reference for the getPlatformInfo method.

Returns information about the platform on which the app is running.

Usage ​

Get platform information ​

typescript
import { getPlatformInfo } from '@canva/platform';

const platformInfo = await getPlatformInfo();

Check if app is running on platform that allows payments ​

typescript
import { getPlatformInfo } from '@canva/platform';

const platformInfo = await getPlatformInfo();

if (platformInfo.canAcceptPayments) {
  // Show payment-related UI elements
} else {
  // Hide payment-related UI elements
}

Returns ​

Information about the platform on which the app is running.

<Prop.List> <Prop name="canAcceptPayments" required type="boolean" sourceLineNumbers={[599]}> If true, the app is allowed to directly link to payment and upgrade flows.

This property is always `true` when the app is running in a web browser, but may otherwise be `false` in
order to comply with the policies of the platforms on which Canva is available. For example, some platforms
only allow payment-related actions that use their own payment mechanisms and apps are therefore not allowed
to render payment-related call-to-actions while running on those platforms.

&lt;Prop.Extras&gt;
  **Example**

  ```ts
  const info = getPlatformInfo();

  if (info.canAcceptPayments) {
    // Display payment links and upgrade flows
  } else {
    // Hide payment links and upgrade flows
    // Optionally, show an appropriate message
  }
  ```
&lt;/Prop.Extras&gt;

</Prop> </Prop.List>

Add Toast Notification ​

API reference for the notification.addToast method.

A method that shows a toast notification to the user.

Usage ​

tsx
import { notification } from '@canva/platform';
import type { ToastRequest } from '@canva/platform';

const showToast = () => {
  const request: ToastRequest = {
    messageText: "Hello world!",
  };
  notification.addToast(request);
};

<Button onClick={() => showToast()}>Show Toast</Button>

Parameters ​

<Prop.List> <Prop name="request" required type="ToastRequest" sourceLineNumbers={[499]}> Options for configuring a toast notification.

&lt;PillAccordion defaultExpanded={true} title={&lt;&gt;Properties of &lt;strong&gt;request&lt;/strong&gt;&lt;/&gt;}&gt;
  &lt;Prop.List&gt;
    &lt;Prop name="messageText" required type="string" sourceLineNumbers={[684]}&gt;
      Text to show within the toast notification.
    &lt;/Prop&gt;

    &lt;Prop name="timeoutMs" type="number | string" sourceLineNumbers={[694]}&gt;
      The duration that the notification will be visible.

      If set to `"infinite"`, the notification will be displayed until manually dismissed by the user.

      If set to a number, the notification will automatically disappear after that duration (in milliseconds).

      &lt;Prop.Extras&gt;
        **Default value**: `5000`
      &lt;/Prop.Extras&gt;
    &lt;/Prop&gt;
  &lt;/Prop.List&gt;
&lt;/PillAccordion&gt;

</Prop> </Prop.List>

Returns ​

The result when a toast notification is successfully added. This is a Promise that resolves with the following object:

<Prop.List> <Prop name="status" required type="string" sourceLineNumbers={[672]}> The status of the request.

The only valid value is `"completed"`.

</Prop> </Prop.List>

Request Open External URL ​

API reference for the requestOpenExternalUrl method.

Opens an external URL.

The URL is opened natively, such as in a new browser tab on desktop or in a browser sheet on mobile.

In some browsers, the user must enable popup permissions before any URL can be opened.

Usage ​

Open an external URL ​

typescript
import { requestOpenExternalUrl } from '@canva/platform';

await requestOpenExternalUrl({
  url: 'https://www.example.com',
});

Detect when a user navigates to the external URL ​

typescript
import { requestOpenExternalUrl } from '@canva/platform';

const response = await requestOpenExternalUrl({
  url: 'https://www.example.com',
});

if (response.status === 'completed') {
  // URL opened successfully
}

Detect when a user doesn't navigate to the external URL ​

typescript
import { requestOpenExternalUrl } from '@canva/platform';

const response = await requestOpenExternalUrl({
  url: 'https://www.example.com',
});

if (response.status === 'aborted') {
  // User declined to open URL
}

Parameters ​

<Prop.List> <Prop name="request" required type="OpenExternalUrlRequest" sourceLineNumbers={[662]}> Options for prompting the user to open an external URL.

&lt;PillAccordion defaultExpanded={true} title={&lt;&gt;Properties of &lt;strong&gt;request&lt;/strong&gt;&lt;/&gt;}&gt;
  &lt;Prop.List&gt;
    &lt;Prop name="url" required type="string" sourceLineNumbers={[564]}&gt;
      The URL to open.
    &lt;/Prop&gt;
  &lt;/Prop.List&gt;
&lt;/PillAccordion&gt;

</Prop> </Prop.List>

Returns ​

The result of prompting the user to open an external URL. This is a Promise that resolves with the following object:

<Tabs> <Tab name="Completed"> The result when a user agrees to navigate to an external URL.

&lt;Prop.List&gt;
  &lt;Prop name="status" required type="string" sourceLineNumbers={[553]}&gt;
    The status of the request.

    The only valid value is `"completed"`.
  &lt;/Prop&gt;
&lt;/Prop.List&gt;

</Tab>

<Tab name="Aborted"> The result when a user doesn't agree to navigate to an external URL.

&lt;Prop.List&gt;
  &lt;Prop name="status" required type="string" sourceLineNumbers={[542]}&gt;
    The status of the request.

    The only valid value is `"aborted"`.
  &lt;/Prop&gt;
&lt;/Prop.List&gt;

</Tab> </Tabs>

Platform Type Declarations ​

TypeScript type definitions for the @canva/platform package.

Tip: You can download the TypeScript types for the @canva/platform package here.

Canva Developer Documentation SOP Site

Built for internal use