Unsplash 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-unsplash-asset-source-ts-web.git
cp -r starterkit-unsplash-asset-source-ts-web/app/imgly ./app/imgly
rm -rf starterkit-unsplash-asset-source-ts-web

git clone https://github.com/imgly/starterkit-unsplash-asset-source-ts-web.git
cp -r starterkit-unsplash-asset-source-ts-web/app/imgly ./app/imgly
rm -rf starterkit-unsplash-asset-source-ts-web

npx degit imgly/starterkit-unsplash-asset-source-ts-web/app/imgly ./app/imgly

npx degit imgly/starterkit-unsplash-asset-source-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 unsplash-js

npm install unsplash-js

pnpm add unsplash-js

pnpm add unsplash-js

yarn add unsplash-js

yarn add unsplash-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.73.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.73.0/imgly-assets.zip
unzip imgly-assets.zip -d public/
rm imgly-assets.zip

'use client';

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

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

import UnsplashEditor from './components/UnsplashEditor';

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

'use client';

import dynamic from 'next/dynamic';

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

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

cd your-project

cd your-project

git clone https://github.com/imgly/starterkit-unsplash-asset-source-ts-web.git
cp -r starterkit-unsplash-asset-source-ts-web/app/imgly ./app/imgly
rm -rf starterkit-unsplash-asset-source-ts-web

git clone https://github.com/imgly/starterkit-unsplash-asset-source-ts-web.git
cp -r starterkit-unsplash-asset-source-ts-web/app/imgly ./app/imgly
rm -rf starterkit-unsplash-asset-source-ts-web

npx degit imgly/starterkit-unsplash-asset-source-ts-web/app/imgly ./app/imgly

npx degit imgly/starterkit-unsplash-asset-source-ts-web/app/imgly ./app/imgly

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

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 unsplash-js

npm install unsplash-js

pnpm add unsplash-js

pnpm add unsplash-js

yarn add unsplash-js

yarn add unsplash-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.73.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.73.0/imgly-assets.zip
unzip imgly-assets.zip -d public/
rm imgly-assets.zip

'use client';

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

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

import UnsplashEditor from './components/UnsplashEditor';

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

'use client';

import dynamic from 'next/dynamic';

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

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

Set Up a Scene#

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

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

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

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

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

The createDesignScene() method is ideal for design workflows, as it creates a blank canvas ready for content.

Customize Assets#

The Unsplash Editor uses asset source plugins to provide built-in libraries for templates, 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,
  EffectsAssetSource,
  // ...
} 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());
await cesdk.addPlugin(new EffectsAssetSource());
// ...

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 design
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('design', blobs[0], 'design.png');

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

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

Unsplash Integration#

The Unsplash Editor replaces the default image library with Unsplash’s extensive collection of free photos.

How It Works#

The integration uses the official unsplash-js client to fetch images from Unsplash. A custom asset source translates Unsplash API responses to CE.SDK’s asset format.

// Add Unsplash image library integration
// Requires: npm install unsplash-js
// Configure: Pass unsplashApiUrl option or set VITE_UNSPLASH_API_URL env var
await cesdk.addPlugin(new UnsplashAssetSourcePlugin({
  apiUrl: options.unsplashApiUrl
}));

Search and Browse#

Users can search Unsplash’s library or browse popular images:

• Search: Type keywords to find relevant photos
• Popular: Browse trending images when no search query is entered
• Pagination: Automatically loads more results as users scroll

Attribution#

Unsplash requires photographer attribution for all images. The integration automatically includes:

• Photographer name: Displayed with each image
• Profile link: Links to the photographer’s Unsplash profile
• UTM tracking: Proper referral tracking per Unsplash guidelines

Set Up Unsplash Proxy#

For production use, you must proxy Unsplash API requests through your server. This keeps your API key secure and prevents exposure in client-side code.

Why a Proxy?#

• Security: API keys should never be in frontend code
• Rate limiting: Control and monitor API usage
• Compliance: Required by Unsplash API guidelines

Proxy Implementation#

Create a proxy endpoint that adds your API key. The starter kit includes a complete example at api/unsplash-proxy-example.ts:

// Next.js API Route
import { NextRequest, NextResponse } from 'next/server';

export async function GET(request: NextRequest) {
  const apiKey = process.env.UNSPLASH_ACCESS_KEY;
  const { searchParams } = new URL(request.url);

  const response = await fetch(`https://api.unsplash.com/photos?${searchParams}`, {
    headers: {
      Authorization: `Client-ID ${apiKey}`
    }
  });

  const data = await response.json();
  return NextResponse.json(data);
}

Configure the Proxy URL#

Set the environment variable to point to your proxy:

NEXT_PUBLIC_UNSPLASH_API_URL=https://your-domain.com/api/unsplash

Then pass it to the init function:

await initUnsplashEditor(cesdk, {
  unsplashApiUrl: process.env.NEXT_PUBLIC_UNSPLASH_API_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: {
    'libraries.unsplash.label': 'Unsplash',
    'actions.export.image': 'Download Design',
    'common.cancel': 'Cancel',
    'common.apply': 'Apply'
  }
});

// Add a new language
cesdk.i18n.setTranslations({
  de: {
    'libraries.unsplash.label': 'Unsplash Fotos',
    'actions.export.image': 'Design 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 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.

Print Ready PDF#

Export print-ready PDF/X-3 files with CMYK color profiles for professional printing workflows.

import PrintReadyPDFPlugin from '@imgly/plugin-print-ready-pdf';

// Add print-ready PDF export capability
await cesdk.addPlugin(PrintReadyPDFPlugin());

See Print Ready PDF 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.

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 Unsplash Editor combines professional design tools with free stock photography.

Unsplash Integration

Search and use millions of free high-quality photos with automatic attribution handling.

Background Removal

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

Professional Filters

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

Text & Typography

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

Multi-Page Documents

Create presentations, brochures, and multi-page designs.

Export Options

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

Troubleshooting#

Unsplash images don’t load#

• Check proxy URL: Verify you’ve configured the Unsplash API proxy URL correctly
• Check console errors: Look for network errors or CORS issues
• Test proxy directly: Ensure your proxy server is running and accessible

”Unsplash API URL not configured” warning#

• Set environment variable: Set NEXT_PUBLIC_UNSPLASH_API_URL in your .env.local file
• Pass to init function: Pass unsplashApiUrl to initUnsplashEditor()
• For development: The demo proxy is used automatically if no URL is provided

Rate limiting errors#

• Check Unsplash rate limits: Free tier allows 50 requests per hour
• Monitor X-Ratelimit-Remaining header: Your proxy should forward these headers
• Upgrade to production: Apply for production access at unsplash.com/developers for higher limits

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

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#

• Custom Asset Sources – Learn how asset sources work
• Theming – Customize colors and appearance
• Localization – Add translations
• Actions – Build custom export workflows