Search
Loading...
Skip to content

Force Crop

The applyForceCrop API allows you to programmatically apply a crop preset to a specific design block. This is useful in scenarios where you want to enforce a particular format (e.g., fixed aspect ratio) and define how the editor should respond after the preset is applied.

Overview#

You can use applyForceCrop to apply a predefined crop preset to a selected block (typically an image or other block that supports cropping). The API provides flexible behavior through the mode parameter, controlling whether the crop UI is shown and whether cropping is conditionally applied based on the block’s current dimensions.

This API is available on the UI namespace as cesdk.ui.applyForceCrop.

cesdk.ui.applyForceCrop(blockId: DesignBlock, {
  sourceId: string;
  presetId: string;
  mode: 'silent' | 'always' | 'ifNeeded';
}): Promise<void>;

Parameters#

NameTypeDescription
blockIdDesignBlockThe ID of the block you want to apply the crop to. Must support cropping.
sourceIdstringID of the asset source where the crop preset is defined.
presetIdstringID of the crop preset to apply.
mode"silent" | "always" | "ifNeeded"Defines how the UI should behave after applying the crop. See below.

Modes#

ModeBehavior
silentApplies the preset without opening the crop UI.
alwaysApplies the preset and always switches to crop mode in the UI.
ifNeededOnly applies the preset if the block’s current dimensions or aspect ratio differ from the preset. Switches to crop mode only if a change is made.

Usage Example#

const ui = cesdk.ui;
const engine = cesdk.engine;


const blockId = engine.block.findAllSelected()[0];


// Add a new custom preset
engine.asset.addAssetToSource('ly.img.crop.presets', {
  id: 'custom-preset',
  label: {
    en: 'Custom Preset',
    de: 'Custom Preset'
  },
  payload: {
    transformPreset: {
      type: 'FixedSize',
      width: 900,
      height: 900,
      designUnit: 'Pixel'
    }
  }
});


// Apply the preset to the selected block
await ui.applyForceCrop(blockId, {
  mode: 'ifNeeded',
  presetId: 'custom-preset',
  sourceId: 'ly.img.crop.presets'
});

You can also apply presets shipped with CE.SDK, such as:

await ui.applyForceCrop(blockId, {
  mode: 'ifNeeded',
  presetId: 'aspect-ratio-1-1',
  sourceId: 'ly.img.crop.presets'
});

Behavior Details#

  • applyForceCrop bypasses the usual user interaction required to apply crop presets manually.
  • When used in always or ifNeeded mode, the crop UI is automatically opened (if appropriate).
  • This function hides the dimension inputs from the crop panel for a cleaner editing experience.
  • Invalid presetId, sourceId, or mode values will result in console warning output.

See Also#