Add Action Buttons

Add interactive save, export, and custom action buttons to your CE.SDK editor using built-in action components.

Add Action Buttons example showing a navigation bar with custom Save, Export, Share, and Download buttons

8 mins

estimated time

CE.SDK provides built-in action button components that you can insert and configure inline without needing to register custom components. There are two main approaches:

Built-in action buttons like ly.img.saveScene.navigationBar that integrate with the Actions API
Custom action buttons using ly.img.action.navigationBar with your own onClick handlers

import type { EditorPlugin, EditorPluginContext } from '@cesdk/cesdk-js';

import {
  BlurAssetSource,
  ColorPaletteAssetSource,
  CropPresetsAssetSource,
  DemoAssetSources,
  EffectsAssetSource,
  FiltersAssetSource,
  PagePresetsAssetSource,
  StickerAssetSource,
  TextAssetSource,
  TextComponentAssetSource,
  TypefaceAssetSource,
  UploadAssetSources,
  VectorShapeAssetSource
} from '@cesdk/cesdk-js/plugins';
import { DesignEditorConfig } from './design-editor/plugin';
import packageJson from './package.json';

class Example implements EditorPlugin {
  name = packageJson.name;
  version = packageJson.version;

  async initialize({ cesdk }: EditorPluginContext): Promise<void> {
    if (!cesdk) {
      throw new Error('CE.SDK instance is required for this plugin');
    }
    await cesdk.addPlugin(new DesignEditorConfig());

    // Add asset source plugins
    await cesdk.addPlugin(new BlurAssetSource());
    await cesdk.addPlugin(new ColorPaletteAssetSource());
    await cesdk.addPlugin(new CropPresetsAssetSource());
    await cesdk.addPlugin(new UploadAssetSources({ include: ['ly.img.image.upload'] }));
    await cesdk.addPlugin(
      new DemoAssetSources({
        include: [
          'ly.img.templates.blank.*',
          'ly.img.templates.presentation.*',
          'ly.img.templates.print.*',
          'ly.img.templates.social.*',
          'ly.img.image.*'
        ]
      })
    );
    await cesdk.addPlugin(new EffectsAssetSource());
    await cesdk.addPlugin(new FiltersAssetSource());
    await cesdk.addPlugin(new PagePresetsAssetSource());
    await cesdk.addPlugin(new StickerAssetSource());
    await cesdk.addPlugin(new TextAssetSource());
    await cesdk.addPlugin(new TextComponentAssetSource());
    await cesdk.addPlugin(new TypefaceAssetSource());
    await cesdk.addPlugin(new VectorShapeAssetSource());

    await cesdk.actions.run('scene.create', {
      page: {
        sourceId: 'ly.img.page.presets',
        assetId: 'ly.img.page.presets.print.iso.a6.landscape'
      }
    });

    // Add a built-in save button that integrates with the Actions API
    cesdk.ui.insertOrderComponent(
      { in: 'ly.img.navigation.bar', after: 'ly.img.spacer' },
      { id: 'ly.img.saveScene.navigationBar' }
    );

    // Register the action handler for the save button
    cesdk.actions.register('saveScene', async () => {
      const sceneString = await cesdk.engine.scene.saveToString();
      console.log('Scene saved via Actions API! Length:', sceneString.length);
      // In production: send sceneString to your backend
      cesdk.ui.showNotification({
        message: 'Scene saved successfully!'
      });
    });

    // Add a custom action button with inline onClick handler
    cesdk.ui.insertOrderComponent(
      { in: 'ly.img.navigation.bar', after: 'ly.img.saveScene.navigationBar' },
      {
        id: 'ly.img.action.navigationBar',
        key: 'my-custom-action',
        label: 'Custom',
        icon: '@imgly/Settings',
        onClick: async () => {
          console.log('Custom action clicked!');
          // Your custom logic here
        }
      }
    );

    // Add an Export button with accent styling
    cesdk.ui.insertOrderComponent(
      { in: 'ly.img.navigation.bar', after: 'ly.img.saveScene.navigationBar' },
      {
        id: 'ly.img.action.navigationBar',
        key: 'my-export',
        label: 'Export',
        icon: '@imgly/Download',
        color: 'accent',
        onClick: async () => {
          // Export to PNG using the utils API
          const { blobs } = await cesdk.utils.export({ mimeType: 'image/png' });
          console.log('Exported PNG! Size:', blobs[0].size);
          // In production: download or upload the blob
        }
      }
    );

    // Create a dropdown menu with multiple export options
    cesdk.ui.insertOrderComponent(
      { in: 'ly.img.navigation.bar' },
      {
        id: 'ly.img.actions.navigationBar',
        label: 'Download',
        icon: '@imgly/Download',
        children: [
          {
            id: 'ly.img.action.navigationBar',
            key: 'export-png',
            label: 'Download as PNG',
            onClick: async () => {
              const { blobs } = await cesdk.utils.export({
                mimeType: 'image/png'
              });
              downloadBlob(blobs[0], 'design.png');
            }
          },
          {
            id: 'ly.img.action.navigationBar',
            key: 'export-jpeg',
            label: 'Download as JPEG',
            onClick: async () => {
              const { blobs } = await cesdk.utils.export({
                mimeType: 'image/jpeg'
              });
              downloadBlob(blobs[0], 'design.jpg');
            }
          },
          {
            id: 'ly.img.action.navigationBar',
            key: 'export-pdf',
            label: 'Download as PDF',
            onClick: async () => {
              const { blobs } = await cesdk.utils.export({
                mimeType: 'application/pdf'
              });
              downloadBlob(blobs[0], 'design.pdf');
            }
          }
        ]
      }
    );

    // Insert multiple buttons at once with a separator between them
    cesdk.ui.insertOrderComponent(
      { in: 'ly.img.navigation.bar', before: 'ly.img.actions.navigationBar' },
      [
        {
          id: 'ly.img.action.navigationBar',
          key: 'share',
          label: 'Share',
          icon: '@imgly/Share',
          onClick: () => {
            console.log('Share clicked!');
          }
        },
        'ly.img.separator',
        {
          id: 'ly.img.action.navigationBar',
          key: 'print',
          label: 'Print',
          icon: '@imgly/Print',
          onClick: () => {
            window.print();
          }
        }
      ]
    );

    // Use the Utils API for export with built-in loading dialog
    cesdk.ui.insertOrderComponent(
      { in: 'ly.img.navigation.bar', before: 'ly.img.actions.navigationBar' },
      {
        id: 'ly.img.action.navigationBar',
        key: 'utils-export',
        label: 'Quick Export',
        icon: '@imgly/Download',
        color: 'accent',
        onClick: async () => {
          // cesdk.utils.export() shows a loading dialog automatically
          const { blobs } = await cesdk.utils.export({ mimeType: 'image/png' });
          // Download the exported file to user's device
          await cesdk.utils.downloadFile(blobs[0], 'image/png');
        }
      }
    );

    console.log('Add Action Buttons example loaded successfully');
  }
}

// Helper function to download a blob as a file
function downloadBlob(blob: Blob, filename: string) {
  const url = URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = url;
  a.download = filename;
  document.body.appendChild(a);
  a.click();
  document.body.removeChild(a);
  URL.revokeObjectURL(url);
}

export default Example;

This guide covers both approaches, along with button appearance configuration, dropdown menus, and the Utils API for export operations.

Use Built-in Action Buttons#

CE.SDK provides pre-configured action buttons for common operations like saving, exporting, and importing. These buttons have default labels and icons, and they automatically integrate with the Actions API.

// Add a built-in save button that integrates with the Actions API
cesdk.ui.insertOrderComponent(
  { in: 'ly.img.navigation.bar', after: 'ly.img.spacer' },
  { id: 'ly.img.saveScene.navigationBar' }
);

// Register the action handler for the save button
cesdk.actions.register('saveScene', async () => {
  const sceneString = await cesdk.engine.scene.saveToString();
  console.log('Scene saved via Actions API! Length:', sceneString.length);
  // In production: send sceneString to your backend
  cesdk.ui.showNotification({
    message: 'Scene saved successfully!'
  });
});

When you insert a built-in button like ly.img.saveScene.navigationBar, clicking it automatically calls the registered saveScene action. You provide the implementation by registering your handler with cesdk.actions.register().

Available built-in action buttons:

Component ID	Triggers Action	Default Label
`ly.img.saveScene.navigationBar`	`saveScene`	Save
`ly.img.shareScene.navigationBar`	`shareScene`	Share
`ly.img.exportImage.navigationBar`	`exportDesign`	Export as Image
`ly.img.exportPDF.navigationBar`	`exportDesign`	Export as PDF
`ly.img.exportVideo.navigationBar`	`exportDesign`	Export as Video
`ly.img.exportScene.navigationBar`	`exportScene`	Export Scene
`ly.img.exportArchive.navigationBar`	`exportScene`	Export Archive
`ly.img.importScene.navigationBar`	`importScene`	Import Scene
`ly.img.importArchive.navigationBar`	`importScene`	Import Archive

Add a Custom Action Button#

When you need full control over button behavior, use ly.img.action.navigationBar with a custom onClick handler. The key property must be unique across all action buttons in the editor.

// Add a custom action button with inline onClick handler
cesdk.ui.insertOrderComponent(
  { in: 'ly.img.navigation.bar', after: 'ly.img.saveScene.navigationBar' },
  {
    id: 'ly.img.action.navigationBar',
    key: 'my-custom-action',
    label: 'Custom',
    icon: '@imgly/Settings',
    onClick: async () => {
      console.log('Custom action clicked!');
      // Your custom logic here
    }
  }
);

The onClick handler can be synchronous or asynchronous. In this example, we serialize the scene and log the result. In production, you would send this data to your backend.

Configure Button Appearance#

Action buttons support several configuration options to customize their appearance and behavior.

// Add an Export button with accent styling
cesdk.ui.insertOrderComponent(
  { in: 'ly.img.navigation.bar', after: 'ly.img.saveScene.navigationBar' },
  {
    id: 'ly.img.action.navigationBar',
    key: 'my-export',
    label: 'Export',
    icon: '@imgly/Download',
    color: 'accent',
    onClick: async () => {
      // Export to PNG using the utils API
      const { blobs } = await cesdk.utils.export({ mimeType: 'image/png' });
      console.log('Exported PNG! Size:', blobs[0].size);
      // In production: download or upload the blob
    }
  }
);

Property	Type	Description
`id`	`string`	Must be `'ly.img.action.navigationBar'`
`key`	`string`	Unique identifier (required)
`label`	`string`	Button text label (required)
`onClick`	`() => void \| Promise<void>`	Click handler function
`icon`	`string`	Icon identifier (e.g., `'@imgly/Download'`)
`color`	`'accent' \| 'danger'`	Button color variant
`variant`	`'regular' \| 'plain'`	Button style variant
`isDisabled`	`boolean`	Whether button is disabled
`isLoading`	`boolean`	Whether to show loading state

Use ly.img.actions.navigationBar with a children array to create a dropdown menu containing multiple actions. This is useful when you have related actions that should be grouped together.

// Create a dropdown menu with multiple export options
cesdk.ui.insertOrderComponent(
  { in: 'ly.img.navigation.bar' },
  {
    id: 'ly.img.actions.navigationBar',
    label: 'Download',
    icon: '@imgly/Download',
    children: [
      {
        id: 'ly.img.action.navigationBar',
        key: 'export-png',
        label: 'Download as PNG',
        onClick: async () => {
          const { blobs } = await cesdk.utils.export({
            mimeType: 'image/png'
          });
          downloadBlob(blobs[0], 'design.png');
        }
      },
      {
        id: 'ly.img.action.navigationBar',
        key: 'export-jpeg',
        label: 'Download as JPEG',
        onClick: async () => {
          const { blobs } = await cesdk.utils.export({
            mimeType: 'image/jpeg'
          });
          downloadBlob(blobs[0], 'design.jpg');
        }
      },
      {
        id: 'ly.img.action.navigationBar',
        key: 'export-pdf',
        label: 'Download as PDF',
        onClick: async () => {
          const { blobs } = await cesdk.utils.export({
            mimeType: 'application/pdf'
          });
          downloadBlob(blobs[0], 'design.pdf');
        }
      }
    ]
  }
);

Each child in the children array follows the same configuration pattern as single action buttons. The dropdown automatically manages its open/close state and displays the children in a menu when clicked.

Add Multiple Buttons at Once#

You can insert multiple buttons in a single call by passing an array. This is more efficient than making multiple insertOrderComponent() calls and ensures the buttons appear together in the specified order.

// Insert multiple buttons at once with a separator between them
cesdk.ui.insertOrderComponent(
  { in: 'ly.img.navigation.bar', before: 'ly.img.actions.navigationBar' },
  [
    {
      id: 'ly.img.action.navigationBar',
      key: 'share',
      label: 'Share',
      icon: '@imgly/Share',
      onClick: () => {
        console.log('Share clicked!');
      }
    },
    'ly.img.separator',
    {
      id: 'ly.img.action.navigationBar',
      key: 'print',
      label: 'Print',
      icon: '@imgly/Print',
      onClick: () => {
        window.print();
      }
    }
  ]
);

The array can contain both component objects and string component IDs (like 'ly.img.separator'). This allows you to mix action buttons with layout components.

Available Icons#

Common icon identifiers for action buttons:

@imgly/Download - Download/export
@imgly/Save - Save
@imgly/Share - Share
@imgly/Upload - Upload/import
@imgly/Copy - Copy
@imgly/Trash - Delete
@imgly/Settings - Settings

Use Utils API for Export#

The Utils API (cesdk.utils) provides helper functions for common export and file operations. These are useful when implementing custom export buttons.

// Use the Utils API for export with built-in loading dialog
cesdk.ui.insertOrderComponent(
  { in: 'ly.img.navigation.bar', before: 'ly.img.actions.navigationBar' },
  {
    id: 'ly.img.action.navigationBar',
    key: 'utils-export',
    label: 'Quick Export',
    icon: '@imgly/Download',
    color: 'accent',
    onClick: async () => {
      // cesdk.utils.export() shows a loading dialog automatically
      const { blobs } = await cesdk.utils.export({ mimeType: 'image/png' });
      // Download the exported file to user's device
      await cesdk.utils.downloadFile(blobs[0], 'image/png');
    }
  }
);

Key Utils API methods:

Method	Purpose
`cesdk.utils.export(options)`	Export with automatic loading dialog and progress
`cesdk.utils.downloadFile(blob, mime)`	Download a file to the user’s device
`cesdk.utils.showLoadingDialog(opts)`	Show a progress dialog for long operations
`cesdk.utils.loadFile(options)`	Open a file picker to load user files

The export() method automatically displays a loading dialog with progress tracking for video exports. For more control, use cesdk.engine.block.export() directly with a custom loading dialog.

Troubleshooting#

Button not appearing - Ensure key is unique when using multiple ly.img.action.navigationBar components. Duplicate keys will cause only one button to appear.

onClick not firing - Check for JavaScript errors in the console. Ensure the handler is a function, not a function call.

Icon not showing - Verify the icon identifier is correct (case-sensitive). Icons use the @imgly/ prefix.

API Reference#

Method	Purpose
`cesdk.ui.insertOrderComponent()`	Insert action buttons into UI areas
`cesdk.actions.register()`	Register custom action handlers
`cesdk.utils.export()`	Export with built-in loading dialog
`cesdk.utils.downloadFile()`	Download file to user’s device
`cesdk.engine.block.export()`	Export blocks/scenes for download
`cesdk.engine.scene.saveToString()`	Serialize scene for saving

Next Steps#

Actions API - Learn about the Actions API and all available actions

Create Custom Components - Build fully custom buttons with the Builder API

Component Order API - Full API reference for UI manipulation

Navigation Bar - Area-specific configuration options