FAQ & Troubleshooting

Quick answers and solutions to the most common questions and issues.

General Questions

What is Imigi?

Imigi is a customizable web-based image editor library built with React and Fabric.js. It provides professional-grade image editing tools that can be embedded in any web application.

What browsers are supported?

Chrome 80+, Firefox 78+, Safari 14+, Edge 80+. Imigi requires modern JavaScript features and WebGL support.

Does Imigi work on mobile devices?

Yes, Imigi is responsive and supports touch interactions. Use forceOverlayModeOnMobile: true for the best mobile experience.

What image formats are supported?

Import: PNG, JPEG, WebP, SVG, and GIF (first frame only). Export: PNG, JPEG, JSON (state), and SVG.

Does Imigi work with TypeScript?

Yes, Imigi ships with full TypeScript type definitions for type-safe development and IDE autocompletion.

Can I use Imigi without a build tool?

Yes, use the UMD build with a <script> tag. No bundler required. See Quick Start (UMD).

Installation Issues

NPM Install Fails

Problem: npm install imigi fails with dependency errors.

Solutions:

1. Clear npm cache:
   TerminalCopy

   npm cache clean --force
   rm -rf node_modules package-lock.json
   npm install

2. Check Node version (requires Node 16+):
   TerminalCopy

   node --version

3. Try with legacy peer deps:
   TerminalCopy

   npm install imigi --legacy-peer-deps

TypeScript Errors

Problem: TypeScript compilation errors after installing.

Solutions:

1. Ensure TypeScript 5.x: npm install typescript@latest --save-dev
2. Update tsconfig.json:
   tsconfig.jsonCopy

   {
     "compilerOptions": {
       "moduleResolution": "bundler",
       "esModuleInterop": true
     }
   }

3. Install missing types: npm install @types/react @types/react-dom --save-dev

Display Issues

Editor Not Visible

Problem: Container element exists but editor doesn't appear.

Solutions:

1. Ensure container has dimensions:
   CSSCopy

   #editor-container {
     width: 100%;
     height: 600px;
     min-height: 400px;
   }

2. Wait for DOM ready:
   JavaScriptCopy

   document.addEventListener('DOMContentLoaded', () => {
     Imigi.init({ selector: '#editor' });
   });

3. Use a DOM element directly: { selector: document.getElementById('editor') }

Canvas is Black or Blank

Problem: Editor loads but canvas is black or empty.

Solutions:

1. Check image path — use an absolute path or full URL
2. Enable CORS for external images: { crossOrigin: true }
3. Check browser console for errors

Incorrect Sizing

Problem: Editor doesn't fit container properly.

Solutions:

1. For percentage heights, ensure all parent elements have height:
   CSSCopy

   html, body, #app {
     height: 100%;
     margin: 0;
   }

2. Use viewport units: width: 100vw; height: 100vh;

Blurry Canvas

Problem: Image/canvas appears blurry.

Solutions:

• Use high-resolution source images — avoid scaling up small images
• Reset zoom level: imigi.tools.zoom.set(1);
• Imigi handles devicePixelRatio automatically. If issues persist, check CSS: canvas { image-rendering: -webkit-optimize-contrast; }

Image Loading Issues

CORS Errors

Problem: "Access to image has been blocked by CORS policy"

Solutions:

1. Enable crossOrigin in config:
   JavaScriptCopy

   Imigi.init({
     crossOrigin: true,
     image: 'https://external-domain.com/image.jpg',
   });

2. Configure the image server to send CORS headers: Access-Control-Allow-Origin: *
3. Use a proxy for external images:
   JavaScriptCopy

   { image: '/api/proxy-image?url=' + encodeURIComponent(externalUrl) }

Large Image Fails

Problem: Very large images cause browser to freeze or crash.

Solutions:

1. Resize before loading:
   JavaScriptCopy

   async function resizeBeforeLoad(file, maxSize = 4000) {
     const img = await createImageBitmap(file);
     if (img.width <= maxSize && img.height <= maxSize) return file;
   
     const scale = maxSize / Math.max(img.width, img.height);
     const canvas = document.createElement('canvas');
     canvas.width = img.width * scale;
     canvas.height = img.height * scale;
     canvas.getContext('2d').drawImage(img, 0, 0, canvas.width, canvas.height);
   
     return new Promise(resolve => {
       canvas.toBlob(resolve, 'image/jpeg', 0.9);
     });
   }

2. Reduce textureSize: { textureSize: 2048 }
3. Add file size limits: tools.import.maxFileSize: 10 * 1024 * 1024

Performance Issues

Slow Filter Application

Problem: Filters take too long to apply.

• Reduce textureSize to 2048 (default is 4096)
• Work with smaller images when possible

Laggy Object Manipulation

Problem: Moving/resizing objects is slow.

• Reduce number of objects on canvas
• Use simpler stickers (smaller file sizes)
• Disable object caching temporarily:
  JavaScriptCopy

  imigi.fabric.getObjects().forEach(obj => {
    obj.objectCaching = false;
  });

Memory Issues

Problem: Browser runs out of memory.

• Clear history periodically: imigi.tools.history.clear();
• Remove unused objects: imigi.tools.objects.delete();
• Use smaller images and a lower textureSize
• Close and reopen editor for a fresh state

Export Issues

Export is Blank

Problem: Exported image is blank or transparent.

• Ensure there's content on the canvas
• JPEG doesn't support transparency — the background will be black. Use PNG or add a background fill:
  JavaScriptCopy

  // PNG supports transparency
  imigi.tools.export.save('image', 'png', 1);
  
  // Or add a white background first
  imigi.tools.fill.apply({ mode: 'color', color: '#ffffff' });

Export Quality is Low

Problem: Exported image looks worse than canvas.

• Increase quality: imigi.tools.export.save('image', 'png', 1);
• Use PNG for graphics/text, JPEG for photos
• Export at higher resolution:
  JavaScriptCopy

  const dataUrl = imigi.fabric.toDataURL({
    format: 'png',
    multiplier: 2, // 2x resolution
  });

onSave Not Called

Problem: The onSave callback isn't triggered.

• Make sure you're using the Save button or calling imigi.tools.export.save();
• If saveUrl is configured, data goes to the server instead of onSave. Remove saveUrl to use the callback.
• Verify the callback is defined in the config

Mobile Issues

Touch Not Working

Problem: Touch interactions don't work on mobile.

1. Ensure viewport meta tag:
   HTMLCopy

   <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no">

2. Prevent page scrolling while editing:
   CSSCopy

   body.editor-open {
     overflow: hidden;
     position: fixed;
     width: 100%;
   }

Pinch Zoom Affects Whole Page

Problem: Pinch zoom affects the page instead of the canvas.

• Add to viewport meta: user-scalable=no, maximum-scale=1.0
• CSS prevention: .imigi-root { touch-action: manipulation; }

Keyboard Covers Input

Problem: On-screen keyboard covers text input fields.

• Use overlay mode on mobile: ui.forceOverlayModeOnMobile: true
• Auto-scroll to input:
  JavaScriptCopy

  document.querySelector('.imigi-root').addEventListener('focusin', (e) => {
    if (e.target.tagName === 'INPUT' || e.target.tagName === 'TEXTAREA') {
      setTimeout(() => {
        e.target.scrollIntoView({ behavior: 'smooth', block: 'center' });
      }, 300);
    }
  });

Framework-Specific Issues

React: Multiple Instances / StrictMode

Problem: Editor initializes twice in development (React StrictMode).

Solution: Use a ref to prevent re-initialization:

const initialized = useRef(false);
const editorRef = useRef(null);

useEffect(() => {
  if (initialized.current) return;
  initialized.current = true;

  Imigi.init({ selector: '#editor' }).then(e => {
    editorRef.current = e;
  });
}, []);

Vue: Reactivity Issues

Problem: Vue reactivity interferes with Fabric.js objects.

Solution: Use shallowRef and markRaw:

import { shallowRef, markRaw } from 'vue';

const imigi = shallowRef(null);

onMounted(async () => {
  const editor = await Imigi.init({ selector: '#editor' });
  imigi.value = markRaw(editor);
});

Next.js: SSR Issues

Problem: "window is not defined" error.

Solution: Use dynamic import with no SSR:

import dynamic from 'next/dynamic';

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

Common Error Messages

Error	Cause	Solution
"Imigi required 'selector' option"	Missing or invalid selector	Provide a valid CSS selector or DOM element
"Cannot read property 'getContext' of null"	Canvas element not found	Ensure container exists in DOM; wait for DOM ready
"Tainted canvas may not be exported"	CORS issue with external image	Set { crossOrigin: true }
"Maximum call stack size exceeded"	Infinite loop from reactivity	Don't trigger state changes from state callbacks; use debouncing
"Out of memory"	Too many operations or large images	Reduce image sizes, clear history, use smaller textureSize

Debug Mode

Enable detailed logging to diagnose issues:

Imigi.init({
  selector: '#editor',
}).then(imigi => {
  // Expose to window for debugging
  window.imigi = imigi;
  window.fabric = imigi.fabric;

  // Log all canvas events
  imigi.fabric.on('*', (eventName, ...args) => {
    console.log('Event:', eventName, args);
  });
});

Getting Help

If you can't find a solution here:

1. Check the browser console for error messages
2. Create a minimal reproduction of the problem
3. Contact support with: browser & version, Imigi version, configuration used, steps to reproduce, and error messages or screenshots