exportToBlob
now automatically setsappState.exportBackground
totrue
if exporting toimage/jpeg
MIME type (to ensure that alpha channel is not compressed to black color).
-
Introduced primary colors to the app. The colors can be overriden. Check readme on how to do so.
-
Removed
getElementMap
util method. -
Changes to
exportToCanvas
util function:- Add
maxWidthOrHeight?: number
attribute. scale
returned fromgetDimensions()
is now optional (default to1
).
- Add
-
Image support.
NOTE: the unreleased API is highly unstable and may change significantly before the next stable release. As such it's largely undocumented at this point. You are encouraged to read through the PR description if you want to know more about the internals.
General notes:
- File data are encoded as DataURLs (base64) for portability reasons.
- added
getFiles()
to get currentBinaryFiles
(Record<FileId, BinaryFileData>
). It may contain files that aren't referenced by any element, so if you're persisting the files to a storage, you should compare them against stored elements.
Excalidraw app props:
- added
generateIdForFile(file: File)
optional prop so you can generate your own ids for added files. onChange(elements, appState, files)
prop callback is now passedBinaryFiles
as third argument.onPaste(data, event)
data prop should containdata.files
(BinaryFiles
) if the elements pasted are referencing new files.initialData
object now supports additionalfiles
(BinaryFiles
) attribute.
Other notes:
.excalidraw
files may now contain top-levelfiles
key in format ofRecord<FileId, BinaryFileData>
when exporting any (image) elements.- Changes were made to various export utilityies exported from the package so that they take
files
. For now, TypeScript should help you figure the changes out.
-
Export
isLinearElement
andgetNonDeletedElements
. -
Support
renderTopRightUI
in mobile UI. -
Export
THEME
constant from the package so host can use this when passing the theme.The
Appearance
type is now removed and renamed toTheme
soTheme
type needs to be used.
- Panning the canvas using
mousewheel-drag
andspace-drag
now prevents the browser from scrolling the container/page #4489. - Scope drag and drop events to Excalidraw container to prevent overriding host application drag and drop events.
-
Added an example to test and develop the package locally using
yarn start
-
Remove
file-loader
so font assets are not duplicated by webpack and use webpack asset modules for font generation #4380 -
We're now compiling to
es2017
target. Notably,async/await
is not compiled down to generators. #4341
-
Don't show save file to disk button in export dialog when
saveFileToDisk
passed asfalse
inUIOptions.canvasActions.export
. -
onPaste
prop should return false to prevent the native excalidraw paste action #3974.- Earlier the paste action was prevented when the prop
onPaste
returned true, but now it should return false to prevent the paste action. This was done to make it semantically more correct and intuitive.
- Earlier the paste action was prevented when the prop
- Enable jsx transform in webpack #4049
- Correct exportToBackend in README to onExportToBackend #3952
This section lists the updates made to the excalidraw library and will not affect the integration.
-
Improve freedraw shape #3984
-
Make color ARIA labels better #3871
-
Add origin trial tokens #3853
-
Re-order zoom buttons #3837
-
Add undo/redo buttons & tweak footer #3832
-
Resave to png/svg with metadata if you loaded your scene from a png/svg file #3645
-
Abstract and fix legacy fs #4032
-
Context menu positioning #4025
-
Added alert for bad encryption key #3998
-
OnPaste should return false to prevent paste action #3974
-
Help-icon now visible on Safari #3939
-
Permanent zoom mode #3931
-
Undo/redo buttons gap in Safari #3836
-
Prevent gradual canvas misalignment #3833
-
Color picker shortcuts not working when elements selected #3817
-
restore(data, localAppState, localElements)
andrestoreElements(elements, localElements)
now takelocalElements
argument which will be used to ensure existing elements' versions are used and incremented. This fixes an issue where importing the same file would resolve to elements with older versions, potentially causing issues when reconciling #3797.localElements
argument is mandatory (can benull
/undefined
) if using TypeScript.
-
Support
appState.exportEmbedScene
attribute inexportToSvg
which allows to embed the scene data #3777.- The attribute
metadata
is now removed asmetadata
was only used to embed scene data which is now supported with theappState.exportEmbedScene
attribute. exportToSvg
now resolves to a promise which resolves tosvg
of the exported drawing.
- The attribute
-
Expose
loadLibraryFromBlob
,loadFromBlob
, andgetFreeDrawSvgPath
#3764. -
Expose
FONT_FAMILY
so that consumer can use when passinginitialData.appState.currentItemFontFamily
#3710. -
Added prop
autoFocus
to focus the excalidraw component on page load when enabled, defaults to false #3691.Note: Earlier Excalidraw component was focussed by default on page load, you need to enable
autoFocus
prop to retain the same behaviour. -
Added prop
UIOptions.canvasActions.export.renderCustomUI
to support Custom UI rendering inside export dialog #3666. -
Added prop
UIOptions.canvasActions.saveAsImage
to show/hide the Save as image button in the canvas actions. Defauls totrue
hence the Save as Image button is rendered #3662. -
Export dialog can be customised with
UiOptions.canvasActions.export
#3658.Also,
UIOptions
is now memoized to avoid unnecessary rerenders.UIOptions.canvasActions.saveAsScene
is now renamed toUiOptions.canvasActions.export.saveFileToDisk
. Defaults totrue
hence the save file to disk button is rendered inside the export dialog.exportToBackend
is now renamed toUIOptions.canvasActions.export.exportToBackend
. If this prop is not passed, the shareable-link button will not be rendered, same as before.
- Use excalidraw Id in elements so every element has unique id #3696.
-
- Rename
UIOptions.canvasActions.saveScene
toUIOptions.canvasActions.saveToActiveFile
#3657. - Removed
shouldAddWatermark: boolean
attribute from options for export APIs #3639. - Removed
appState.shouldAddWatermark
so in case you were passingshouldAddWatermark
in initialData.AppState it will not work anymore.
- Rename
This section lists the updates made to the excalidraw library and will not affect the integration.
-
Switch to selection tool on library item insert #3773
-
Show active file name when saving to current file #3733
-
Add hint around text editing #3708
-
Change library icon to be more clear #3583
-
Pass current
theme
when installing libraries #3701 -
Update virgil font #3692
-
Support exporting json to excalidraw plus #3678
-
Save exportScale in AppState #3580
-
Add shortcuts for stroke and background color picker #3318
-
Exporting redesign #3613
-
Auto-position tooltip and suport overflowing container #3631
-
Auto release @excalidraw/excalidraw-next on every change #3614
-
Allow inner-drag-selecting with cmd/ctrl #3603
-
view mode cursor adjustments #3809.
-
Pass next release to updatePackageVersion & replace ## unreleased with new version #3806
-
Include deleted elements when passing to restore #3802
-
Import React before using jsx #3804
-
Ensure
s
andg
shortcuts work on no selection #3800 -
Keep binding for attached arrows after changing text #3754
-
Deselect elements on viewMode toggle #3741
-
Allow pointer events for disable zen mode button #3743
-
Use rgba instead of shorthand alpha #3688
-
Color pickers not opening on mobile #3676
-
On contextMenu, use selected element regardless of z-index #3668
-
SelectedGroupIds not being stored in history #3630
-
Overscroll on touch devices #3663
-
Small UI issues around image export dialog #3642
-
Normalize linear element points on restore #3633
-
Disable pointer-events on footer-center container #3629
- Improve arrow head sizing #3480
-
Add release script to update relevant files and commit for next release #3805
-
Add script to update changelog before a stable release #3784
-
Add script to update readme before stable release #3781
These section lists the updates which may affect your integration, so it is recommended to go through this when upgrading the version.
-
Support updating any
appState
properties inupdateScene
API. Earlier onlyappState.viewBackgroundColor
was supported, now any attribute can be updated with this API. -
Expose
serializeAsJSON
helper that we use when saving Excalidraw scene to a file #3538. -
Add support to render custom UI in the top right corner via
renderTopRightUI
prop #3539, #3572 .This also removes the GitHub icon, keeping it local to the https://excalidraw.com app.
-
The encryption shield icon is now removed from excalidraw package as it was specific to excalidraw app and is now rendered via
renderFooter
prop. In case you were hiding this icon earlier, you need not do that anymore #3577.Now
appState
is also passed torenderFooter
prop.
These section lists the updates made to the excalidraw library and will not affect the integration.
- Shortcut key for nerd stats #3552.
- Better rendering of curved rectangles #3562.
- Improved freedraw #3512.
- Add shortcut for dark mode #3543.
- Adds rounded icons, joins and caps.#3521.
- Exporting freedraw with color to svg #3565.
- Handle render errors #3557.
- Restore on paste or lib import #3558.
- Improve mobile user experience #3508.
- Prevent selecting
.visually-hidden
elements #3501.
- Reduce SVG export size by more than half by reducing precision to 2 decimal places #3567.
- Remove
backdrop-filter
to improve perf #3506
-
scrollToContent
API now supports passing just a single Excalidraw element, or none at all (which will default to current elements on the scene) #3482.- Renamed
setScrollToContent
toscrollToContent
.
- Renamed
-
Make library local to given excalidraw instance (previously, all instances on the same page shared one global library) #3451.
-
Added prop onLibraryChange which if supplied will be called when library is updated.
-
Added attribute
libraryItems
to prop initialData which can be used to load excalidraw with existing library items. -
Assign a unique id to the excalidraw component. The id can be accessed via
ref
.
- From now on the host application is responsible for persisting the library to LocalStorage (or elsewhere), and importing it on mount.
-
-
Bind the keyboard events to component and added a prop
handleKeyboardGlobally
which if set to true will bind the keyboard events to document #3430.- Earlier keyboard events were bind to document but now its bind to Excalidraw component by default. So you will need to set
handleKeyboardGlobally
to true if you want the previous behaviour (bind the keyboard events to document).
- Earlier keyboard events were bind to document but now its bind to Excalidraw component by default. So you will need to set
-
Recompute offsets on
scroll
of the nearest scrollable container #3408. This can be disabled by settingdetectScroll
tofalse
. -
Add
onPaste
prop to handle custom clipboard behaviours #3420.
-
Changing z-index of elements (sorting them below/above other elements) now updates their
version
andversionNonce
(only applies to the selected elements). This fix will allow you account for z-index changes if you're syncing just the elements that changed (and not the whole scene) #3483. -
Only handle cut/paste events inside excalidraw #3484.
-
Make history local to a given Excalidraw instance. This fixes a case where history was getting shared when you have multiple Excalidraw components on the same page #3481.
-
Use active Excalidraw component when editing text. This fixes a case where text editing was not working when you have multiple Excalidraw components on the same page #3478.
-
Fix library being pasted off-center #3462.
-
When switching theme, apply it only to the active Excalidraw component. This fixes a case where the theme was getting applied to the first Excalidraw component if you had multiple Excalidraw components on the same page #3446.
-
-
Removed exposing
getSyncableElements
helper which was specific to excalidraw app collab implementation #3471. If you happened to use it, you can easily reimplement it yourself using the newly exposed isInvisiblySmallElement helper:const getSyncableElements = (elements: readonly ExcalidrawElement[]) => elements.filter((el) => el.isDeleted || !isInvisiblySmallElement(el));
-
- Add vendor prefixes to css rules #3476.
- Renamed the following types in case you depend on them (via #3427):
DataState
→ExportedDataState
LibraryData
→ExportedLibraryData
-
Support tab-to-indent when editing text #3411.
-
App now breaks into mobile view using the component dimensions, not viewport dimensions. This fixes a case where the app would break sooner than necessary when the component's size is smaller than viewport #3414.
-
Add screenshots to manifest.json #3369.
-
Enable drop event on the whole component #3406.
-
Focus on last active element when dialog closes #3447.
-
Fix incorrectly caching png file handle #3407.
-
Fix popover position incorrect on Safari for non-zero offsets/scroll #3399.
- Add
UIOptions
prop to customisecanvas actions
which includes customisingbackground color picker
,clear canvas
,export
,load
,save
,save as
&theme toggle
#3364. Check the readme for more details. - Calculate
width/height
of canvas based on excalidraw component (".excalidraw" selector) & also resize and update offsets whenever the dimensions of excalidraw component gets updated #3379. You also don't need to add a resize handler anymore for excalidraw as its handled now in excalidraw itself.width/height
props have been removed. Instead now it takes100%
ofwidth
andheight
of the container so you need to make sure the container in which you are rendering Excalidraw has non zero dimensions (It should have non zero width and height so Excalidraw can match the dimensions of containing block)
- Calculate offsets when excalidraw container resizes using resize observer api #3374.
- Export types for the package so now it can be used with typescript #3337. The types are available at
@excalidraw/excalidraw/types
. - Add
renderCustomStats
prop to render extra stats on host, and exposesetToastMessage
API via refs which can be used to show toast with custom message #3360. - Support passing a CSRF token when importing libraries to prevent prompting before installation. The token is passed from https://libraries.excalidraw.com using the
token
URL key #3329. -
Use
location.hash
when importing libraries to fix installation issues. This will require host apps to add ahashchange
listener and call the newly exposedexcalidrawAPI.importLibrary(url)
API when applicable #3320. Check the readme for more details. - Append
location.pathname
tolibraryReturnUrl
default url #3325. - Support image elements #3424.
- Expose separate builds for dev and prod and support source maps in dev build #3330. Check the readme for more details.
- If you are using script tag to embed excalidraw then the name of the file will have to be updated to
excalidraw.production.min.js
instead ofexcalidraw.min.js
. If you want to use dev build you can useexcalidraw.development.js
- If you are using script tag to embed excalidraw then the name of the file will have to be updated to
- Reopen library menu on import from file #3383.
- Don't unnecessarily prompt when installing libraries #3329.
- Add option to flip single element on the context menu #2520.
- Replace fontSize and fontFamily text with icons #2857.
- Export dialog canvas positioning #3397.
- Don't share collab types with core #3353.
- Support d&d of files without extension #3168.
- Positions stats for linear elements #3331.
- Debounce.flush invokes func even if never queued before #3326.
- State selection state on opening contextMenu #3333.
- Add unique key for library header to resolve dev warnings #3316.
- disallow create text in viewMode on mobile #3219.
- Make help toggle tabbable #3310
- Show Windows share icon for Windows users #3306.
- Don't scroll to content on INIT websocket message #3291.
- Use arrow function where possible #3315.
- Set the target to
window.name
if present during excalidraw libraries installation so it opens in same tab for the host. Ifwindow.name
is not set it will open in a new tab #3299. - Add
name
prop to indicate the name of the drawing which will be used when exporting the drawing. When supplied, the value takes precedence overintialData.appState.name
, thename
will be fully controlled by host app and the users won't be able to edit from within Excalidraw #3273. - Export API
setCanvasOffsets
viaref
to set the offsets for Excalidraw#3265.offsetLeft
andoffsetTop
props have been removed now so you have to use thesetCanvasOffsets
viaref
to achieve the same.
- Export API to export the drawing to canvas, svg and blob #3258. For more info you can check the readme
- Add a
theme
prop to indicate Excalidraw's theme. #3228. When this prop is passed, the theme is fully controlled by host app. - Support
libraryReturnUrl
prop to indicate what URL to install libraries to #3227.
-
- Rename prop
initialData.scrollToCenter
andsetScrollToCenter
API exposed via ref toinitialData.scrollToContent
andsetScrollToContent
respectively#3261.
- Rename prop
- Rename appearance to theme #3237.
- Since
appState.appearance
is renamed toappState.theme
so whereverappState.appearance
includinginitialData.appState.appearance
should be renamed toappState.theme
andinitialData.appState.theme
respectively. If theappearance
was persisted earlier, now it needs to passed astheme
. - The class
Appearance_dark
is renamed totheme--dark
. - The class
Appearance_dark-background-none
is renamed totheme--dark-background-none
.
- Since
- Support pasting file contents & always prefer system clip #3257
- Add label for name field and use input when editable in export dialog #3286
- Implement the Web Share Target API #3230.
- Don't show export and delete when library is empty #3288
- Overflow in textinput in export dialog #3284.
- Bail on noop updates for newElementWith #3279.
- Prevent State continuously updated when holding ctrl/cmd #3283
- Debounce flush not invoked if lastArgs not defined #3281.
- Stop preventing canvas pointerdown/tapend events #3207.
- Double scrollbar on modals #3226.
- Allow copy of excalidraw elements only when inside excalidraw #3206.
- Position text editor absolute and fix the offsets so it doesn't remain fixed when the container is scrolled #3200.
- Scope CSS variables so that host CSS vars don't clash with excalidraw #3199.
- Apply correct translation when text editor overflows when zoom not 100% #3225
- Don't overflow text beyond width of Excalidraw #3215.
- Wrap excalidraw in position relative so host need not do it anymore & hide scrollbars in zen mode #3174.
- Reduce the scroll debounce timeout to
100ms
sooffsets
gets updated faster if changed when container scrolled #3182. - Rerender UI on
renderFooter
prop change #3183
- Temporarily downgrade browser-fs-access to fix legacy FS API #3172
- Use
Array.from
when spreading over set so that typescript transpiles correctly in the umd build#3165.
- Add export info on copy PNG to clipboard toast message #3159.
- Use the latest version of Virgil #3124.
- Support exporting with dark mode #3046.
-
Expose
window.EXCALIDRAW_ASSET_PATH
which host can use to load assets from a different URL. By default it will be loaded fromhttps://unpkg.com/@excalidraw/excalidraw{currentVersion}/dist/
#3068.Also now the assets will have a hash in filename so cache bursting can easily happen with version bump.
-
Add support for
scrollToCenter
in initialData so host can control whether to scroll to center on mount #3070. -
Export
restore
,restoreAppState
andrestoreElements
to host #3049
- Adjust line-confirm-threshold based on zoom #2884
- Hide scrollbars on mobile #3044
- Support Excalidraw inside scrollable container #3018
- Allow to toggle between modes when view only mode to make UI consistent #3009
- Allow host to pass color for collaborator #2943. The unused prop
user
is now removed. - Add
zenModeEnabled
andgridModeEnabled
prop which enables zen mode and grid mode respectively #2901. When this prop is used, the zen mode / grid mode will be fully controlled by the host app. - Allow host to pass userState for collaborator to show the current user state #2877.
- Add
viewModeEnabled
prop which enabled the view mode #2840. When this prop is used, the view mode will not show up in context menu is so it is fully controlled by host. - Expose
getAppState
onexcalidrawRef
#2834.
- Remove publicPath so host can use
__webpack_public_path__
to host the assets#2835
- Add the ability to clear library #2997
- Updates to Collaboration and RTL UX #2994
- Show toast when saving to existing file #2988
- Support supplying custom scale when exporting canvas #2904
- Show version in the stats dialog #2908
- Add idle detection to collaboration feature #2877
- Add view mode in Excalidraw #2840
- Increase max zoom #2881
- Remove copy & paste from context menu on desktop #2872
- Add separators on context menu #2659
- Add ctrl-y to redo #2831
- Add view mode #2840.
- Remove
copy
,cut
, andpaste
actions from contextmenu #2872 - Support
Ctrl-Y
shortcut to redo on Windows #2831.
- Refresh wysiwyg position on canvas resize #3008
- Update the
lang
attribute with the current lang. #2995 - Rename 'Grid mode' to 'Show grid' #2944
- Deal with users on systems that don't handle emoji #2941
- Mobile toolbar tooltip regression #2939
- Hide collaborator list on mobile if empty #2938
- Toolbar unnecessarily eats too much width #2924
- Mistakenly hardcoding scale #2925
- Text editor not visible in dark mode #2920
- Incorrect z-index of text editor #2914
- Make scrollbars draggable when offsets are set #2916
- Pointer-events being disabled on free-draw #2912
- Track zenmode and grid mode usage #2900
- Disable UI pointer-events on canvas drag #2856
- Stop flooring scroll positions #2883
- Apply initialData appState for zenmode and grid stats and refactor check param for actions #2871
- Show correct state of Nerd stats in context menu when nerd stats dialog closed #2874
- Remote pointers not accounting for offset #2855
- Toggle help dialog when "shift+?" is pressed #2828
- Add safe check for process so Excalidraw can be loaded via script #2824
- Fix UI pointer-events not disabled when dragging on canvas #2856.
- Fix remote pointers not accounting for offset #2855.
- Remove duplicate key handling #2878
- Reuse scss variables in js for SSOT #2867
- Rename browser-nativefs to browser-fs-access #2862
- Rewrite collabWrapper to remove TDZs and simplify #2834
- Use
Sentence case
forLive collaboration
- Bundle css files with js #2819. The host would not need to import css files separately.
-
Exported few Extra API's which can be used by the host to communicate with Excalidraw.
-
Remove language picker, and add
langCode
,renderFooter
#2644:- BREAKING: removed the language picker from UI. It is now the host app's responsibility to implement a language picker if desirable, using the newly added
renderFooter
prop. The reasoning is that the i18n should be controlled by the app itself, not by the nested Excalidraw component. - Added
langCode
prop to control the UI language.
- BREAKING: removed the language picker from UI. It is now the host app's responsibility to implement a language picker if desirable, using the newly added
-
Add support for
exportToBackend
prop to allow host apps to implement shareable links #2612
- Hide collaboration button when the prop
onCollabButtonClick
is not provided #2598
- Add toast #2772
- Add
cmd+o
shortcut to load scene #2732 - Require use of a preset dialog size; adjust dialog sizing #2684
- Add line chart and paste dialog selection #2670
- Tweak editing behavior #2668
- Change title to Excalidraw after a timeout
- Checkmark to toggle context-menu-items #2645
- Add zoom to selection #2522
- Insert Library items in the middle of the screen #2527
- Show shortcut context menu #2501
- Aligns arrowhead schemas #2517
- Add Cut to menus #2511
- More Arrowheads: dot, bar #2486
- Support CSV graphs and improve the look and feel #2495
- Fix compile error #2685
- Center zoom on iPhone and iPad #2642
- Allow text-selecting in dialogs & reset cursor #2783
- Don't render due to zoom after unmount #2779
- Track the chart type correctly #2773
- Fix late-render due to debounced zoom #2779
- Fix initialization when browser tab not focused #2677
- Consistent case for export locale strings #2622
- Remove unnecessary console.error as it was polluting Sentry #2637
- Fix scroll-to-center on init for non-zero canvas offsets #2445
- Fix resizing the pasted charts #2586
- Fix element visibility and zoom on cursor when canvas offset isn't 0. #2534
- Fix Library Menu Layout #2502
- Support number with commas in charts #2636
- Don't break zoom when zooming in on UI #2638
- Added Zen Mode to the context menu #2734
- Do not reset to selection for draw tool [#2721]((excalidraw/excalidraw#2721)
- Make dialogs look more like dialogs #2686
- Browse libraries styles fixed #2694
- Change hint for 2-point lines on resize #2655
- Align items in context menu #2640
- Do not reset to selection when using the draw tool #2721
- Display proper tooltip for 2-point lines during resize, and normalize modifier key labels in hints #2655
- Improve error message around importing images #2619
- Add tooltip with icon for embedding scenes #2532
- RTL support for the stats dialog #2530
- Expand canvas padding based on zoom. #2515
- Hide shortcuts on pickers for mobile #2508
- Hide stats and scrollToContent-button when mobile menus open #2509
- refactor: Converting span to kbd tag #2774
- Media queries #2680
- Remove duplicate entry from en.json#2654
- Remove the word toggle from labels #2648
- Document some of the more exotic element props #2673
- Update the homepage URL so it redirects to correct readme #2498
First release of @excalidraw/excalidraw