This document maintains a list of changes to Slate with each new version. Until 1.0.0 is released, breaking changes will be added as minor version bumps, and non-breaking changes won't be accounted for since the library is moving quickly.
- The
filterDescendantsandfindDescendantsmethods are now depth-first. This shouldn't affect almost anyone, since they are usually not the best things to be using for performance reasons. If you happen to have a very specific use case that needs breadth-first, (or even likely something better), you'll need to implement it yourself.
- Some
Nodemethods have been deprecated! There were a few methods that had been added over time that were either poorly named that have been deprecated and renamed, and a handful of methods that are no longer useful for the core library that have been deprecated. Here's a full list:areDescendantSorted->areDescendantsSortedgetHighestChild->getFurthestAncestorgetHighestOnlyChildParent->getFurthestOnlyChildAncestorconcatChildrendecorateTextsfilterDescendantsDeepfindDescendantDeepgetChildrenBetweengetChildrenBetweenIncludingisInlineSplitAtRange
- The
plugin.renderproperty is now calledplugin.renderPortal. This is to make way for the newplugin.renderproperty that offers HOC-like behavior, so that plugins can augment the editor however they choose.
-
Some
Selectionmethods have been deprecated! Previously there were many inconsistencies in the naming and handling of selection changes. This has all been cleaned up, but in the process some methods have been deprecated. Here is a full list of the deprecated methods and their new alternatives:moveToOffsets->moveOffsetsTomoveForward->movemoveBackward->movemoveAnchorOffset->moveAnchormoveFocusOffset->moveFocusmoveStartOffset->moveStartmoveEndOffset->moveEndextendForward->extendextendBackward->extendunset->deselect
-
Some selection transforms have been deprecated! Along with the methods, the selection-based transforms have also been refactored, resulting in deprecations. Here is a full list of the deprecated transforms and their new alternatives:
moveTo->selectmoveToOffsets->moveOffsetsTomoveForward->movemoveBackward->movemoveStartOffset->moveStartmoveEndOffset->moveEndextendForward->extendextendBackward->extendflipSelection->flipunsetSelection->deselectunsetMarks
- Inline nodes are now always surrounded by text nodes. Previously this behavior only occured for inline nodes with
isVoid: true. Now, all inline nodes will always be surrounded by text nodes. If text nodes don't exist, empty ones will be created. This allows for more consistent behavior across Slate, and parity with other editing experiences.
-
The unique
keygenerated values have changed. Previously, Slate generated unique keys that looked like'9dk3'. But they were not very conflict-resistant. Now the keys are simple string of auto-incrementing numbers, like'0','1','2'. This makes more clear that keys are simply a convenient way to uniquely reference nodes in the short-term lifespan of a single in-memory instance of Slate. They are not designed to be used for long-term uniqueness. A newsetKeyGeneratorfunction has been exported that allows you to pass in your own key generating mechanism if you want to ensure uniqueness. -
The
Rawserializer doesn't preserve keys by default. Previously, theRawserializer would omit keys when passed theterse: trueoption, but preserve them without it. Now it will always omit keys, unless you pass the newpreserveKeys: trueoption. This better reflects that keys are temporary, in-memory IDs. -
Operations on the document now update the selection when needed. This won't affect you unless you were doing some very specific things with transforms and updating selections. Overall, this makes it much easier to write transforms, since in most cases, the underlying operations will update the selection as you would expect without you doing anything.
- Node accessor methods no longer accept being passed another node! Previously, node accessor methods like
node.getParentcould be passed either akeystring or anodeobject. For performance reasons, passing in anodeobject is being deprecated. So if you have any calls that look like:node.getParent(descendant), they will now need to be written asnode.getParent(descendant.key). They will throw a warning for now, and will throw an error in a later version of Slate.
-
The
undoandredotransforms need to be applied! Previously,undoandredowere special cased such that they did not require an.apply()call, and instead would return a newStatedirectly. Now this is no longer the case, and they are just like every other transform. -
Transforms are no longer exposed on
StateorNode. The transforms API has been completely refactored to be built up of "operations" for collaborative editing support. As part of this refactor, the transforms are now only available via thestate.transform()API, and aren't exposed on theStateorNodeobjects as they were before. -
Transformobjects are now mutable. PreviouslyTransformwas an Immutable.jsRecord, but now it is a simple constructor. This is because transforms are inherently mutating their representation of a state, but this decision is up for discussion. -
The selection can now be "unset". Previously, a selection could never be in an "unset" state where the
anchorKeyorfocusKeywas null. This is no longer technically true, although this shouldn't really affect anyone in practice.
-
The
renderNodeandrenderMarkproperties are gone! Previously, rendering nodes and marks happened via these two properties of the<Editor>, but this has been replaced by the newschemaproperty. Check out the updated examples to see how to define a schema! There's a good chance this eliminates extra code for most use cases! 😄 -
The
renderDecorationsproperty is gone! Decoration rendering has also been replaced by the newschemaproperty of the<Editor>.
- The
data.filesproperty is now anArray. Previously it was a nativeFileListobject, but needed to be changed to add full support for pasting an dropping files in all browsers. This shouldn't affect you unless you were specifically depending on it being array-like instead of a trueArray.
- Void nodes are renderered implicitly again! Previously Slate had required that you wrap void node renderers yourself with the exposed
<Void>wrapping component. This was to allow for selection styling, but a change was made to make selection styling able to handled in Javascript. Now the<Void>wrapper will be implicitly rendered by Slate, so you do not need to worry about it, and "voidness" only needs to toggled in one place, theisVoid: trueproperty of a node.
- Marks are now renderable as components. Previously the only supported way to render marks was by returning a
styleobject. Now you can return a style object, a class name string, or a full React component. Because of this, the DOM will be renderered slightly differently than before, resulting in an extra<span>when rendering non-component marks. This won't affect you unless you were depending on the DOM output by Slate for some reason.
- The
wrapandunwrapmethod signatures have changed! Previously, you would passtypeanddataas separate parameters, for example:wrapBlock('code', { src: true }). This was inconsistent with other transforms, and has been updated such that a single argument ofpropertiesis passed instead. So that example could now be:wrapBlock({ type: 'code', { data: { src: true }}). You can still pass atypestring as shorthand, which will be the most frequent use case, for example:wrapBlock('code').
-
The
onKeyDownandonBeforeInputhandlers signatures have changed! Previously, some Slate handlers had a signature of(e, state, editor)and others had a signature of(e, data, state, editor). Now all handlers will be passed adataobject—which contains Slate-specific data related to the event—even if it is empty. This is helpful for future compatibility where we might need to add data to a handler that previously didn't have any, and is nicer for consistency. TheonKeyDownhandler's newdataobject contains thekeyname,codeand a series ofis*properties to make working with hotkeys easier. TheonBeforeInputhandler's newdataobject is empty. -
The
Utilsexport has been removed. Previously, aKeyutility and thefindDOMNodeutility were exposed under theUtilsobject. TheKeyhas been removed in favor of thedataobject passed toonKeyDown. And thenfindDOMNodeutility has been upgraded to a top-level named export, so you'll now need to access it viaimport { findDOMNode } from 'slate'. -
Void nodes now permanently have
" "as content. Previously, they contained an empty string, but this isn't technically correct, since they have content and shouldn't be considered "empty". Now they will have a single space of content. This shouldn't really affect anyone, unless you happened to be accessing that string for serialization. -
Empty inline nodes are now impossible. This is to stay consistent with native
contenteditablebehavior, where although technically the elements can exist, they have odd behavior and can never be selected.
- The
Rawserializer is no longer terse by default! Previously, theRawserializer would return a "terse" representation of the document, omitting information that wasn't strictly necessary to deserialize later, like thekeyof nodes. By default this no longer happens. You have to opt-in to the behavior by passing{ terse: true }as the secondoptionsargument of thedeserializeandserializemethods.
-
Void components are no longer rendered implicity! Previously, Slate would automatically wrap any node with
isVoid: truein a<Void>component. But doing this prevented you from customizing the wrapper, like adding aclassNameorstyleproperty. So you must now render the wrapper yourself, and it has been exported asSlate.Void. This, combined with a small change to the<Void>component's structure allows the "selected" state of void nodes to be rendered purely with CSS based on the:focusproperty of a<Void>element, which previously had to be handled in Javascript. This allows us to streamline selection-handling logic, improving performance and reducing complexity. -
data-offset-keyis now<key>-<index>instead of<key>:<start>-<end>. This shouldn't actually affect anyone, unless you were specifically relying on that attribute in the DOM. This change greatly reduces the number of re-renders needed, since previously any additional characters would cause a cascading change in the<start>and<end>offsets of latter text ranges.
-
node.getTextNodes()is nownode.getTexts(). This is just for consistency with the other existingNodemethods likegetBlocks(),getInlines(), etc. And it's nicely shorter. 😉 -
Nodemethods nowthrowearlier during unexpected states. This shouldn't break anything for most folks, unless a strange edge-case was going undetected previously.
renderMark(mark, state, editor)is nowrenderMark(mark, marks, state, editor). This change allows you to render marks based on multiplemarkspresence at once on a given range of text, for example using a customBoldItalic.otffont when text has bothboldanditalicmarks.
transform.unwrapBlock()now unwraps selectively. Previously, callingunwrapBlockwith a range representing a middle sibling would unwrap all of the siblings, removing the wrapping block entirely. Now, calling it with those same arguments will only move the middle sibling up a layer in the hierarchy, preserving the nesting on any of its siblings. This changes makes it much simpler to implement functionality like unwrapping a single list item, which previously would unwrap the entire list.
transform.mark()is nowtransform.addMark()andtransform.unmark()is nowtransform.removeMark(). The new names make it clearer that the transforms are actions being performed, and it paves the way for adding atoggleMarkconvenience as well.
🎉