Lexical

Lexical is an extensible text editor framework that provides excellent reli...

Rich text editorReact
facebook/lexicallexical.dev@lexical/react

README

Lexical

GitHub Workflow Status Visit the NPM page Add yourself to our Discord Follow us on Twitter


Lexical is an extensible JavaScript web text-editor framework with an emphasis on reliability, accessibility, and performance. Lexical aims to provide a best-in-class developer experience, so you can easily prototype and build features with confidence. Combined with a highly extensible architecture, Lexical allows developers to create unique text editing experiences that scale in size and functionality.

For documentation and more information about Lexical, be sure to visit the Lexical website.

Here are some examples of what you can do with Lexical:

- Lexical Playground
- Plain text sandbox
- Rich text sandbox



Overview:

- Getting started with React

- Lexical is a framework

- Working with Lexical

- Contributing to Lexical


Getting started with React


Note: Lexical is not only limited to React. Lexical can support any underlying DOM based library once bindings for that library have been created.


Install lexical and @lexical/react:

  1. ```
  2. npm install --save lexical @lexical/react
  3. ```

Below is an example of a basic plain text editor using lexical and @lexical/react (try it yourself).

  1. ``` js
  2. import {$getRoot, $getSelection} from 'lexical';
  3. import {useEffect} from 'react';

  5. import {LexicalComposer} from '@lexical/react/LexicalComposer';
  6. import {PlainTextPlugin} from '@lexical/react/LexicalPlainTextPlugin';
  7. import {ContentEditable} from '@lexical/react/LexicalContentEditable';
  8. import {HistoryPlugin} from '@lexical/react/LexicalHistoryPlugin';
  9. import {OnChangePlugin} from '@lexical/react/LexicalOnChangePlugin';
  10. import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
  11. import LexicalErrorBoundary from '@lexical/react/LexicalErrorBoundary';

  13. const theme = {
  14.   // Theme styling goes here
  15.   // ...
  16. }

  18. // When the editor changes, you can get notified via the
  19. // LexicalOnChangePlugin!
  20. function onChange(editorState) {
  21.   editorState.read(() => {
  22.     // Read the contents of the EditorState here.
  23.     const root = $getRoot();
  24.     const selection = $getSelection();

  26.     console.log(root, selection);
  27.   });
  28. }

  30. // Lexical React plugins are React components, which makes them
  31. // highly composable. Furthermore, you can lazy load plugins if
  32. // desired, so you don't pay the cost for plugins until you
  33. // actually use them.
  34. function MyCustomAutoFocusPlugin() {
  35.   const [editor] = useLexicalComposerContext();

  37.   useEffect(() => {
  38.     // Focus the editor when the effect fires!
  39.     editor.focus();
  40.   }, [editor]);

  42.   return null;
  43. }

  45. // Catch any errors that occur during Lexical updates and log them
  46. // or throw them as needed. If you don't throw them, Lexical will
  47. // try to recover gracefully without losing user data.
  48. function onError(error) {
  49.   console.error(error);
  50. }

  52. function Editor() {
  53.   const initialConfig = {
  54.     namespace: 'MyEditor',
  55.     theme,
  56.     onError,
  57.   };

  59.   return (
  60.     <LexicalComposer initialConfig={initialConfig}>
  61.       <PlainTextPlugin
  62.         contentEditable={<ContentEditable />}
  63.         placeholder={<div>Enter some text...</div>}
  64.         ErrorBoundary={LexicalErrorBoundary}
  65.       />
  66.       <OnChangePlugin onChange={onChange} />
  67.       <HistoryPlugin />
  68.       <MyCustomAutoFocusPlugin />
  69.     </LexicalComposer>
  70.   );
  71. }
  72. ```

Lexical is a framework


The core of Lexical is a dependency-free text editor framework that allows developers to build powerful, simple and complex,
editor surfaces. Lexical has a few concepts that are worth exploring:

Editor instances


Editor instances are the core thing that wires everything together. You can attach a contenteditable DOM element to editor instances, and also
register listeners and commands. Most importantly, the editor allows for updates to its EditorState. You can create an editor instance
using the createEditor() API, however you normally don't have to worry when using framework bindings such as @lexical/react as this
is handled for you.

Editor States


An Editor State is the underlying data model that represents what you want to show on the DOM. Editor States contain two parts:

- a Lexical node tree
- a Lexical selection object

Editor States are immutable once created, and in order to create one, you must do so via editor.update(() => {...}). However, you
can also "hook" into an existing update using node transforms or command handlers – which are invoked as part of an existing update
workflow to prevent cascading/waterfalling of updates. You can retrieve the current editor state using editor.getEditorState().

Editor States are also fully serializable to JSON and can easily be serialized back into the editor using editor.parseEditorState().

Editor Updates


When you want to change something in an Editor State, you must do it via an update, editor.update(() => {...}). The closure passed
to the update call is important. It's a place where you have full "lexical" context of the active editor state, and it exposes
access to the underlying Editor State's node tree. We promote using $ prefixed functions in this context, as it signifies a place
where they can be used exclusively. Attempting to use them outside of an update will trigger a runtime error with an appropriate error.
For those familiar with React Hooks, you can think of these as having a similar functionality (except $ functions can be used in any order).

DOM Reconciler


Lexical has its own DOM reconciler that takes a set of Editor States (always the "current" and the "pending") and applies a "diff"
on them. It then uses this diff to update only the parts of the DOM that need changing. You can think of this as a kind-of virtual DOM,
except Lexical is able to skip doing much of the diffing work, as it knows what was mutated in a given update. The DOM reconciler
adopts performance optimizations that benefit the typical heuristics of a content editable – and is able to ensure consistency for
LTR and RTL languages automatically.

Listeners, Node Transforms and Commands


Outside of invoking updates, the bulk of work done with Lexical is via listeners, node transforms and commands. These all stem from
the editor and are prefixed with register. Another important feature is that all the register methods return a function to easily unsubscribe them. For example here is how you listen to an update to a Lexical editor:

  1. ``` js
  2. const unregisterListener = editor.registerUpdateListener(({editorState}) => {
  3.   // An update has occurred!
  4.   console.log(editorState);
  5. });

  7. // Ensure we remove the listener later!
  8. unregisterListener();
  9. ```

Commands are the communication system used to wire everything together in Lexical. Custom commands can be created using createCommand() and
dispatched to an editor using editor.dispatchCommand(command, payload). Lexical dispatches commands internally when key presses are triggered
and when other important signals occur. Commands can also be handled using editor.registerCommand(handler, priority), and incoming commands are
propagated through all handlers by priority until a handler stops the propagation (in a similar way to event propagation in the browser).

Working with Lexical


This section covers how to use Lexical, independently of any framework or library. For those intending to use Lexical in their React applications,
it's advisable to [check out the source-code for the hooks that are shipped in @lexical/react](https://github.com/facebook/lexical/tree/main/packages/lexical-react/src).

Creating an editor and using it


When you work with Lexical, you normally work with a single editor instance. An editor instance can be thought of as the one responsible
for wiring up an EditorState with the DOM. The editor is also the place where you can register custom nodes, add listeners, and transforms.

An editor instance can be created from the lexical package and accepts an optional configuration object that allows for theming and other options:

  1. ``` js
  2. import {createEditor} from 'lexical';

  4. const config = {
  5.   namespace: 'MyEditor',
  6.   theme: {
  7.     ...
  8.   },
  9. };

  11. const editor = createEditor(config);
  12. ```

Once you have an editor instance, when ready, you can associate the editor instance with a content editable `
` element in your document:

  1. ``` js
  2. const contentEditableElement = document.getElementById('editor');

  4. editor.setRootElement(contentEditableElement);
  5. ```

If you want to clear the editor instance from the element, you can pass null. Alternatively, you can switch to another element if need be,
just pass an alternative element reference to setRootElement().

Working with Editor States


With Lexical, the source of truth is not the DOM, but rather an underlying state model
that Lexical maintains and associates with an editor instance. You can get the latest
editor state from an editor by calling editor.getEditorState().

Editor states are serializable to JSON, and the editor instance provides a useful method
to deserialize stringified editor states.

  1. ``` js
  2. const stringifiedEditorState = JSON.stringify(editor.getEditorState().toJSON());

  4. const newEditorState = editor.parseEditorState(stringifiedEditorState);
  5. ```

Updating an editor


There are a few ways to update an editor instance:

- Trigger an update with editor.update()
- Setting the editor state via editor.setEditorState()
- Applying a change as part of an existing update via editor.registerNodeTransform()
- Using a command listener with editor.registerCommand(EXAMPLE_COMMAND, () => {...}, priority)

The most common way to update the editor is to use editor.update(). Calling this function
requires a function to be passed in that will provide access to mutate the underlying
editor state. When starting a fresh update, the current editor state is cloned and
used as the starting point. From a technical perspective, this means that Lexical leverages a technique
called double-buffering during updates. There's an editor state to represent what is current on
the screen, and another work-in-progress editor state that represents future changes.

Creating an update is typically an async process that allows Lexical to batch multiple updates together in
a single update – improving performance. When Lexical is ready to commit the update to
the DOM, the underlying mutations and changes in the update will form a new immutable
editor state. Calling editor.getEditorState() will then return the latest editor state
based on the changes from the update.

Here's an example of how you can update an editor instance:

  1. ``` js
  2. import {$getRoot, $getSelection, $createParagraphNode} from 'lexical';

  4. // Inside the `editor.update` you can use special $ prefixed helper functions.
  5. // These functions cannot be used outside the closure, and will error if you try.
  6. // (If you're familiar with React, you can imagine these to be a bit like using a hook
  7. // outside of a React function component).
  8. editor.update(() => {
  9.   // Get the RootNode from the EditorState
  10.   const root = $getRoot();

  12.   // Get the selection from the EditorState
  13.   const selection = $getSelection();

  15.   // Create a new ParagraphNode
  16.   const paragraphNode = $createParagraphNode();

  18.   // Create a new TextNode
  19.   const textNode = $createTextNode('Hello world');

  21.   // Append the text node to the paragraph
  22.   paragraphNode.append(textNode);

  24.   // Finally, append the paragraph to the root
  25.   root.append(paragraphNode);
  26. });
  27. ```

If you want to know when the editor updates so you can react to the changes, you can add an update
listener to the editor, as shown below:

  1. ``` js
  2. editor.registerUpdateListener(({editorState}) => {
  3.   // The latest EditorState can be found as `editorState`.
  4.   // To read the contents of the EditorState, use the following API:

  6.   editorState.read(() => {
  7.     // Just like editor.update(), .read() expects a closure where you can use
  8.     // the $ prefixed helper functions.
  9.   });
  10. });
  11. ```

Creating custom Lexical nodes


- Creating custom decorator nodes

Contributing to Lexical


1. Clone this repository

2. Install dependencies

   - npm install

3. Start local server and run tests
   - npm run start
   - npm run test-e2e-chromium to run only chromium e2e tests
     - The server needs to be running for the e2e tests

npm run start will start both the dev server and collab server. If you don't need collab, use npm run dev to start just the dev server.

Optional but recommended, use VSCode for development


1.  Download and install VSCode

    - Download from here (it’s recommended to use the unmodified version)

2.  Install extensions
    - Flow Language Support
      - Make sure to follow the setup steps in the README
    - Prettier
      - Set prettier as the default formatter in editor.defaultFormatter
      - Optional: set format on save editor.formatOnSave
    - ESlint

Documentation


- How Lexical was designed
- Testing

Browser Support


- Firefox 52+
- Chrome 49+
- Edge 79+ (when Edge switched to Chromium)
- Safari 11+
- iOS 11+ (Safari)
- iPad OS 13+ (Safari)
- Android Chrome 72+

Note: Lexical does not support Internet Explorer or legacy versions of Edge.

Contributing


1. Create a new branch
   - git checkout -b my-new-branch
2. Commit your changes
   - git commit -a -m 'Description of the changes'
     - There are many ways of doing this and this is just a suggestion
3. Push your branch to GitHub
   - git push origin my-new-branch
4. Go to the repository page in GitHub and click on "Compare & pull request"
   - The GitHub CLI allows you to skip the web interface for this step (and much more)

Support


If you have any questions about Lexical, would like to discuss a bug report, or have questions about new integrations, feel free to join us at our Discord server.

Lexical engineers are checking this regularly.

Running tests


- npm run test-unit runs only unit tests.
- npm run test-e2e-chromium runs only chromium e2e tests.
- npm run debug-test-e2e-chromium runs only chromium e2e tests in head mode for debugging.
- npm run test-e2e-firefox runs only firefox e2e tests.
- npm run debug-test-e2e-firefox runs only firefox e2e tests in head mode for debugging.
- npm run test-e2e-webkit runs only webkit e2e tests.
- npm run debug-test-e2e-webkit runs only webkit e2e tests in head mode for debugging.

License


Lexical is MIT licensed.