• Stars
    star
    29,825
  • Rank 603 (Top 0.02 %)
  • Language
    TypeScript
  • License
    MIT License
  • Created over 8 years ago
  • Updated 30 days ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

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

A completely customizable framework
for building rich text editors.


Why? · Principles · Demo · Examples · 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. It was inspired by libraries like Draft.js, Prosemirror and Quill.

🤖 Slate is currently in beta. Its core API is useable right now, but you might need to pull request improvements for advanced use cases, or fixes for some bugs. Some of its APIs are not "finalized" and will have breaking changes over time as we discover better solutions. There isn't currently a 1.0 release schedule, we're still getting the architecture right.

🤖 Slate is also contributor-driven. It is not backed by any huge company, which means that all contributions are voluntary and done by the people who need them. If you need something improved, added, or fixed, please contribute it yourself or no one will. And if you want to become a more active maintainer, let us know in the Slack channel.


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. 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 assumes very little 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. Intuitive commands. Slate documents are edited using "commands", 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.

  6. Collaboration-ready data model. The data model Slate uses—specifically how operations 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.

  7. 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.
  • Markdown preview — showing how to add key handlers for Markdown-like shortcuts.
  • Inlines — showing how wrap text in inline nodes with associated data.
  • Images — showing how to use void (text-less) nodes to add images.
  • Hovering toolbar — showing how a hovering toolbar 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.
  • Mentions — showing how to use inline void nodes for simple @-mentions.
  • See all the examples...

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


Documentation

If you're using Slate for the first time, check out the Getting Started walkthroughs and the Concepts to familiarize yourself with Slate's architecture and mental models.

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-history A plugin that adds undo/redo history to Slate.
slate-hyperscript A hyperscript tool to write JSX Slate documents!
slate-react React components for rendering Slate editors.

Contributing!

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

Slate is MIT-licensed.

More Repositories

1

superstruct

A simple and composable way to validate data in JavaScript (and TypeScript).
TypeScript
6,946
star
2

permit

An unopinionated authentication library for building Node.js APIs.
JavaScript
1,683
star
3

react-values

A set of tiny React components for handling state with render props.
JavaScript
1,024
star
4

awesome-heroku

A curated list of helpful Heroku resources.
291
star
5

slate-plugins

A set of my personal Slate editor plugins, in a monorepo.
JavaScript
232
star
6

to-case

Simple case detection and conversion for strings.
JavaScript
122
star
7

minify

Simple, clean API for minifying Javascript, HTML or CSS.
JavaScript
112
star
8

hpmor

A set of covers for "Harry Potter and the Methods of Rationality".
112
star
9

css-color-function

A parser and converter for Tab Atkins's proposed color function in CSS.
JavaScript
91
star
10

is

Simple type checking.
JavaScript
77
star
11

router

A nice client-side router.
JavaScript
70
star
12

bump

Easily bump the version of all the different package.json equivalents.
JavaScript
64
star
13

heroku-logger

A dead simple logger, designed to be perfect for Heroku apps.
JavaScript
59
star
14

is-empty

Check whether a value is empty.
JavaScript
47
star
15

browser-logger

A dead simple logger, designed to be perfect for the browser.
JavaScript
44
star
16

download-github-repo

Download and extract a GitHub repository from node.
JavaScript
42
star
17

void

A toolkit for making generative art.
TypeScript
42
star
18

pg-sql-helpers

A set helpers for writing dynamic SQL queries with `pg-sql` in Javascript.
JavaScript
38
star
19

to-camel-case

Convert a string to a camel case.
JavaScript
36
star
20

rework-pure-css

Spiritual successor:
JavaScript
33
star
21

to-snake-case

Convert a string to a snake case.
JavaScript
26
star
22

history

A nicer wrapper around the browser's History API. Push, replace, back, forward, etc.
JavaScript
25
star
23

makefile-help

An easy way to add a `make help` target to your Makefiles.
Makefile
24
star
24

slate-drop-or-paste-images

Moved! This package has moved to ianstormtaylor/slate-plugins...
24
star
25

rework-color-function

Implements Tab Atkins's proposed color function in CSS.
CSS
22
star
26

slate-auto-replace

Moved! This package has moved to ianstormtaylor/slate-plugins...
22
star
27

trigger-event

Programmatically trigger a DOM event. Useful for unit testing mostly.
JavaScript
21
star
28

component-size

A component command to list the sizes of all your component's dependencies.
JavaScript
18
star
29

to-title-case

Convert a string to a title case.
JavaScript
17
star
30

component-update

A component command plugin to update out of date dependencies.
JavaScript
16
star
31

to-no-case

Remove an existing case from a string.
JavaScript
16
star
32

reset

An opinionated CSS reset for web *apps*.
CSS
15
star
33

css

Simple CSS manipulation.
JavaScript
15
star
34

component-outdated

A component command plugin to list outdated dependencies.
JavaScript
14
star
35

read-file-stdin

Read from a file, falling back to stdin.
JavaScript
14
star
36

create-event

Create an event object cross browser. Useful for unit testing mostly.
JavaScript
13
star
37

correct-email

Correct common misspellings in an email address, based on Kicksend's Mailcheck library.
JavaScript
13
star
38

backbone-inheritance

(I no longer use Backbone, but feel free to check this plugin out. The code is pretty straightforward.) A Backbone.js mixin that lets Views inherit properties from their parents.
JavaScript
12
star
39

to-capital-case

Convert a string to a capital case.
JavaScript
11
star
40

to-slug-case

Convert a string to a slug case.
JavaScript
11
star
41

jquery-state

A jQuery plugin that makes setting states in the DOM easy and accessible.
JavaScript
11
star
42

animate

Easily apply animate.css animations to elements via Javascript.
CSS
10
star
43

slate-paste-linkify

Moved! This package has moved to ianstormtaylor/slate-plugins...
10
star
44

backbone-state

(I no longer use Backbone, but feel free to check this plugin out. The code is pretty straightforward.) A Backbone.js mixin that adds states to Views.
JavaScript
9
star
45

slate-soft-break

Moved! This package has moved to ianstormtaylor/slate-plugins...
8
star
46

title-case-minors

A list of the minor words that shouldn't be capitalized in a title case string.
JavaScript
8
star
47

closest-match

Find the closest match for a string from an array of matches, using string distance.
JavaScript
7
star
48

loading

A simple way to toggle loading state.
JavaScript
7
star
49

to-sentence-case

Convert a string to a sentence case.
JavaScript
6
star
50

makefile-assert

An easy way to assert that an environment variable is defined in your Makefiles.
Makefile
6
star
51

mailto

Programmatically open the user's email client.
JavaScript
6
star
52

assert-dir-equal

Assert that the contents of two directories are equal.
JavaScript
6
star
53

write-file-stdout

Write to a file, falling back to stdout.
JavaScript
6
star
54

slate-auto-replace-text

Deprecated! Use ianstormtaylor/slate-auto-replace instead...
6
star
55

to-space-case

Convert a string to a space case.
JavaScript
5
star
56

to-dot-case

Convert a string to a dot case.
JavaScript
5
star
57

to-constant-case

Convert a string to a constant case.
JavaScript
4
star
58

parallel

A simple API for running async functions in parallel.
JavaScript
4
star
59

rework-font-variant

Implements the font-variant-* properties for browsers that don't yet support them.
JavaScript
4
star
60

email

Parse an email address into its components, based on component/url.
JavaScript
4
star
61

parent

Get the parent of an element.
JavaScript
3
star
62

get

Get a property from a model or object.
JavaScript
3
star
63

to-pascal-case

Convert a string to pascal case.
JavaScript
3
star
64

classes

Quickly mixin class helper methods to a view.
JavaScript
3
star
65

map

Map an array or object.
JavaScript
3
star
66

matchuppps

My 10K Apart 2010 entry that won Best Design
JavaScript
3
star
67

bind

A clear API for function binding helpers.
JavaScript
3
star
68

slate-collapse-on-escape

Moved! This package has moved to ianstormtaylor/slate-plugins...
3
star
69

backbone-getset

(I no longer use Backbone, but feel free to check this plugin out. The code is pretty straightforward.) A Backbone.js mixin that adds a getter and setter to Backbone Views.
JavaScript
2
star
70

typekit

Load a Typekit kit asynchronously, automatically handling FOUT.
JavaScript
2
star
71

backbone-events

(I no longer use Backbone, but feel free to check this plugin out. The code is pretty straightforward.) A Backbone.js mixin that lets you define all your events in one place.
JavaScript
2
star
72

pick

Pick keys from an object, returning a clone.
JavaScript
1
star
73

reduce

Reduce an array or object.
JavaScript
1
star
74

callback

Sugar for couthly calling functions back.
JavaScript
1
star
75

changesets-logo

A logo for Changesets.
1
star
76

graph

WIP, naming ideas much appreciated :)
JavaScript
1
star
77

redraw

Force a redraw on an element.
JavaScript
1
star
78

on-load

Callback when the document has loaded.
JavaScript
1
star
79

set

Set a property on a model or object.
JavaScript
1
star
80

case

Moved to https://github.com/ianstormtaylor/to-case
JavaScript
1
star
81

slate-auto-replace-block

Deprecated! Use ianstormtaylor/slate-auto-replace instead...
1
star