editate

An experimental, type-safe, framework agnostic and small (5kB+) contenteditable state manager.

Motivation

Web editing is so hard even today. There are excellent libraries to make complex rich text editor, but they are too much for small purposes. Native textarea element is accessible and easy to use, but it's hardly customizable.

contenteditable attribute is a primitive for rich text editing, that was designed for Internet Explorer and copied by other browsers. As you may know it has so many problems. It has no clear spec, it has many edge case bugs, and has cross browser/OS/input device problems. And it doesn't work well with declarative frontend frameworks... However, at least the core of contenteditable is stable and it works in all browsers except the inconsistencies. This library aims to fill that gap, fix contenteditable to fit modern web development.

Demo

• React Storybook
• Framework examples

Install

npm install editate

typescript >=5.0 is recommended.

Supported browsers

Browser versions supporting beforeinput event are supported.

Mobile browsers are also supported, but with some issues (https://github.com/inokawa/editate/issues/97).

Getting started

1. Define your document as a state.
2. Define your editor view declaratively. There are rules you have to follow:
   • You must render all texts in the document as Text nodes in DOM.
   • You must render <br/> in empty blocks (limitation of contenteditable).
   • You must render hard breaks in the document as block element.
   • You must render void nodes in the document as void element.
3. Use createPlainEditor/createEditor to initialize Editor with the document.
4. Call Editor.input on mount, with HTMLElement which is the root of editor view.
5. Update your state with onChange, which will be called on edit.
6. Call returned function from Editor.input on unmount for cleanup.

Here is an example for React.

Plain text

import { useState, useEffect, useRef } from "react";
import { createPlainEditor } from "editate";

export const App = () => {
  const ref = useRef<HTMLDivElement>(null);
  // 1. Define state
  const [text, setText] = useState("Hello world.");

  useEffect(() => {
    // 3. init
    const editor = createPlainEditor({
      text: text,
      onChange: (v) => {
        // 5. update state
        setText(v);
      },
    });
    // 4. bind to DOM
    const cleanup = editor.input(ref.current);
    return () => {
      // 6. cleanup DOM
      cleanup();
    };
  }, []);

  // 2. render from state
  return (
    <div
      ref={ref}
      style={{
        backgroundColor: "white",
        border: "solid 1px darkgray",
        padding: 8,
      }}
    >
      {text.split("\n").map((t, i) => (
        <div key={i}>{t ? t : <br />}</div>
      ))}
    </div>
  );
};

Rich text

You can define document schema with Standard Schema for type-safe editing.

import { useState, useEffect, useRef, useMemo } from "react";
import { createEditor, ToggleFormat, ToggleBlockAttr } from "editate";
import * as z from "zod";

const schema = z.strictObject({
  children: z.array(
    z.strictObject({
      align: z.enum(["left", "right"]).optional(),
      children: z.array(
        z.strictObject({
          text: z.string(),
          bold: z.boolean().optional(),
          italic: z.boolean().optional(),
        }),
      ),
    }),
  ),
});

export const App = () => {
  const ref = useRef<HTMLDivElement>(null);

  type Doc = z.infer<typeof schema>;
  const [doc, setDoc] = useState<Doc>({
    children: [
      {
        children: [
          { text: "Hello", bold: true },
          { text: " " },
          { text: "World", italic: true },
          { text: "." },
        ],
      },
    ],
  });

  const editor = useMemo(
    () =>
      createEditor({
        doc,
        schema,
        onChange: setDoc,
      }),
    [],
  );

  useEffect(() => {
    return editor.input(ref.current);
  }, []);

  return (
    <div>
      <div>
        <button
          onClick={() => {
            editor.exec(ToggleFormat, "bold");
          }}
        >
          bold
        </button>
        <button
          onClick={() => {
            editor.exec(ToggleFormat, "italic");
          }}
        >
          italic
        </button>
        <button
          onClick={() => {
            editor.exec(ToggleBlockAttr, "align", "right", undefined);
          }}
        >
          align
        </button>
      </div>
      <div
        ref={ref}
        style={{
          backgroundColor: "white",
          border: "solid 1px darkgray",
          padding: 8,
        }}
      >
        {doc.children.map((b, i) => (
          <div key={i} style={{ textAlign: b.align }}>
            {b.children.map((n, j) => (
              <span
                key={j}
                style={{
                  fontWeight: n.bold ? "bold" : undefined,
                  fontStyle: n.italic ? "italic" : undefined,
                }}
              >
                {n.text || <br />}
              </span>
            ))}
          </div>
        ))}
      </div>
    </div>
  );
};

Other examples

• React (Demo, Source)
• Vue (Demo, Source)
• Svelte (Demo, Source)
• Solid (Demo, Source)
• Angular (Demo, Source)
• Preact (Demo, Source)
• Vanilla (Demo, Source)

...and more! Contribution welcome!

Documentation

• API reference
• Storybook examples for more usages
• DeepWiki

Contribute

All contributions are welcome. If you find a problem, feel free to create an issue or a PR. If you have a question, ask in discussions.

Making a Pull Request

1. Fork this repo.
2. Run npm install.
3. Commit your fix.
4. Make a PR and confirm all the CI checks passed.

Inspirations

• ProseMirror
• Slate
• Lexical
• Quill
• Tiptap
• Draft.js
• rich-textarea (my early project)
• use-editable
• @react-libraries/markdown-editor
• VS Code
• Language Server Protocol
• urql
• TanStack DB
• Hono
• Textbus
• vistree
• Proposed EditContext API
• Proposed Richer Text Fields in Open UI