edix

v0.2.1TypeScript

An experimental, framework agnostic, small (4kB+) contenteditable state manager.

contenteditable ui headless textarea input form highlight autocomplete tagging combobox

0/weekUpdated 5 months agoMITUnpacked: 194.8 KB

Published by inokawa

npm install edix

edix

!npm !npm bundle size ![check](https://github.com/inokawa/edix/actions/workflows/check.yml) ![demo](https://github.com/inokawa/edix/actions/workflows/demo.yml)

> An experimental, framework agnostic, small (4kB+) 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, but as you may know it has so many problems. 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

``sh npm install edix`

typescript >=5.0 is recommended.

`$3`

Browser versions supporting beforeinput event are supported.

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

`Getting started`

1. Define your contents declaratively. There are rules you have to follow:

- You must render
in empty row (limitation of contenteditable). - Ifmultilineoption is -falseor undefined, direct children of the root are treated as inline nodes. -true, direct children of the root are treated as rows. They must be elements, not text. - (TODO)

2. Initialize Editor with createEditor. 3. CallEditor.input on mount, with HTMLElementwhich is the root of editable contents. 4. Update your state withonChange, which will be called on edit. 5. Call returned function fromEditor.input on unmount for cleanup.

Here is an example for React.

`$3`

`tsx import { useState, useEffect, useRef } from "react"; import { createEditor, plainSchema } from "edix";

export const App = () => { const ref = useRef(null); const [value, setValue] = useState("Hello world.");

useEffect(() => { // 2. init const editor = createEditor({ doc: value, schema: plainSchema(), onChange: (v) => { // 4. update state setValue(v); }, }); // 3. bind to DOM const cleanup = editor.input(ref.current); return () => { // 5. cleanup DOM cleanup(); }; }, []);

// 1. render contents from state return ( ref={ref} style={{ backgroundColor: "white", border: "solid 1px darkgray", padding: 8, }} > {value ? value : }


  );
};

$3

`tsx import { useState, useEffect, useRef } from "react"; import { createEditor, plainSchema } from "edix";

export const App = () => { const ref = useRef(null); const [value, setValue] = useState("Hello world.");

useEffect(() => { // 2. init const editor = createEditor({ doc: value, schema: plainSchema({ multiline: true }), onChange: (v) => { // 4. update state setValue(v); }, }); // 3. bind to DOM const cleanup = editor.input(ref.current); return () => { // 5. cleanup DOM cleanup(); }; }, []);

// 1. render contents from state return ( ref={ref} style={{ backgroundColor: "white", border: "solid 1px darkgray", padding: 8, }} > {value.split("\n").map((t, i) => (

{t ? t : 
}

))}


  );
};


$3
- React (Demo, Source)
- Vue (Demo, Source)
- Svelte (Demo, Source)
- Solid (Demo, Source)
- Angular (Demo, Source)
- Preact (Demo, Source)
- Qwik (Source)
- Vanilla (Demo, Source)
...and more! Contribution welcome!
Documentation
- API reference
- Storybook examples for more usages
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.
$3

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

Inspirations

- Many great text editor libraries (ProseMirror, Lexical, Slate, Quill, Draft.js, etc.)
- rich-textarea (my early work)
- use-editable
- @react-libraries/markdown-editor
- Textbus
- vistree
- Proposed EditContext API
- Proposed Richer Text Fields in Open UI

Motivation

Getting started

1. Define your contents declaratively. There are rules you have to follow:

- You must render

 in empty row (limitation of contenteditable).
   - If

multiline

 option is
     -

false

 or undefined, direct children of the root are treated as inline nodes.
     -

true

, direct children of the root are treated as rows. They must be elements, not text.
   - (TODO)

2. Initialize Editor with createEditor

.
3. Call

Editor.input on mount, with HTMLElement

 which is the root of editable contents.
4. Update your state with

onChange

, which will be called on edit.
5. Call returned function from

Editor.input on unmount for cleanup.

Here is an example for React.

$3

tsx
import { useState, useEffect, useRef } from "react";
import { createEditor, plainSchema } from "edix";

export const App = () => {
  const ref = useRef(null);
  const [value, setValue] = useState("Hello world.");

  useEffect(() => {
    // 2. init
    const editor = createEditor({
      doc: value,
      schema: plainSchema(),
      onChange: (v) => {
        // 4. update state
        setValue(v);
      },
    });
    // 3. bind to DOM
    const cleanup = editor.input(ref.current);
    return () => {
      // 5. cleanup DOM
      cleanup();
    };
  }, []);

  // 1. render contents from state
  return (
          ref={ref}
      style={{
        backgroundColor: "white",
        border: "solid 1px darkgray",
        padding: 8,
      }}
    >
      {value ? value : 
}