Building an awesome editor for your React-based web application is by no means easy. But with things get much easier. Even with the help of Slate, building a full-featured editor is way more work than we can cover in one blog post, so this post will give you the big picture and subsequent posts will dive into the dirty details. SlateJS Note: this post is based on a recent talk at the JavaScript NYC meetup. You can watch the video here: SlateJS We're building , a new, fast, and highly collaborative alternative to issue trackers like Jira, Trello, and Clubhouse. We're big believers in remote work, and in particular working asynchronously so that team members get large, uninterrupted blocks of time to get work done. A key to supporting this type of work is having a really great editor so that teams are inspired to collaborate together on issues and ensure alignment. And we think we've got the best editor around: Kitemaker Markdown shortcuts, code blocks with syntax highlighting, images, embedding designs from , math expressions with LaTex, diagrams with , and, of course, emojis ♥️. All done entirely with Slate. Figma MermaidJS So why did we choose to go with Slate in the first place? It's definitely not the only editor framework out there. For us, the things that pushed us towards Slate were: It's un-opinionated about how your document is structured, and that gave us the flexibility we needed It doesn't force any built-in toolbars or any other visuals upon you It's built with React in mind and that makes a huge difference when rendering complex documents It lays the foundation for collaborative editing which is something we believe is important for Kitemaker We really like the philosophy behind it It has a thriving community, particularly on Slack How Slate represents documents One of the best parts of Slate is how it holds very few opinions about how documents are structured. It has only a few concepts: Editor - the top level container of your document Block level elements - the domain-specific "chunks" that make up your documents, like paragraphs, code blocks and lists. These are the things you can draw horizontal lines between in your document Inline elements - special elements that flow inline with the text of your document, like links Text nodes - these contain the actual text in the document Marks - annotations placed on the text, such as marking text as bold or italic Astute readers will notice that this is structured very similar to the DOM, and text, block and inlines in Slate behave very much like their counterparts in the DOM. Here's an annotated screenshot of a Slate editor to explain these concepts visually: Slate uses a very simple JSON format for representing documents, and the document above would look like this in Slate's representation: [ { : , : [ { : }, { : , : , : [ { : } ] }, { : } ] }, { : , : [ { : }, { : , : }, { : }, { : , : }, { : } ] } ] "type" "paragraph" "children" "text" "Text with a link " "type" "link" "url" "https://kitemaker.co" "children" "text" "https://kitemaker.co" "text" " here" "type" "paragraph" "children" "text" "Text with " "text" "bold" "bold" true "text" " and " "text" "italic" "italic" true "text" " here" As we said before, Slate is really un-opinionated about how documents are structured. In the JSON blob above, the only thing Slate cares about is that it gets an array of block elements with a property and that those children are either other block elements, or a mixture of text nodes and inline elements. That's it. Slate doesn't care about the , or properties and it doesn't care about how these various nodes will be rendered. This makes it really flexible and powerful to work with. children type url bold Hello world editor Enough background. Let's look at some code! Let's see what a simple editor component looks like using Slate: { editor = useMemo( withReact(createEditor()), []); [value, setValue] = React.useState<Node[]>([ { : [{ : }], }, ]); ( <Editable /> ); } ( ) function MyEditor const => () const children text 'Testing' return setValue(v)}> < = = = => Slate editor {editor} value {value} onChange {(v) </ > Slate And that's it. That's an entire working component with Slate! We use to make ourselves an editor (don't worry about for now - that's a plugin, which we'll discuss below) createEditor() withReact() We make a simple array of nodes to store the document (just like we looked at above) We instantiate a component which serves as a context provider, providing the editor we created above to all of the components below it. This is really cool because you can, for example, add toolbars and other components below the component that can grab the editor and manipulate the document with it. We also wire up the and properties, similar to any input in React <Slate> <Slate> value onChange We add an component which is the actual editor the user interacts with on the screen <Editable> Boring. How do we extend things? So while that previous example was trivial to write, we still only have an editor that works about as well as . Not very exciting. <TextArea> Luckily Slate provides mechanisms for making things a whole lot more interesting: plugins allow us to override the core behavior of the editor. They're not concerned with rendering, just with overriding what happens when (for example) text is inserted, or an image is dropped Plugins: allow us to handle things like key presses, so we can add hotkeys or allow pressing 'tab' to indent a bulleted list Event handlers: with Slate we can specify exactly how each and every node in our document should be rendered using React Custom rendering with React: Let's take a quick look at each of these. Plugins Plugins are a deceptively simple, powerful concept in Slate. Plugins generally look something like this: { { insertText, insertData, normalizeNode, isVoid, isInline } = editor; editor.insertText = { insertText(text); }; editor.insertData = { insertData(data); }; editor.normalizeNode = { normalizeNode(entry); }; editor.isVoid = { (element.type === ) { ; } isVoid(element); }; editor.isInline = { (element.type === ) { ; } isInline(element); }; editor; } export ( ) function withMyPlugin editor: ReactEditor const // called whenever text is inserted into the document (e.g. when // the user types something) ( ) => text // do something interesting! // called when the users pastes or drags things into the editor ( ) => data // do something interesting! // we'll dedicate a whole post to this one, but the gist is that it's used // to enforce your own custom schema to the document JSON ( ) => entry // do something interesting! // tells slate that certain nodes don't have any text content (they're _void_) // super handy for stuff like images and diagrams ( ) => element if 'image' return true return // tells slate that certain nodes are inline and should flow with text, like // the link in our example above ( ) => element if 'link' return true return return By convention, their names start with . They take a Slate editor, override whatever functions they need to override and return the modified editor back. Very often, they handle a few cases in some of these functions and fall back to the default behavior for the rest. about 80% of adding functionality to a Slate editor is doing string matching in these plugin functions and then manipulate the document using Slate's rich API. with Spoiler alert: There are more functions you can override than the ones shown above, but these are the most common by far. You can read all about plugins in . Slate's documentation One of the most powerful parts of Slate plugins is that they can be composed together. Each plugin can look for the things it cares about and pass everything else along unmodified. Then you can compose multiple plugins together and get an even more powerful editor: { editor = useMemo( withReact(withDragAndDrop(withMarkdownShortcuts(withEmojis(withReact(createEditor())))), []); ... } ( ) function MyEditor const => () Event handlers Like many React input components, the component has a bunch of events to which you can listen. We don't have time to go through them all here, but we'll mention the one we use most often: <Editable> onKeyDown() By handling this event, we can do all sorts of powerful things in our editor, like adding hotkeys for example: <Editable onKeyDown={(e) => { (e.metaKey && e.key === ) { e.preventDefault(); Editor.addMark(editor, , ); } }} ... /> // let's make the current text bold if the user holds command and hits "b" if 'b' 'bold' true We use key down events in Kitemaker: everywhere Nesting and un-nesting lists when tab is pressed Breaking out of lists and code blocks when enter (or in some cases backspace) is pressed Splitting blocks (e.g. headlines) when enter is pressed in the middle of a block And many many more Custom rendering with React Slate has no opinions on how your blocks and inlines should look on the screen. By default, it just shoves all blocks into plain elements and all inlines into plain elements, but that's pretty dull. <div> <span> To override Slate's default behavior, all we need to do is pass a function into the component's property: <Editable> renderElement <Editable renderElement={({ element, attributes, children }) => { (element.type) { : ; : ; : ; } }} /> switch case 'code' return {children} < { }> pre ...attributes </ > pre case 'link' return {children} < = { }> a href {element.url} ...attributes </ > a default return {children} < { }> div ...attributes </ > div All this code is doing is looking for the property on a node and picking a different rendering path based on that. Remember, as we said before, Slate doesn't care about these properties, only do. So while the convention is to use to denote the type of a node, nothing is forcing you to do so. You can also add all sorts of other properties to your components that help with the rendering (like the url property we saw on links above). type we type The things returned from just need to be React components. What they look like and their complexity is entirely up to you. Here we're returning a simple element to denote a code block, but nothing is stopping us from returning a full blown component that supports syntax highlighting (like we do in Kitemaker). renderElement <pre> <Code> There's only one important thing to remember when implementing your own rendering - always spread the parameter as properties on the topmost component you're returning. If you don't, Slate won't be able to do its own internal bookkeeping and things will go very badly for you. attributes This has been a super quick introduction to custom rendering, so don't worry if you don't fully grasp it yet. What's tricky in Slate? You've now seen some of the basics of Slate, so you're ready to start experimenting. We thought we'd warn you a little about some of the pitfalls and tricky parts of working with Slate so you'll see them coming and not get discouraged: copying and pasting on the web is a mess. We'll dedicate a whole post to how we handle this in Kitemaker. Short version is that to test our own "paste logic", we have made a somewhat complex document in a bunch of popular web editors Google docs, Notion, Dropbox Paper, Quip, etc. Copying and pasting: by default, Slate doesn't support undo/redo. It does however come with a plugin called that provides this functionality. However, we've found that this doesn't provide the exact user experience we're looking for and so we've had to extend it ourselves History: useHistory() dealing with things that pop up and need to be positioned correctly (like what you see in the Kitemaker editor above when "/" is typed to insert a block or "@" is typed to mention a user) can be pretty tricky Hovers/floating menus: Kitemaker is a product with a ton of hotkeys for everything (we want our users to be able to use it without lifting their hands off the keys) but sometimes there have been some challenges with the key handling in Slate "fighting" with our hotkeys Key handling: Slate's API is quite extensive and we haven't even begun to touch on it in this post. There are many, many functions for manipulating the document (adding nodes, removing nodes, splitting nodes, wrapping nodes, adding text, deleting words, etc.) and it's not always totally obvious which API to use in which situation Big API surface: we've had complaints from users using MBPs and also things like pen inputs for writing Japanese. There's a to fix some strange behaviors so hopefully it'll be fixed soon 🤞 Some wonkiness with input methods like the Macbook Pro touch bar: PR open We'll cover some of these advanced topics in our subsequent posts. And a brief word of warning While we've been very happy with Slate so far, there are a few warnings that any team embarking on building their own editor should be aware of: Like any open source project, progress on Slate comes in waves. While there was a huge rewrite last year and things moved really quickly, progress has now slowed down considerably. There are lots of open issues and open PRs. We hope we can do our share to improve this going forward, but the community could use more support After the rewrite last year, the documentation hasn't quite gotten back to the standard it was before the rewrite. There's a fair amount of stubbed-out documentation that lacks the details required by developers who are just getting started with the project. We've submitted some changes to improve this, but more work is needed Slate is not properly supported on Android. Fortunately, there was a to fix this. Awesome! 🤙 Kickstarter project funded More to come! We hope this served as a nice high level introduction to Slate for you and gave you some of the information you need about whether or not to give Slate a try. There is way way way too much material to cover in a single post, but there will be a number of posts that follow that dig into some of the more complex topics. Thanks for reading! Did you find this article useful? If you want to see more material like this follow and on Twitter. @ksimons @KitemakerHQ Kevin Simons is the CTO of Kitemaker, the super-fast issue tracker that gives distributed teams superpowers Previously published at https://blog.kitemaker.co/building-a-rich-text-editor-in-react-with-slatejs
