ianstormtaylor/slate


A completely customizable framework for building rich text editors. (Currently in beta.)

http://slatejs.org

License: MIT

Language: JavaScript

Keywords: browser, editor, framework, javascript, react, rich-text, slate, text-editor


A completely customizable framework
for building rich text editors.


Why? · Principles · Demo · Examples · Plugins · Documentation · Contributing!



Slate lets you build rich, intuitive editors like those in Medium, Dropbox Paper or Google Docs—which are becoming table stakes for applications on the web—without your codebase getting mired in complexity.

It can do this because all of its logic is implemented with a series of plugins, so you aren't ever constrained by what is or isn't in "core". You can think of it like a pluggable implementation of contenteditable built on top of React and Immutable. It was inspired by libraries like Draft.js, Prosemirror and Quill.

🤖 Slate is currently in beta. Its core API is useable now, but you might need to pull request a fix or two for advanced use cases. Some of its APIs are not "finalized" and will (breaking) change over time as we discover better solutions.


Why?

Why create Slate? Well... (Beware: this section has a few of my opinions!)

Before creating Slate, I tried a lot of the other rich text libraries out there—Draft.js, Prosemirror, Quill, etc. What I found was that while getting simple examples to work was easy enough, once you started trying to build something like Medium, Dropbox Paper or Google Docs, you ran into deeper issues...

  • The editor's "schema" was hardcoded and hard to customize. Things like bold and italic were supported out of the box, but what about comments, or embeds, or even more domain-specific needs?

  • Transforming the documents programmatically was very convoluted. Writing as a user may have worked, but making programmatic changes, which is critical for building advanced behaviors, was needlessly complex.

  • Serializing to HTML, Markdown, etc. seemed like an afterthought. Simple things like transforming a document to HTML or Markdown involved writing lots of boilerplate code, for what seemed like very common use cases.

  • Re-inventing the view layer seemed inefficient and limiting. Most editors rolled their own views, instead of using existing technologies like React, so you have to learn a whole new system with new "gotchas".

  • Collaborative editing wasn't designed for in advance. Often the editor's internal representation of data made it impossible to use to for a realtime, collaborative editing use case without basically rewriting the editor.

  • The repositories were monolithic, not small and reusable. The code bases for many of the editors often didn't expose the internal tooling that could have been re-used by developers, leading to having to reinvent the wheel.

  • Building complex, nested documents was impossible. Many editors were designed around simplistic "flat" documents, making things like tables, embeds and captions difficult to reason about and sometimes impossible.

Of course not every editor exhibits all of these issues, but if you've tried using another editor you might have run into similar problems. To get around the limitations of their API's and achieve the user experience you're after, you have to resort to very hacky things. And some experiences are just plain impossible to achieve.

If that sounds familiar, you might like Slate.

Which brings me to how Slate solves all of that...


Principles

Slate tries to solve the question of "Why?" with a few principles:

  1. First-class plugins. The most important part of Slate is that plugins are first-class entities—the core editor logic is even implemented as its own plugin. That means you can completely customize the editing experience, to build complex editors like Medium's or Dropbox's, without having to fight against the library's assumptions.

  2. Schema-less core. Slate's core logic doesn't assume anything about the schema of the data you'll be editing, which means that there are no assumptions baked into the library that'll trip you up when you need to go beyond the most basic use cases.

  3. Nested document model. The document model used for Slate is a nested, recursive tree, just like the DOM itself. This means that creating complex components like tables or nested block quotes are possible for advanced use cases. But it's also easy to keep it simple by only using a single level of hierarchy.

  4. Parallel to the DOM. Slate's data model is based on the DOM—the document is a nested tree, it uses selections and ranges, and it exposes all the standard event handlers. This means that advanced behaviors like tables or nested block quotes are possible. Pretty much anything you can do in the DOM, you can do in Slate.

  5. Stateless views and immutable data. By using React and Immutable.js, the Slate editor is built in a stateless fashion using immutable data structures, which leads to much easier to reason about code, and a much easier time writing plugins.

  6. Intuitive changes. Slate documents are edited using "changes", that are designed to be high-level and extremely intuitive to write and read, so that custom functionality is as expressive as possible. This greatly increases your ability to reason about your code.

  7. Collaboration-ready data model. The data model Slate uses—specifically how changes are applied to the document—has been designed to allow for collaborative editing to be layered on top, so you won't need to rethink everything if you decide to make your editor collaborative.

  8. Clear "core" boundaries. With a plugin-first architecture, and a schema-less core, it becomes a lot clearer where the boundary is between "core" and "custom", which means that the core experience doesn't get bogged down in edge cases.


Demo

Check out the live demo of all of the examples!


Examples

To get a sense for how you might use Slate, check out a few of the examples:

  • Plain text — showing the most basic case: a glorified <textarea>.
  • Rich text — showing the features you'd expect from a basic editor.
  • Auto-markdown — showing how to add key handlers for Markdown-like shortcuts.
  • Links — showing how wrap text in inline nodes with associated data.
  • Images — showing how to use void (text-less) nodes to add images.
  • Hovering menu — showing how a contextual hovering menu can be implemented.
  • Tables — showing how to nest blocks to render more advanced components.
  • Paste HTML — showing how to use an HTML serializer to handle pasted HTML.
  • Code Highlighting — showing how to use decorations to dynamically mark text.
  • See all the examples...

If you have an idea for an example that shows a common use case, pull request it!


Plugins

Slate encourages you to write small, reusable modules. Check out the public ones you can use in your project!


Documentation

If you're using Slate for the first time, check out the Getting Started walkthroughs and the Guides to familiarize yourself with Slate's architecture and mental models. Once you've gotten familiar with those, you'll probably want to check out the full API Reference.

If even that's not enough, you can always read the source itself, which is heavily commented.

There are also translations of the documentation into other languages:

If you're maintaining a translation, feel free to pull request it here!


Packages

Slate's codebase is monorepo managed with Lerna. It consists of a handful of packages—although you won't always use all of them. They are:

Package Version Size Description
slate Slate's core data model logic.
slate-base64-serializer A Base64 string serializer for Slate documents.
slate-html-serializer An HTML serializer for Slate documents.
slate-hyperscript A hyperscript tool to write JSX Slate documents!
slate-plain-serializer A plain text serializer for Slate documents.
slate-prop-types React prop types for checking Slate values.
slate-react React components for rendering Slate editors.
slate-hotkeys Detect common keypresses in a platform-agnostic way

Contributing!

All contributions are super welcome! Check out the Contributing instructions for more info!

Slate is MIT-licensed.

Project Statistics

Sourcerank 19
Repository Size 13.1 MB
Stars 16,509
Forks 1,624
Watchers 302
Open issues 177
Dependencies 1,445
Contributors 248
Tags 2,806
Created
Last updated
Last pushed

Top Contributors See all

Ian Storm Taylor Samy Pessé Nicolas Gaborit Jinxuan Zhu AlbertHilb Per-Kristian Nordnes Sunny Hirai Yifeng Wang Zach Schneider Eric Edem Ryan Yurkanin Dundercover Justin Weiss Anuj Irwan Fario Subastian Tobias Andersen Benjamin Kniffler Conor Cussell Tyler Johnson Dan Burzo

Packages Referencing this Repo

slate-dev-environment
INTERNAL: A set of environment-related constants for Slate's core.
Latest release 0.2.2 - Updated - 16.5K stars
slate-hotkeys
A set of function to detect common keypresses in a platform-agnostic way
Latest release 0.2.9 - Updated - 16.5K stars
@eliumhq/slate-react
A set of React components for building completely customizable rich-text editors.
Latest release 0.11.7-4 - Published - 16.5K stars
slate-react
Tools for building completely customizable richtext editors with React.
Latest release 0.57.1 - Updated - 16.5K stars
slate-html-serializer
An HTML serializer for Slate editors.
Latest release 0.8.11 - Updated - 16.5K stars
slate-hyperscript
A hyperscript helper for creating Slate documents.
Latest release 0.57.1 - Updated - 16.5K stars
slate-dev-logger
INTERNAL: A simple, development-only logger for Slate.
Latest release 0.1.43 - Updated - 16.5K stars
slate
A completely customizable framework for building rich text editors.
Latest release 0.57.1 - Updated - 16.5K stars
slate-prop-types
A set of React prop type checkers for Slate editors.
Latest release 0.5.42 - Updated - 16.5K stars
slate-plain-serializer
A plain text serializer for Slate editors.
Latest release 0.7.11 - Updated - 16.5K stars
slate-simulator
A simulator for testing Slate editors and plugins.
Latest release 0.4.67 - Updated - 16.5K stars
slate-base64-serializer
A Base64 serializer for Slate editors.
Latest release 0.2.112 - Updated - 16.5K stars
slate-history
An operation-based history implementation for Slate editors.
Latest release 0.57.1 - Updated - 16.5K stars
muxi-slate-react
A set of React components for building completely customizable rich-text editors.
Latest release 0.22.3 - Updated - 16.5K stars
@kancloud/slate
A completely customizable framework for building rich text editors.
Latest release 0.44.9 - Published - 16.5K stars
@royie/slate-prop-types
A set of React prop type checkers for Slate editors.
Latest release 0.5.24 - Updated - 16.5K stars
@mattkrick/slate-react
A set of React components for building completely customizable rich-text editors.
Latest release 0.13.6 - Updated - 16.5K stars
slate-fix
A completely customizable framework for building rich text editors.
Latest release 0.33.6 - Published - 16.5K stars
@opuscapita/slate-base64-serializer
A Base64 serializer for Slate editors.
Latest release 1.0.7 - Updated - 16.5K stars
slate-react-patch-android
A set of React components for building completely customizable rich-text editors.
Latest release 0.15.3 - Published - 16.5K stars

Recent Tags See all

v0.57.1 December 20, 2019
v0.57.0 December 18, 2019
v0.56.1 December 18, 2019
v0.56.0 December 18, 2019
v0.56.0 December 18, 2019
v0.55.3 December 16, 2019
v0.55.2 December 16, 2019
v0.55.1 December 16, 2019
v0.55.0 December 16, 2019
slate-react@0.54.6 December 14, 2019
slate-hyperscript@0.54.6 December 14, 2019
slate-history@0.54.6 December 14, 2019
slate@0.54.6 December 14, 2019
slate-react@0.54.5 December 13, 2019
slate-hyperscript@0.54.5 December 13, 2019

Interesting Forks See all

thesunny/slate
A completely customizable framework for building rich text editors.
JavaScript - MIT - Last pushed - 1 stars
discordapp/slate
A completely customizable framework for building rich text editors. (Currently in beta.)
JavaScript - MIT - Last pushed - 1 stars - 1 forks
NeoReyad/slate
A completely customizable framework for building rich text editors.
JavaScript - MIT - Last pushed - 1 stars
abumalick/slate
A completely customizable framework for building rich text editors.
JavaScript - Updated - 1 stars
soulwire/slate
A completely customizable framework for building rich text editors.
JavaScript - Updated - 1 stars

Something wrong with this page? Make a suggestion

Last synced: 2019-05-09 21:46:46 UTC

Login to resync this repository