Customize the Clip Context Menu

Customize the dropdown menu on video timeline clips — control which actions appear, their order, and add custom entries per clip type.

Customize Clip Context Menu example showing the video editor with clip menu customization

8 mins

estimated time

Download

StackBlitz

GitHub

The clip context menu is the dropdown that opens via a dedicated button on each clip in the video timeline. CE.SDK provides a different default menu per clip type: background clips show move, overlay, mute, and trim actions; overlay clips show layering and clip-conversion actions; caption clips show merge, add, and delete actions. All menus are customizable through the ly.img.video.clip.menu UI area using the Component Order API.

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

import {
  BlurAssetSource,
  CaptionPresetsAssetSource,
  ColorPaletteAssetSource,
  CropPresetsAssetSource,
  DemoAssetSources,
  EffectsAssetSource,
  FiltersAssetSource,
  PagePresetsAssetSource,
  StickerAssetSource,
  TextAssetSource,
  TextComponentAssetSource,
  TypefaceAssetSource,
  UploadAssetSources,
  VectorShapeAssetSource
} from '@cesdk/cesdk-js/plugins';
import { VideoEditorConfig } from './video-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');
    }

    // Enable video editing features
    cesdk.feature.enable('ly.img.video.*');

    await cesdk.addPlugin(new VideoEditorConfig());

    // Add asset source plugins
    await cesdk.addPlugin(new BlurAssetSource());
    await cesdk.addPlugin(new CaptionPresetsAssetSource());
    await cesdk.addPlugin(new ColorPaletteAssetSource());
    await cesdk.addPlugin(new CropPresetsAssetSource());
    await cesdk.addPlugin(
      new UploadAssetSources({
        include: [
          'ly.img.image.upload',
          'ly.img.video.upload',
          'ly.img.audio.upload'
        ]
      })
    );
    await cesdk.addPlugin(
      new DemoAssetSources({
        include: [
          'ly.img.templates.video.*',
          'ly.img.image.*',
          'ly.img.audio.*',
          'ly.img.video.*'
        ]
      })
    );
    await cesdk.addPlugin(new EffectsAssetSource());
    await cesdk.addPlugin(new FiltersAssetSource());
    await cesdk.addPlugin(
      new PagePresetsAssetSource({
        include: [
          'ly.img.page.presets.instagram.*',
          'ly.img.page.presets.facebook.*',
          'ly.img.page.presets.x.*',
          'ly.img.page.presets.linkedin.*',
          'ly.img.page.presets.pinterest.*',
          'ly.img.page.presets.tiktok.*',
          'ly.img.page.presets.youtube.*',
          'ly.img.page.presets.video.*'
        ]
      })
    );
    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', { mode: 'Video' });

    // Retrieve the default clip menu order for background clips
    const clipOrder = cesdk.ui.getComponentOrder({
      in: 'ly.img.video.clip.menu',
      when: { clipType: 'clip' }
    });
    console.log('Default clip menu order:', clipOrder);

    // Retrieve the default overlay menu order
    const overlayOrder = cesdk.ui.getComponentOrder({
      in: 'ly.img.video.clip.menu',
      when: { clipType: 'overlay' }
    });
    console.log('Default overlay menu order:', overlayOrder);

    // Retrieve the default caption menu order
    const captionOrder = cesdk.ui.getComponentOrder({
      in: 'ly.img.video.clip.menu',
      when: { clipType: 'caption' }
    });
    console.log('Default caption menu order:', captionOrder);

    // Replace the overlay menu with a simplified layout
    cesdk.ui.setComponentOrder(
      { in: 'ly.img.video.clip.menu', when: { clipType: 'overlay' } },
      [
        'ly.img.video.clip.menu.setAsClip',
        'ly.img.separator',
        'ly.img.video.clip.menu.duplicate',
        'ly.img.video.clip.menu.delete'
      ]
    );

    // Add a custom "Export Clip" action to the background clip menu
    cesdk.ui.insertOrderComponent(
      {
        in: 'ly.img.video.clip.menu',
        before: 'ly.img.video.clip.menu.delete',
        when: { clipType: 'clip' }
      },
      {
        id: 'ly.img.video.clip.menu.action',
        key: 'export-clip',
        label: 'Export Clip',
        icon: '@imgly/Download',
        onClick: () => {
          console.log('Export Clip action triggered');
        }
      }
    );

    // Remove the placeholder action from the background clip menu
    cesdk.ui.removeOrderComponent({
      in: 'ly.img.video.clip.menu',
      match: 'ly.img.video.clip.menu.placeholder',
      when: { clipType: 'clip' }
    });

    // Insert a separator after the trim action in the clip menu
    cesdk.ui.insertOrderComponent(
      {
        in: 'ly.img.video.clip.menu',
        after: 'ly.img.video.clip.menu.trim',
        when: { clipType: 'clip' }
      },
      'ly.img.separator'
    );

    // Disable the custom export action conditionally
    cesdk.ui.updateOrderComponent(
      {
        in: 'ly.img.video.clip.menu',
        match: { id: 'ly.img.video.clip.menu.action', key: 'export-clip' },
        when: { clipType: 'clip' }
      },
      { isDisabled: false }
    );
  }
}

export default Example;

This guide covers reading the default menu order, replacing or modifying the menu per clip type, removing and inserting built-in actions, and adding custom actions with callbacks.

Each clip type has its own default order. The menu renders components in the order defined by setComponentOrder or the built-in defaults.

Clip (Background Track): Move Left, Move Right, Set as Overlay, Mute, Trim, Replace, Placeholder, Duplicate, Delete — with separators grouping related actions.

Overlay (Foreground Track): Bring Forward, Send Backward, Set as Clip, Mute, Trim, Replace, Placeholder, Duplicate, Delete.

Caption: Merge Captions, Add Caption, Delete.

Available Component IDs#

All built-in component IDs that you can use when configuring menu orders:

Component ID	Purpose
`ly.img.video.clip.menu.moveLeft`	Move clip earlier in the track
`ly.img.video.clip.menu.moveRight`	Move clip later in the track
`ly.img.video.clip.menu.bringForward`	Move overlay one layer up
`ly.img.video.clip.menu.sendBackward`	Move overlay one layer down
`ly.img.video.clip.menu.setAsOverlay`	Convert clip to overlay
`ly.img.video.clip.menu.setAsClip`	Convert overlay to clip
`ly.img.video.clip.menu.mute`	Toggle audio mute
`ly.img.video.clip.menu.trim`	Open trim controls
`ly.img.video.clip.menu.caption.merge`	Merge adjacent captions
`ly.img.video.clip.menu.caption.add`	Add a new caption
`ly.img.video.clip.menu.replace`	Replace clip media
`ly.img.video.clip.menu.placeholder`	Toggle placeholder mode
`ly.img.video.clip.menu.duplicate`	Duplicate the clip
`ly.img.video.clip.menu.delete`	Delete the clip
`ly.img.video.clip.menu.action`	Generic custom action slot
`ly.img.separator`	Visual separator between groups

Reading the Current Order#

We retrieve the current menu order for any clip type using cesdk.ui.getComponentOrder(). Pass the when option with clipType to target a specific clip type. Without a when clause, the default 'clip' type order is returned.

// Retrieve the default clip menu order for background clips
const clipOrder = cesdk.ui.getComponentOrder({
  in: 'ly.img.video.clip.menu',
  when: { clipType: 'clip' }
});
console.log('Default clip menu order:', clipOrder);

// Retrieve the default overlay menu order
const overlayOrder = cesdk.ui.getComponentOrder({
  in: 'ly.img.video.clip.menu',
  when: { clipType: 'overlay' }
});
console.log('Default overlay menu order:', overlayOrder);

// Retrieve the default caption menu order
const captionOrder = cesdk.ui.getComponentOrder({
  in: 'ly.img.video.clip.menu',
  when: { clipType: 'caption' }
});
console.log('Default caption menu order:', captionOrder);

This is useful for inspecting the current state before making modifications, or for building a UI that displays the current configuration.

Replacing the Entire Order#

We can override the full menu for a clip type using cesdk.ui.setComponentOrder(). Pass an array of component IDs to define the complete new order. Each clip type is configured independently — changing the overlay menu does not affect clip or caption menus.

// Replace the overlay menu with a simplified layout
cesdk.ui.setComponentOrder(
  { in: 'ly.img.video.clip.menu', when: { clipType: 'overlay' } },
  [
    'ly.img.video.clip.menu.setAsClip',
    'ly.img.separator',
    'ly.img.video.clip.menu.duplicate',
    'ly.img.video.clip.menu.delete'
  ]
);

Here we replace the overlay menu with only four items: a “Set as Clip” action, a separator, then duplicate and delete. All other default overlay actions are removed.

Removing Actions#

We remove a specific action from a clip type’s menu using cesdk.ui.removeOrderComponent(). The match option accepts a component ID string, an index, or a predicate function.

// Remove the placeholder action from the background clip menu
cesdk.ui.removeOrderComponent({
  in: 'ly.img.video.clip.menu',
  match: 'ly.img.video.clip.menu.placeholder',
  when: { clipType: 'clip' }
});

This removes only the placeholder action from the background clip menu. The overlay and caption menus remain unchanged.

Inserting Actions#

We insert a component before or after an existing one using cesdk.ui.insertOrderComponent(). The options support before, after, and position ('start', 'end', or a numeric index) placement.

// Insert a separator after the trim action in the clip menu
cesdk.ui.insertOrderComponent(
  {
    in: 'ly.img.video.clip.menu',
    after: 'ly.img.video.clip.menu.trim',
    when: { clipType: 'clip' }
  },
  'ly.img.separator'
);

Here we add a separator after the trim action, visually grouping trim with the actions above it and separating it from the actions below.

Adding Custom Actions#

We register a custom action using the ly.img.video.clip.menu.action component ID. Pass a ClipContextMenuCustomAction object with key, label, onClick, and optionally icon and isDisabled.

// Add a custom "Export Clip" action to the background clip menu
cesdk.ui.insertOrderComponent(
  {
    in: 'ly.img.video.clip.menu',
    before: 'ly.img.video.clip.menu.delete',
    when: { clipType: 'clip' }
  },
  {
    id: 'ly.img.video.clip.menu.action',
    key: 'export-clip',
    label: 'Export Clip',
    icon: '@imgly/Download',
    onClick: () => {
      console.log('Export Clip action triggered');
    }
  }
);

The key must be unique across all custom actions in the same menu. The onClick handler runs when the user selects the action. You can use any icon from the @imgly/icons package.

The ClipContextMenuCustomAction interface:

interface ClipContextMenuCustomAction {
  id: 'ly.img.video.clip.menu.action';
  key: string;
  onClick: () => void | Promise<void>;
  label: string;
  icon?: string;
  isDisabled?: boolean;
}

Updating Existing Actions#

We modify properties of an existing component using cesdk.ui.updateOrderComponent(). The update can be a partial object or an updater function.

// Disable the custom export action conditionally
cesdk.ui.updateOrderComponent(
  {
    in: 'ly.img.video.clip.menu',
    match: { id: 'ly.img.video.clip.menu.action', key: 'export-clip' },
    when: { clipType: 'clip' }
  },
  { isDisabled: false }
);

Use match with both id and key to target a specific custom action. You can update any property including label, icon, isDisabled, and onClick.

Clip-Type-Specific Customization#

Each of the three clip types ('clip', 'overlay', 'caption') has its own independent order. Changes to one do not affect the others. Use the when: { clipType } option on every operation to target a specific clip type. Omitting it defaults to 'clip'.

This independence lets you tailor each menu to its context. For example, overlays need layering controls while captions need merge actions — and you can customize each without worrying about side effects.

Troubleshooting#

Action not appearing: Verify the component ID is included in the order for the correct clip type. Use getComponentOrder to inspect the current order.
Custom action not clickable: Ensure isDisabled is not set to true and onClick is a valid function.
Changes affecting wrong clip type: Always pass when: { clipType } to target the intended clip type. Without it, operations default to 'clip'.
Separator not showing: Separators are only rendered between visible actions. If adjacent actions are hidden, the separator may not appear.

Default Menu Actions#