Configuration

Configure the editor engine, canvas dimensions, zoom behavior, and other settings. This page covers the full EditorEngineConfig interface, built-in constants, and canvas presets.

EditorEngineConfig

The configuration object passed when creating a new EditorEngine instance.

EditorEngineConfigtypescript
interface EditorEngineConfig {
  canvasElement: HTMLCanvasElement;  // Required: the canvas DOM element
  width?: number;                    // Canvas width in pixels (default: 1080)
  height?: number;                   // Canvas height in pixels (default: 1080)
  backgroundColor?: string;          // Canvas background color (default: '#ffffff')
}

// Create an engine with custom dimensions
const canvas = document.createElement('canvas');
const engine = new EditorEngine({
  canvasElement: canvas,
  width: 1920,
  height: 1080,
  backgroundColor: '#f0f0f0',
});

Config Properties

NameTypeDefaultDescription
canvasElement*HTMLCanvasElementThe HTML canvas element to render on
widthnumber1080Canvas width in pixels
heightnumber1080Canvas height in pixels
backgroundColorstring'#ffffff'Canvas background color

Constants

Built-in constants that control editor behavior. These are not configurable at runtime but are useful to know when building integrations.

Built-in constantstypescript
// Zoom limits
const ZOOM_MIN = 0.1;       // 10% minimum zoom
const ZOOM_MAX = 5.0;       // 500% maximum zoom

// History
const MAX_HISTORY_SIZE = 50; // Maximum undo steps

// Export defaults
const EXPORT_QUALITY = 1;    // Default export quality (0-1)
const EXPORT_MULTIPLIER = 1; // Default resolution multiplier

// Canvas presets (see full list below)
const CANVAS_PRESETS = [
  { name: 'Instagram Post',    width: 1080, height: 1080 },
  { name: 'Instagram Story',   width: 1080, height: 1920 },
  { name: 'Facebook Post',     width: 1200, height: 628  },
  { name: 'Facebook Cover',    width: 820,  height: 312  },
  { name: 'Twitter Post',      width: 1200, height: 675  },
  { name: 'Twitter Header',    width: 1500, height: 500  },
  { name: 'YouTube Thumbnail', width: 1280, height: 720  },
  { name: 'LinkedIn Post',     width: 1200, height: 627  },
  { name: 'Pinterest Pin',     width: 1000, height: 1500 },
  { name: 'Presentation',      width: 1920, height: 1080 },
  { name: 'A4 Portrait',       width: 2480, height: 3508 },
  { name: 'A4 Landscape',      width: 3508, height: 2480 },
  { name: 'Business Card',     width: 1050, height: 600  },
  { name: 'Custom',            width: 1080, height: 1080 },
];

Constants Reference

NameTypeDefaultDescription
ZOOM_MINnumber0.1Minimum zoom level (10%)
ZOOM_MAXnumber5.0Maximum zoom level (500%)
MAX_HISTORY_SIZEnumber50Maximum number of undo steps
EXPORT_QUALITYnumber1Default export quality for lossy formats
EXPORT_MULTIPLIERnumber1Default resolution multiplier for exports

Canvas Presets

14 built-in canvas size presets covering common social media, print, and presentation dimensions.

Using canvas presetstypescript
import { CANVAS_PRESETS } from '@design-on-web/core';

// List all presets
CANVAS_PRESETS.forEach(preset => {
  console.log(`${preset.name}: ${preset.width}x${preset.height}`);
});

// Apply a preset
const preset = CANVAS_PRESETS.find(p => p.name === 'Instagram Story');
if (preset) {
  engine.setCanvasSize(preset.width, preset.height);
}

All Canvas Presets

NameTypeDefaultDescription
Instagram Post1080 x 1080Square format for Instagram feed posts
Instagram Story1080 x 1920Vertical format for Instagram/Facebook stories
Facebook Post1200 x 628Landscape format for Facebook feed posts
Facebook Cover820 x 312Facebook page cover photo
Twitter Post1200 x 675Twitter/X feed post image
Twitter Header1500 x 500Twitter/X profile header
YouTube Thumbnail1280 x 720YouTube video thumbnail (16:9)
LinkedIn Post1200 x 627LinkedIn feed post image
Pinterest Pin1000 x 1500Tall format for Pinterest pins
Presentation1920 x 1080Standard 16:9 presentation slide
A4 Portrait2480 x 3508A4 paper at 300 DPI (portrait)
A4 Landscape3508 x 2480A4 paper at 300 DPI (landscape)
Business Card1050 x 600Standard business card dimensions
Custom1080 x 1080Custom size (user-defined)

Runtime Configuration

Some settings can be changed after the engine is created.

Runtime configurationtypescript
// Change canvas dimensions at runtime
engine.setCanvasSize(1920, 1080);

// Change background color
engine.setBackgroundColor('#000000');

// Get current dimensions
const { width, height } = engine.getCanvasSize();

// Set zoom level
engine.setZoom(1.5);    // 150%
engine.zoomToFit();     // Fit canvas in viewport
engine.resetZoom();     // Reset to 100%

// Get current zoom
const zoom = engine.getZoom();

Runtime Methods

NameTypeDefaultDescription
setCanvasSize(w, h)voidChange canvas dimensions
setBackgroundColor(color)voidChange canvas background color
getCanvasSize(){ width, height }Get current canvas dimensions
setZoom(level)voidSet zoom level (0.1 to 5.0)
getZoom()numberGet current zoom level
zoomToFit()voidZoom to fit the canvas in the viewport
resetZoom()voidReset zoom to 100%
💡
Canvas size vs viewport
The canvas size defines the design dimensions (what gets exported). The viewport is the visible area in the browser. Zoom controls how the canvas fits within the viewport.

Branding

Customize the editor's visual identity with the branding configuration. This allows you to replace the default logo, set a custom title, and control the "Powered by" footer visibility.

BrandingConfig interfacetypescript
interface BrandingConfig {
  logo?: string;       // URL to custom logo image
  title?: string;      // Text shown next to logo in toolbar
  poweredBy?: boolean;  // Show "Powered by Design on Web" footer (default: true)
}
Usage in Reacttsx
import { DesignEditor } from '@design-on-web/react';

function App() {
  return (
    <DesignEditor
      branding={{
        logo: "/my-logo.svg",
        title: "My Design Tool",
        poweredBy: false,
      }}
    />
  );
}

Branding Properties

NameTypeDefaultDescription
logostringURL to a custom logo image displayed in the toolbar. Supports any image format (SVG recommended for crisp rendering at any size).
titlestringText shown next to the logo in the toolbar. If omitted, no title text is displayed.
poweredBybooleantrueControls visibility of the "Powered by Design on Web" footer. Set to false to hide it (e.g., for white-label deployments).
ℹ️
White-label support
Combine logo, title, and poweredBy: false for a fully white-labeled editor that matches your brand. CSS custom properties (--dow-*) can further customize colors and fonts.

Full Setup Example

A complete initialization example with config, plugins, locale, and design loading.

Complete setuptypescript
import { EditorEngine } from '@design-on-web/core';
import { EditorContext, EditorShell } from '@design-on-web/ui';
import { SvgExportPlugin } from '@design-on-web/export-svg';
import { PdfExportPlugin } from '@design-on-web/export-pdf';
import { PsdExportPlugin } from '@design-on-web/export-psd';
import { I18nManager } from '@design-on-web/shared';

// Import styles
import '@design-on-web/ui/themes/variables.css';
import '@design-on-web/ui/themes/light.css';
import '@design-on-web/ui/components/EditorShell.css';

async function initEditor() {
  const canvas = document.createElement('canvas');

  // 1. Create engine with config
  const engine = new EditorEngine({
    canvasElement: canvas,
    width: 1080,
    height: 1080,
    backgroundColor: '#ffffff',
  });

  // 2. Register plugins
  await engine.registerPlugin(SvgExportPlugin);
  await engine.registerPlugin(PdfExportPlugin);
  await engine.registerPlugin(PsdExportPlugin);

  // 3. Set locale
  I18nManager.instance.setLocale('en');

  // 4. Load saved design (optional)
  const savedJson = localStorage.getItem('my-design');
  if (savedJson) {
    await engine.loadJSON(savedJson);
  }

  return engine;
}
ℹ️
Initialization order
Always create the engine first, then register plugins, then set locale, and finally load any saved designs. Plugins must be registered before loading designs that use plugin-specific data.