Skip to main content
This guide helps you migrate your Canvas Editor implementation to the latest version. It covers breaking changes, new features, and upgrade steps based on the project’s changelog.

​
Current Version

Latest stable version: 0.9.128 (February 28, 2026)View the complete changelog at GitHub

​
Quick Migration

For most users, upgrading is straightforward: 
npm install @hufe921/canvas-editor@latest
Then review the breaking changes sections below for your current version.

​
Version 0.9.128 (Latest)

Release Date: February 28, 2026

​
New Features

Checkbox Mark Color

New checkMarkColor option for checkbox styling (#1367)
const options = {
  checkbox: {
    checkMarkColor: '#FFFFFF'
  }
}

Paste Image Override

Support for custom paste image handling (#1365)
editor.override.paste = (data) => {
  // Custom paste logic
  return customData
}

Home/End Keys

Implemented shortcuts for Home and End keys (#1361)

Paragraph Index

Added paragraph index to getRangeContext API (#1360)

​
Bug Fixes

  • Fixed global CSS affecting pasted text color (#1359)

​
Version 0.9.127

Release Date: February 18, 2026

​
Bug Fixes

  • Fixed format elements error in executeComputeElementListHeight API (#1356)
  • Fixed cursor movement to visible range boundary

​
Version 0.9.126

Release Date: February 12, 2026

​
New Features

1

Element Height Calculation

New APIs for computing element heights (#1213):
editor.command.executeComputeElementListHeight(elements)
editor.command.executeGetRemainingPageHeight()
2

List Style Inheritance

Configure list number style inheritance (#727):
const options = {
  list: {
    inheritStyle: true
  }
}

​
Bug Fixes

  • Adjusted image rowFlex when converting HTML to elements (#1354)
  • Fixed cursor positioning when clicking control postfix (#1353)
  • Restored titleId when splitting/merging titles (#921, #1337)

​
Version 0.9.125

Release Date: February 7, 2026

​
Major Features

Image Caption

Full support for image captions (#1326)
{
  type: ElementType.IMAGE,
  value: 'base64...',
  imgCaption: {
    value: 'Figure 1',
    color: '#666',
    size: 12
  }
}

Image Cropping

New executeSetImageCrop API (#1327)
editor.command.executeSetImageCrop({
  x: 10,
  y: 10,
  width: 200,
  height: 150
})

Label Element

New label element and events (#859)
{
  value: 'Label',
  labelId: 'label-1',
  label: {
    backgroundColor: '#FF0000'
  }
}

Hide Cursor API

Added executeHideCursor API (#1352)
editor.command.executeHideCursor()

​
Version 0.9.124

Release Date: January 31, 2026

​
New Features

  • Calculator support for number controls (#925)
  • Line spacing scales proportionally with font size (#1344)

​
Bug Fixes

  • Fixed checkbox not selectable on first click in form mode (#1347)
  • Fixed copy style before title line break (#1339)
  • Fixed cursor focus in table when resizing last row (#1349)
  • Fixed layout shift with descended characters (#1342)

​
Version 0.9.123

Release Date: January 16, 2026

​
New Features

  • Search within selected content (#1336)
  • Ensure selected option scrolls into view (#1340)
editor.command.executeSearch('query', {
  inSelection: true
})

​
Bug Fixes

  • Prevented cursor jump during search with selection (#1335)
  • Fixed search highlight position for radio controls (#1346)
  • Fixed tab element boundingBoxAscent value (#1341)

​
Version 0.9.122

Release Date: December 30, 2025

​
Major Features

White Space Markers

Draw whitespace markers (#1329)
const options = {
  whiteSpace: {
    visible: true,
    color: '#E0E0E0'
  }
}

Iframe Permissions

Configure iframe allow permissions (#1260)
{
  type: ElementType.BLOCK,
  block: {
    iframeBlock: {
      allow: 'camera; microphone'
    }
  }
}

​
Performance

  • Reduced graffiti points for better drawing performance
  • Optimized graffiti drawing algorithm

​
Version 0.9.121

Release Date: December 19, 2025

​
Major Features: Graffiti Mode

New graffiti/drawing mode (#992): 
import { EditorMode } from '@hufe921/canvas-editor'

const options = {
  mode: EditorMode.GRAFFITI,
  graffiti: {
    lineWidth: 2,
    strokeStyle: '#000000'
  }
}

​
Bug Fixes

  • Fixed eventbus clearing when destroying editor
  • Fixed compute position boundary errors
  • Fixed graffiti mode boundary errors
  • Restricted allowed characters in number control (#1319)

​
Version 0.9.120

Release Date: November 28, 2025

​
New Features

1

Regex Search

Search with regular expressions (#1308)
editor.command.executeSearch(/\d{3}-\d{4}/, {
  isRegex: true
})
2

Case-Insensitive Search

Ignore case option (#1316)
editor.command.executeSearch('query', {
  ignoreCase: true
})
3

Background in Print Mode

Disable background in print mode (#1314)
const options = {
  modeRule: {
    [EditorMode.PRINT]: {
      backgroundDisabled: true
    }
  }
}

​
Breaking Changes by Version

Review these breaking changes if upgrading from older versions.

​
0.9.118 → 0.9.120

Clipboard operations are now async (#1276)Before:
editor.command.executeCopy()
After:
await editor.command.executeCopy()

​
0.9.110 → 0.9.115

New modeRule configuration structure (#1132)Migration:
// Old approach: individual flags
const options = {
  imagePreviewerDisabled: true
}

// New approach: mode-specific rules
const options = {
  modeRule: {
    [EditorMode.PRINT]: {
      imagePreviewerDisabled: true,
      backgroundDisabled: false
    },
    [EditorMode.READONLY]: {
      imagePreviewerDisabled: false
    }
  }
}

​
0.9.100 → 0.9.105

Batch control property updates (#1037)Before:
// Update individual properties
editor.command.executeSetControlValue({ ... })
editor.command.executeSetControlExtension({ ... })
After:
// Batch update
editor.command.executeSetControlProperties({
  conceptId: 'field-1',
  properties: {
    placeholder: 'New placeholder',
    minWidth: 200,
    disabled: false
  }
})

​
0.9.95 → 0.9.97

New area element feature (#216)Areas allow creating editable regions within documents:
{
  value: '\n',
  type: ElementType.AREA,
  areaId: 'area-1',
  area: {
    mode: AreaMode.EDIT,
    backgroundColor: '#F5F5F5'
  },
  valueList: [
    { value: 'Area content' }
  ]
}

​
Migration Checklist

1

Update Package

npm install @hufe921/canvas-editor@latest
2

Update Imports

Check if any new enums or types are needed:
import Editor, {
  EditorMode,
  ElementType,
  ControlType,
  // Add new imports as needed
  WatermarkType,
  AreaMode
} from '@hufe921/canvas-editor'
3

Update Configuration

Review and update your editor options:
const options = {
  // Add new options
  modeRule: { ... },
  graffiti: { ... },
  whiteSpace: { ... }
}
4

Update API Calls

Replace deprecated methods:
// Check for async operations
await editor.command.executeCopy()

// Use new batch APIs
editor.command.executeSetControlProperties({ ... })
5

Test Thoroughly

  • Test all editor modes (edit, readonly, form, print)
  • Verify data loading and saving
  • Check custom integrations
  • Test on different browsers

​
Common Issues and Solutions

​
Issue: AsyncClipboard Errors

Problem: Clipboard operations fail in older browsersSolution: Update to version 0.9.118+ which made clipboard operations async:
try {
  await editor.command.executeCopy()
} catch (error) {
  console.error('Clipboard not available:', error)
  // Fallback logic
}

​
Issue: Control Value Not Updating

Problem: Control values don’t update after settingSolution: Use the isSubmitHistory option:
editor.command.executeSetControlValue({
  conceptId: 'field-1',
  value: 'New value',
  isSubmitHistory: true
})

​
Issue: Style Inheritance in Lists

Problem: List numbers don’t inherit text styleSolution: Enable style inheritance (v0.9.126+):
const options = {
  list: {
    inheritStyle: true
  }
}

​
Version Compatibility

Canvas Editor maintains backward compatibility for document data. Documents created with older versions can be loaded in newer versions, but some features may not be available until the data is re-saved.

​
Data Migration

When loading old documents: 
function migrateDocument(oldData: IEditorData): IEditorData {
  // The editor automatically handles most migrations
  // But you may want to add new features:
  
  const newData = { ...oldData }
  
  // Example: Add image captions to existing images
  newData.main = newData.main.map(element => {
    if (element.type === ElementType.IMAGE && !element.imgCaption) {
      return {
        ...element,
        imgCaption: {
          value: 'Untitled',
          color: '#666666'
        }
      }
    }
    return element
  })
  
  return newData
}

​
Future-Proofing

Store Version

Always save the editor version with documents:
const result = editor.command.getResult()
saveDocument({
  version: result.version,
  data: result.data
})

Feature Detection

Check for feature availability:
if (editor.command.executeHideCursor) {
  editor.command.executeHideCursor()
}

Gradual Migration

Migrate features incrementally rather than all at once.

Test Environments

Always test migrations in a staging environment first.

​
Getting Help

GitHub Issues

Report bugs or request features

Changelog

View complete version history

Documentation

Browse the complete documentation

Examples

See migration examples in action

​
Next Steps

Configuration

Review configuration options

Data Structure

Understand data format changes

API Reference

Explore new API methods

Examples

See new features in action

Build docs developers (and LLMs) love

Get started for freeTalk to us