Photo Editor for Next.js

Prerequisites#

Before you begin, make sure you have the following:

• Node.js v20+ and npm installed locally – Download Node.js
• A supported browser – Chrome 114+, Edge 114+, Firefox 115+, Safari 15.6+
  See Browser Support for the full list.

npx create-next-app@latest your-project-name
cd your-project-name

npx create-next-app@latest your-project-name
cd your-project-name

pnpm create next-app your-project-name
cd your-project-name

pnpm create next-app your-project-name
cd your-project-name

yarn create next-app your-project-name
cd your-project-name

yarn create next-app your-project-name
cd your-project-name

git clone https://github.com/imgly/starterkit-photo-editor-ts-web.git
cp -r starterkit-photo-editor-ts-web/app/imgly ./app/imgly
rm -rf starterkit-photo-editor-ts-web

git clone https://github.com/imgly/starterkit-photo-editor-ts-web.git
cp -r starterkit-photo-editor-ts-web/app/imgly ./app/imgly
rm -rf starterkit-photo-editor-ts-web

npx degit imgly/starterkit-photo-editor-ts-web/app/imgly ./app/imgly

npx degit imgly/starterkit-photo-editor-ts-web/app/imgly ./app/imgly

npm install @cesdk/cesdk-js

npm install @cesdk/cesdk-js

pnpm add @cesdk/cesdk-js

pnpm add @cesdk/cesdk-js

yarn add @cesdk/cesdk-js

yarn add @cesdk/cesdk-js

npm install @imgly/background-removal onnxruntime-web

npm install @imgly/background-removal onnxruntime-web

pnpm add @imgly/background-removal onnxruntime-web

pnpm add @imgly/background-removal onnxruntime-web

yarn add @imgly/background-removal onnxruntime-web

yarn add @imgly/background-removal onnxruntime-web

curl -O https://cdn.img.ly/packages/imgly/cesdk-js/1.69.0/imgly-assets.zip
unzip imgly-assets.zip -d public/
rm imgly-assets.zip

curl -O https://cdn.img.ly/packages/imgly/cesdk-js/1.69.0/imgly-assets.zip
unzip imgly-assets.zip -d public/
rm imgly-assets.zip

'use client';

import { initPhotoEditor } from '../imgly';
import CreativeEditor from '@cesdk/cesdk-js/react';

export default function PhotoEditor() {
  return (
    <CreativeEditor
      config={{ baseURL: '/assets' }}
      init={initPhotoEditor}
      width="100vw"
      height="100vh"
    />
  );
}

import PhotoEditor from './components/PhotoEditor';

export default function Page() {
  return <PhotoEditor />;
}

'use client';

import dynamic from 'next/dynamic';

const PhotoEditor = dynamic(
  () => import('./components/PhotoEditor'),
  { ssr: false }
);

export default function Page() {
  return <PhotoEditor />;
}

// Get the currently selected image block
const selectedBlocks = cesdk.engine.block.findAllSelected();
const imageBlock = selectedBlocks[0];

// Apply a 1:1 square crop
await cesdk.ui.applyForceCrop(imageBlock, {
  sourceId: 'ly.img.crop.presets',
  presetId: 'ly.img.crop.presets.fixed-ratio.1_1',
  mode: 'ifNeeded'
});

cd your-project

cd your-project

git clone https://github.com/imgly/starterkit-photo-editor-ts-web.git
cp -r starterkit-photo-editor-ts-web/app/imgly ./app/imgly
rm -rf starterkit-photo-editor-ts-web

git clone https://github.com/imgly/starterkit-photo-editor-ts-web.git
cp -r starterkit-photo-editor-ts-web/app/imgly ./app/imgly
rm -rf starterkit-photo-editor-ts-web

npx degit imgly/starterkit-photo-editor-ts-web/app/imgly ./app/imgly

npx degit imgly/starterkit-photo-editor-ts-web/app/imgly ./app/imgly

imgly/
├── index.ts                  # Editor initialization function
├── config/
│   ├── plugin.ts             # Main configuration plugin
│   ├── actions.ts            # Export/import actions
│   ├── features.ts           # Feature toggles
│   ├── i18n.ts               # Translations
│   ├── settings.ts           # Engine settings
│   └── ui/                   # UI customization
│       ├── index.ts          # Combines UI customization exports
│       ├── canvas.ts         # Canvas configuration
│       ├── components.ts     # Custom component registration
│       ├── dock.ts           # Dock layout configuration
│       ├── inspectorBar.ts   # Inspector bar layout
│       ├── navigationBar.ts  # Navigation bar layout
│       └── panel.ts          # Panel configuration
└── plugins/
    └── background-removal.ts # Background removal plugin

npm install @cesdk/cesdk-js

npm install @cesdk/cesdk-js

pnpm add @cesdk/cesdk-js

pnpm add @cesdk/cesdk-js

yarn add @cesdk/cesdk-js

yarn add @cesdk/cesdk-js

npm install @imgly/background-removal onnxruntime-web

npm install @imgly/background-removal onnxruntime-web

pnpm add @imgly/background-removal onnxruntime-web

pnpm add @imgly/background-removal onnxruntime-web

yarn add @imgly/background-removal onnxruntime-web

yarn add @imgly/background-removal onnxruntime-web

curl -O https://cdn.img.ly/packages/imgly/cesdk-js/1.69.0/imgly-assets.zip
unzip imgly-assets.zip -d public/
rm imgly-assets.zip

curl -O https://cdn.img.ly/packages/imgly/cesdk-js/1.69.0/imgly-assets.zip
unzip imgly-assets.zip -d public/
rm imgly-assets.zip

'use client';

import { initPhotoEditor } from '@/imgly';
import CreativeEditor from '@cesdk/cesdk-js/react';

export default function PhotoEditor() {
  return (
    <CreativeEditor
      config={{
        baseURL: '/assets'
      }}
      init={initPhotoEditor}
      width="100vw"
      height="100vh"
    />
  );
}

import PhotoEditor from '../components/PhotoEditor';

export default function EditorPage() {
  return <PhotoEditor />;
}

'use client';

import dynamic from 'next/dynamic';

const PhotoEditor = dynamic(
  () => import('./components/PhotoEditor'),
  { ssr: false }
);

export default function PhotoEditorComponent() {
  return <PhotoEditor />;
}

// Get the currently selected image block
const selectedBlocks = cesdk.engine.block.findAllSelected();
const imageBlock = selectedBlocks[0];

// Apply a 1:1 square crop
await cesdk.ui.applyForceCrop(imageBlock, {
  sourceId: 'ly.img.crop.presets',
  presetId: 'ly.img.crop.presets.fixed-ratio.1_1',
  mode: 'ifNeeded'
});

Set Up a Scene#

CE.SDK offers multiple ways to load content into the editor. Choose the method that matches your use case:

// Load from an image URL - creates a new scene with the image
await cesdk.createFromImage('https://example.com/photo.jpg');

// Load from a template archive - restores a previously saved project
await cesdk.loadFromArchiveURL('https://example.com/template.zip');

// Create a blank canvas - starts with an empty design scene
await cesdk.actions.run('scene.create');

// Load from a scene file - restores a scene from JSON
await cesdk.loadFromURL('https://example.com/scene.json');

The createFromImage() method is ideal for photo editing workflows, as it automatically creates a scene sized to the image dimensions.

Customize Assets#

The Photo Editor uses asset source plugins to provide built-in libraries for filters, effects, stickers, shapes, and fonts. The starter kit includes a curated selection—customize what’s included based on your needs.

Asset sources are added via plugins in app/imgly/index.ts. Enable or disable individual sources:

import {
  FiltersAssetSource,
  StickerAssetSource,
  TextAssetSource,
  VectorShapeAssetSource,
  // ...
} from '@cesdk/cesdk-js/plugins';

// Add only the sources you need
await cesdk.addPlugin(new FiltersAssetSource());
await cesdk.addPlugin(new StickerAssetSource());
await cesdk.addPlugin(new TextAssetSource());
await cesdk.addPlugin(new VectorShapeAssetSource());
// ...

For production deployments, self-hosting assets is required—the IMG.LY CDN is intended for development only. See Serve Assets for downloading assets, configuring baseURL, and excluding unused sources to optimize load times.

Configure Actions#

Actions are functions that handle user interactions like exporting designs, saving scenes, and importing files. CE.SDK provides built-in actions that you can run directly or override with custom implementations.

Key built-in actions:

• exportDesign – Export the current design to PNG, JPEG, PDF, or other formats
• saveScene – Save the scene as a JSON string for later editing
• importScene – Import a previously saved scene (supports .scene and .cesdk formats)
• exportScene – Export the scene as a JSON file or .cesdk archive with all assets
• uploadFile – Handle file uploads with progress tracking

Use cesdk.actions.run() to execute any action:

// Run a built-in action
await cesdk.actions.run('exportDesign', { mimeType: 'image/png' });

Import from File Picker#

// Let users open images from their device
cesdk.actions.register('importImage', async () => {
  const blobURL = await cesdk.utils.loadFile({
    accept: 'image/*',
    returnType: 'objectURL'
  });
  await cesdk.createFromImage(blobURL);
});

Export and Save#

// Register export action that downloads the edited photo
cesdk.actions.register('exportDesign', async (exportOptions) => {
  const { blobs, options } = await cesdk.utils.export(exportOptions);
  await cesdk.utils.downloadFile(blobs[0], options.mimeType);
});

Upload to Your Backend#

// Override the built-in exportDesign action to send to your server
cesdk.actions.register('exportDesign', async (exportOptions) => {
  const { blobs } = await cesdk.utils.export(exportOptions);

  const formData = new FormData();
  formData.append('image', blobs[0], 'edited-photo.png');

  const response = await fetch('/api/upload', {
    method: 'POST',
    body: formData
  });

  const { url } = await response.json();
  console.log('Uploaded to:', url);
});

Customize (Optional)#

Theming#

CE.SDK supports light and dark themes out of the box, plus automatic system preference detection. Switch between themes programmatically:

// 'light' | 'dark' | 'system' | (() => 'light' | 'dark')
cesdk.ui.setTheme('dark');

See Theming for custom color schemes, CSS variables, and advanced styling options.

Localization#

Customize UI labels and add support for multiple languages. The i18n system supports translation keys for all UI elements:

// Override specific labels
cesdk.i18n.setTranslations({
  en: {
    'actions.export.image': 'Download Photo',
    'common.cancel': 'Cancel',
    'common.apply': 'Apply'
  }
});

// Add a new language
cesdk.i18n.setTranslations({
  de: {
    'actions.export.image': 'Foto herunterladen'
  }
});

// Set the active locale
cesdk.i18n.setLocale('de');

See Localization for supported languages, translation key reference, and right-to-left language support.

UI Layout#

Customize the editor interface by modifying the dock, inspector bar, navigation bar, and canvas menu. CE.SDK provides Order APIs to control which components appear and in what sequence.

// Get current navigation bar components
const navOrder = cesdk.ui.getNavigationBarOrder();

// Add a custom button to the navigation bar
cesdk.ui.insertNavigationBarOrderComponent(
  'ly.img.spacer',
  { id: 'my-custom-action' },
  'after'
);

// Rearrange dock items
cesdk.ui.setDockOrder([
  'ly.img.assetLibrary.dock',
  'ly.img.separator',
  'my-custom-dock-item'
]);

// Customize the inspector bar
cesdk.ui.setInspectorBarOrder([
  'ly.img.fill.inspectorBar',
  'ly.img.separator',
  'ly.img.filter.inspectorBar'
]);

The Order API methods follow a consistent pattern across all UI areas:

• get*Order() – Retrieve the current component order
• set*Order() – Replace the entire order
• insert*OrderComponent() – Add components relative to existing ones

See Dock, Inspector Bar, Navigation Bar, Canvas Menu, and Canvas for detailed layout customization options.

Custom Components#

Build custom UI components using the builder system and integrate them in the editor. Custom components receive reactive state updates and can interact with the engine API.

// Register a custom component
cesdk.ui.registerComponent('my-custom-button', ({ builder, engine }) => {
  const selectedBlocks = engine.block.findAllSelected();

  builder.Button('apply-effect', {
    label: 'Apply Effect',
    isDisabled: selectedBlocks.length === 0,
    onClick: () => {
      // Apply custom logic to selected blocks
    }
  });
});

// Add the component to the navigation bar
cesdk.ui.insertNavigationBarOrderComponent(
  'ly.img.spacer',
  'my-custom-button',
  'after'
);

Custom components automatically re-render when the engine state they depend on changes—no manual subscription management required.

See Register New Component for the complete builder API and component patterns.

Settings & Features#

Fine-tune editor behavior through settings and features.

Settings configure core engine behavior—rendering, input handling, and history management:

cesdk.engine.editor.setSettingBool('page/dimOutOfPageAreas', true);
cesdk.engine.editor.setSettingBool('mouse/enableZoomControl', true);
cesdk.engine.editor.setSettingBool('features/undoHistory', true);

Features toggle which editing tools and panels appear in the UI:

// Toggle editor features
cesdk.feature.enable('ly.img.crop', true);
cesdk.feature.enable('ly.img.filter', true);
cesdk.feature.enable('ly.img.adjustment', true);

See Settings and Features for the complete reference.

Explore Plugins#

CE.SDK has a rich plugin ecosystem that extends the editor with powerful capabilities. Plugins can add new features, integrate third-party services, or customize editor behavior.

Background Removal#

Add AI-powered background removal that runs entirely client-side. The background removal plugin processes images directly in the browser without sending data to external servers.

import BackgroundRemovalPlugin from '@imgly/plugin-background-removal';

// Add background removal capability
await cesdk.addPlugin(BackgroundRemovalPlugin());

See Background Removal for setup instructions and configuration options.

AI Integration#

Extend the editor with generative AI capabilities for text-to-image generation, image enhancement, and intelligent editing features. CE.SDK integrates with various AI providers.

import AIPlugin from '@imgly/plugin-ai-generation';

// Configure AI generation
await cesdk.addPlugin(AIPlugin({
  provider: 'your-ai-provider',
  apiKey: 'your-api-key'
}));

See AI Integration for provider setup and supported AI features.

Custom Asset Sources#

Connect external asset libraries like Unsplash, Getty Images, or your own content management system. Asset sources let users browse and insert content from any source.

import UnsplashAssetSource from '@imgly/plugin-unsplash';

// Add Unsplash integration
await cesdk.addPlugin(UnsplashAssetSource({
  accessKey: 'your-unsplash-access-key'
}));

See Custom Asset Sources for integration patterns.

Discover More Plugins#

Explore the full plugin ecosystem in the IMG.LY plugins repository. Available plugins include:

• Vectorizer – Convert raster images to vectors
• Design Presets – Pre-built design templates
• Social Media Templates – Platform-specific sizing
• And more – Check the repository for the latest additions

Key Capabilities#

The Photo Editor includes everything needed for professional image editing.

Transform Operations

Crop, rotate, resize, and flip images with precision controls and visual feedback.

Professional Filters

Apply color grading with LUT filters, duotone effects, and customizable image adjustments.

Background Removal

AI-powered background removal that runs entirely in the browser without server dependencies.

Text Overlays

Add styled text with comprehensive typography controls, fonts, and visual effects.

Asset Libraries

Access built-in collections of stickers, shapes, and graphics, plus import custom assets.

Export Options

Export to multiple formats including PNG, JPEG, and PDF with quality and size controls.

Troubleshooting#

Editor doesn’t load#

• Check the container element exists: Ensure your container element is in the DOM before calling create()
• Verify the baseURL: Assets must be accessible from the CDN or your self-hosted location
• Check console errors: Look for CORS or network errors in browser developer tools
• Ensure ‘use client’ directive: CE.SDK requires browser APIs and must run as a Client Component

Assets don’t appear#

• Check network requests: Open DevTools Network tab and look for failed requests to cdn.img.ly
• Self-host assets for production: See Serve Assets to host assets on your infrastructure

Export fails or produces blank images#

• Wait for content to load: Ensure images are fully loaded before exporting
• Check CORS on images: Remote images must allow cross-origin access

Watermark appears in production#

• Add your license key: Set the license property in your configuration
• Sign up for a trial: Get a free trial license at img.ly/forms/free-trial

Next Steps#

• Configuration – Complete list of initialization options
• Serve Assets – Self-host engine assets for production
• Actions – Build custom export and save workflows
• Theming – Customize colors and appearance
• Localization – Add translations and language support