API Reference - @liveblocks/react-lexical

@liveblocks/react-lexical provides you with a React plugin that adds collaboration to any Lexical text editor. It also adds realtime cursors, document persistence on the cloud, comments, and mentions. Read our get started guides to learn more.

Setup

To set up your collaborative Lexical editor, you must use LiveblocksPlugin and liveblocksConfig.

LiveblocksPlugin

Liveblocks plugin for Lexical that adds collaboration to your editor.

<LexicalComposer initialConfig={initialConfig}>  <LiveblocksPlugin /></LexicalComposer>

LiveblocksPlugin should always be nested inside LexicalComposer, and each Lexical default component you’re using should be placed inside the plugin.

import { LexicalComposer } from "@lexical/react/LexicalComposer";import { RichTextPlugin } from "@lexical/react/LexicalRichTextPlugin";import { ContentEditable } from "@lexical/react/LexicalContentEditable";import { LexicalErrorBoundary } from "@lexical/react/LexicalErrorBoundary";import { liveblocksConfig, LiveblocksPlugin } from "@liveblocks/react-lexical";
const initialConfig = liveblocksConfig({  namespace: "MyEditor",  theme: {},  nodes: [],  onError: (err) => console.error(err),});
function Editor() {  return (    <LexicalComposer initialConfig={initialConfig}>      <LiveblocksPlugin>        <FloatingThreads />        <FloatingComposer />        <AnchoredThreads />      </LiveblocksPlugin>      <RichTextPlugin        contentEditable={<ContentEditable />}        placeholder={<div>Enter some text...</div>}        ErrorBoundary={LexicalErrorBoundary}      />    </LexicalComposer>  );}

Learn more in our get started guides.

liveblocksConfig

Function that takes a Lexical editor config and modifies it to add the necessary nodes and theme to make LiveblocksPlugin works correctly.

import { liveblocksConfig } from "@liveblocks/react-lexical";
const initialConfig = liveblocksConfig({  namespace: "MyEditor",  theme: {},  nodes: [],  onError: (err) => console.error(err),});

The config created by liveblocksConfig should be passed to initialConfig in LexicalComposer.

import { LexicalComposer } from "@lexical/react/LexicalComposer";import { RichTextPlugin } from "@lexical/react/LexicalRichTextPlugin";import { ContentEditable } from "@lexical/react/LexicalContentEditable";import { LexicalErrorBoundary } from "@lexical/react/LexicalErrorBoundary";import { liveblocksConfig, LiveblocksPlugin } from "@liveblocks/react-lexical";
const initialConfig = liveblocksConfig({  namespace: "MyEditor",  theme: {},  nodes: [],  onError: (err) => console.error(err),});
function Editor() {  return (    <LexicalComposer initialConfig={initialConfig}>      <LiveblocksPlugin>        <FloatingThreads />        <FloatingComposer />        <AnchoredThreads />      </LiveblocksPlugin>      <RichTextPlugin        contentEditable={<ContentEditable />}        placeholder={<div>Enter some text...</div>}        ErrorBoundary={LexicalErrorBoundary}      />    </LexicalComposer>  );}

Note that liveblocksConfig sets editorState to null because LiveblocksPlugin is responsible for initializing it on the server.

Default components

Toolbar

Displays a toolbar, allowing you to change the styles of selected text. You can add content before or after, or the toolbar’s options can be customized. A floating toolbar also exists.

<LexicalComposer initialConfig={initialConfig}>  <LiveblocksPlugin>    <Toolbar />  </LiveblocksPlugin></LexicalComposer>
Toolbar

By default, one of the toolbar buttons can create comment threads—to enable this add FloatingComposer and display threads with AnchoredThreads or FloatingThreads. Should be nested inside LiveblocksPlugin.

import { LexicalComposer } from "@lexical/react/LexicalComposer";import { RichTextPlugin } from "@lexical/react/LexicalRichTextPlugin";import { ContentEditable } from "@lexical/react/LexicalContentEditable";import { LexicalErrorBoundary } from "@lexical/react/LexicalErrorBoundary";import { useThreads } from "@liveblocks/react/suspense";import {  liveblocksConfig,  LiveblocksPlugin,  FloatingComposer,  Toolbar,} from "@liveblocks/react-lexical";
const initialConfig = liveblocksConfig({  namespace: "MyEditor",  theme: {},  nodes: [],  onError: (err) => console.error(err),});
function Editor() {  const { threads } = useThreads();
  return (    <LexicalComposer initialConfig={initialConfig}>      <LiveblocksPlugin>        <Toolbar />        <FloatingComposer style={{ width: "350px" }} />        <FloatingThreads threads={threads} style={{ width: "350px" }} />      </LiveblocksPlugin>      <RichTextPlugin        contentEditable={<ContentEditable />}        placeholder={<div>Enter some text...</div>}        ErrorBoundary={LexicalErrorBoundary}      />    </LexicalComposer>  );}

Extending the defaults

You can insert content before the first button and after the last button using before and after. Components such as Toolbar.Button and Toolbar.Toggle can be used to create new buttons.

import { Toolbar } from "@liveblocks/react-lexical";import { Icon } from "@liveblocks/react-ui";
<Toolbar  before={<>I'm at the start</>}  after={    <Toolbar.Button      name="Help"      icon={<Icon.QuestionMark />}      shortcut="CMD-H"      onClick={() => console.log("help")}    />  }/>;

For more complex customization, instead read creating a custom floating toolbar.

Creating a custom toolbar

By passing elements as children, it’s possible to create a fully custom toolbar.

import { Toolbar } from "@liveblocks/react-lexical";
function CustomToolbar() {  return (    <Toolbar>      Hello <strong>world</strong>    </Toolbar>  );}

Each part of our default toolbar is available as blocks which can be slotted together. This is how the default toolbar is constructed:

import { Toolbar } from "@liveblocks/react-lexical";
function CustomToolbar() {  return (    <Toolbar>      <Toolbar.BlockSelector />      <Toolbar.SectionInline />      <Toolbar.Separator />      <Toolbar.SectionCollaboration />    </Toolbar>  );}

You can mix these default components with any custom ones of your own. Below the Toolbar.SectionHistory component is added alongside some custom buttons created with Toolbar.Button, Toolbar.Toggle, and Icon.

import { FORMAT_TEXT_COMMAND } from "lexical";import { useLexicalComposerContext } from "@lexical/react/LexicalComposerContext";import { isTextFormatActive, Toolbar } from "@liveblocks/react-lexical";import { Icon } from "@liveblocks/react-ui";
function CustomToolbar() {  const [editor] = useLexicalComposerContext();
  return (    <Toolbar>      <Toolbar.SectionHistory />      <Toolbar.Separator />      <Toolbar.Button        name="Help"        icon={<Icon.QuestionMark />}        shortcut="CMD-H"        onClick={() => console.log("help")}      />      <Toolbar.Toggle        name="Bold"        icon={<strong>B️</strong>}        active={isTextFormatActive(editor, "bold")}        onClick={() => editor.dispatchCommand(FORMAT_TEXT_COMMAND, "bold")}      />    </Toolbar>  );}

To learn more about the different components, read more below.

Props

  • editorLexicalEditorRequired

    The Lexical editor.

  • childrenReactNode

    The content of the toolbar, overriding the default content. Use the before and after props if you want to keep and extend the default content. Any ReactNode or Toolbar.* components work inside.

  • beforeReactNode

    The content to display at the start of the toolbar. Any ReactNode or Toolbar.* components work inside.

  • afterReactNode

    The content to display at the end of the toolbar. Any ReactNode or Toolbar.* components work inside.

Toolbar.Button

A button for triggering actions. The name is displayed in a tooltip. Props such as onClick will be passed to the underlying button element.

import { Toolbar } from "@liveblocks/react-lexical";
<Toolbar>  <Toolbar.Button name="Question" onClick={(e) => console.log("Clicked")} /></Toolbar>;

Optionally takes an icon which will visually replace the name. Also optionally accepts a shortcut, which is displayed in the tooltip. Comment key names are converted to symbols. Here are various examples.

import { Toolbar } from "@liveblocks/react-lexical";import { Icon } from "@liveblocks/react-ui";
// Button says "Question"<Toolbar.Toggle name="Question" onClick={/* ... */} />
// Tooltip says "Question [⌘+Q]"<Toolbar.Button name="Question" shortcut="CMD+Q" onClick={/* ... */} />
// Custom icon, replaces the name in the button<Toolbar.Button name="Question" icon={<div>?</div>} onClick={/* ... */} />
// Using a Liveblocks icon, replaces the name in the button<Toolbar.Button name="Question" icon={<Icon.QuestionMark />} onClick={/* ... */} />
// Passing children visually replaces the `name` and `icon`<Toolbar.Button name="Question" onClick={/* ... */}>  ? Ask a question</Toolbar.Button>
// Props are passed to the inner `button`<Toolbar.Button  name="Question"  style={{ marginLeft: 10 }}  className="custom-button"  onMouseOver={() => console.log("Hovered")}/>
Props
  • namestringRequired

    The name of this button displayed in its tooltip. Will also be displayed in the button if no icon or children are passed.

  • iconReactNode

    An optional icon displayed in this button.

  • shortcutstring

    An optional keyboard shortcut displayed in this button’s tooltip. Common shortcuts such will be replaced by their symbols, for example CMD → ⌘.

Toolbar.Toggle

A toggle button for values that can be active or inactive. Best used with text editor commands. The name is displayed in a tooltip. Props will be passed to the underlying button element.

import { FORMAT_TEXT_COMMAND } from "lexical";import { isTextFormatActive, Toolbar } from "@liveblocks/react-lexical";
<Toolbar>  <Toolbar.Toggle    name="Highlight"    active={isTextFormatActive(editor, "bold")}    onClick={() => editor.dispatchCommand(FORMAT_TEXT_COMMAND, "bold")}  /></Toolbar>;

The snippet above shows how to toggle bold styling. The toggle button can also be toggled with useState.

import { Toolbar } from "@liveblocks/react-lexical";import { useState } from "react";
function CustomToggle() {  const [active, setActive] = useState(false);
  return (    <Toolbar.Toggle      name="Toggle options"      active={active}      onClick={() => setActive(!active)}    />  );}

Toolbar.Toggle optionally takes an icon which will visually replace the name. Also optionally accepts a shortcut, which is displayed in the tooltip. Comment key names are converted to symbols. Here are various examples.

import { Toolbar } from "@liveblocks/react-lexical";import { Icon } from "@liveblocks/react-ui";
// Button says "Highlight"<Toolbar.Toggle  name="Highlight"  active={/* ... */}  onClick={/* ... */}/>
// Tooltip says "Highlight [⌘+H]"<Toolbar.Toggle  name="Highlight"  shortcut="CMD+H"  active={/* ... */}  onClick={/* ... */}/>
// Custom icon, replaces the name in the button<Toolbar.Toggle  name="Highlight"  icon={<div>🖊</div>}  active={/* ... */}  onClick={/* ... */}/>
// Using a Liveblocks icon, replaces the name in the button<Toolbar.Toggle  name="Highlight"  icon={<Icon.QuestionMark />}  active={/* ... */}  onClick={/* ... */}/>
// Passing children visually replaces the `name` and `icon`<Toolbar.Toggle  name="Highlight"  active={/* ... */}  onClick={/* ... */}>  🖊️Highlight</Toolbar.Toggle>
// Props are passed to the inner `button`<Toolbar.Toggle  name="Highlight"  active={/* ... */}  onClick={/* ... */}  style={{ marginLeft: 10 }}  className="custom-toggle"  onMouseOver={() => console.log("Hovered")}/>
Props
  • namestringRequired

    The name of this button displayed in its tooltip. Will also be displayed in the button if no icon or children are passed.

  • activebooleanRequired

    Whether the button is toggled.

  • iconReactNode

    An optional icon displayed in this button.

  • shortcutstring

    An optional keyboard shortcut displayed in this button’s tooltip. Common shortcuts such will be replaced by their symbols, for example CMD → ⌘.

Toolbar.BlockSelector

Adds a dropdown selector for switching between different block types, such as text, heading 1, blockquote. Props will be passed to the inner button element. Can also be placed inside FloatingToolbar.

import { Toolbar } from "@liveblocks/react-lexical";
<Toolbar>  <Toolbar.BlockSelector /></Toolbar>;
Use custom item options

If you’d like to change the items shown in the dropdown menu, you can pass a custom items array. Below a code block item (Lexical extension) is added after the default options.

import { isBlockNodeActive, Toolbar } from "@liveblocks/react-lexical";import { $setBlocksType } from "@lexical/selection";import { $isCodeNode } from "@lexical/code";import { $getSelection } from "lexical";
<Toolbar>  <Toolbar.BlockSelector    items={(defaultItems) => [      ...defaultItems,      {        name: "Code block",        icon: <div>❮ ❯</div>, // Optional        isActive: (editor) => isBlockNodeActive(editor, $isCodeNode),        setActive: (editor) =>          $setBlocksType($getSelection(), () => $createCodeNode()),      },    ]}  /></Toolbar>;
Customize item styles

By passing a label property, you can overwrite the styles of the dropdown items. The toolbar button will still display the name, but in the dropdown, the label will be used instead of the name and icon. Below, a new item is added and its label is customized.

import { isBlockNodeActive, Toolbar } from "@liveblocks/react-lexical";import { $setBlocksType } from "@lexical/selection";import { $isCodeNode } from "@lexical/code";import { $getSelection } from "lexical";
<Toolbar>  <Toolbar.BlockSelector    items={(defaultItems) => [      ...defaultItems,      {        name: "Code block",        label: <div className="font-mono">Code</div>, // Optional, overwrites `icon` + `name`        isActive: (editor) => isBlockNodeActive(editor, $isCodeNode),        setActive: (editor) =>          $setBlocksType($getSelection(), () => $createCodeNode()),      },    ]}  /></Toolbar>;

You can also customize the default items. Below each item is styled to represent the effect each block applies to the document.

import { Toolbar } from "@liveblocks/react-lexical";
<Toolbar.BlockSelector  items={(defaultItems) =>    defaultItems.map((item) => {      let label;
      if (item.name === "Text") {        label = <span>Regular text</span>;      }
      if (item.name === "Heading 1") {        label = (          <span style={{ fontSize: 18, fontWeight: "bold" }}>Heading 1</span>        );      }
      if (item.name === "Heading 2") {        label = (          <span style={{ fontSize: 16, fontWeight: "bold" }}>Heading 2</span>        );      }
      if (item.name === "Heading 3") {        label = (          <span style={{ fontSize: 15, fontWeight: "bold" }}>Heading 3</span>        );      }
      if (item.name === "Blockquote") {        label = (          <span style={{ borderLeft: "3px solid gray", paddingLeft: 8 }}>            Blockquote          </span>        );      }
      return {        ...item,        label,        icon: null, // Hide all icons      };    })  }/>;
Props
  • itemsarray | function

    The items displayed in this block selector. When provided as an array, the default items are overridden. To avoid this, a function can be provided instead and it will receive the default items.

Toolbar.Separator

Adds a visual, and accessible, separator used to separate sections in the toolbar. Props will be passed to the inner div element. Can also be placed inside FloatingToolbar.

import { Toolbar } from "@liveblocks/react-lexical";
<Toolbar>  <Toolbar.SectionHistory /></Toolbar>;

Toolbar.SectionHistory

Adds a section containing undo and redo buttons. Can also be placed inside FloatingToolbar.

import { Toolbar } from "@liveblocks/react-lexical";
<Toolbar>  <Toolbar.SectionHistory /></Toolbar>;

Toolbar.SectionInline

Adds a section containing inline formatting actions such as bold, italic, underline. Can also be placed inside FloatingToolbar.

import { Toolbar } from "@liveblocks/react-lexical";
<Toolbar>  <Toolbar.SectionInline /></Toolbar>;

Toolbar.SectionCollaboration

Adds a section containing an add comment button. Can also be placed inside FloatingToolbar.

import { Toolbar } from "@liveblocks/react-lexical";
<Toolbar>  <Toolbar.SectionCollaboration /></Toolbar>;

FloatingToolbar

Displays a floating toolbar near the current Lexical selection, allowing you to change styles. You can add content before or after, or the toolbar’s options can be customized. A static toolbar also exists.

<LexicalComposer initialConfig={initialConfig}>  <LiveblocksPlugin>    <FloatingToolbar />  </LiveblocksPlugin></LexicalComposer>
FloatingToolbar

By default, one of the toolbar buttons can create comment threads—to enable this add FloatingComposer and display threads with AnchoredThreads or FloatingThreads. Should be nested inside LiveblocksPlugin.

import { LexicalComposer } from "@lexical/react/LexicalComposer";import { RichTextPlugin } from "@lexical/react/LexicalRichTextPlugin";import { ContentEditable } from "@lexical/react/LexicalContentEditable";import { LexicalErrorBoundary } from "@lexical/react/LexicalErrorBoundary";import { useThreads } from "@liveblocks/react/suspense";import {  liveblocksConfig,  LiveblocksPlugin,  FloatingComposer,  FloatingToolbar,} from "@liveblocks/react-lexical";
const initialConfig = liveblocksConfig({  namespace: "MyEditor",  theme: {},  nodes: [],  onError: (err) => console.error(err),});
function Editor() {  const { threads } = useThreads();
  return (    <LexicalComposer initialConfig={initialConfig}>      <LiveblocksPlugin>        <FloatingToolbar />        <FloatingComposer style={{ width: "350px" }} />        <FloatingThreads threads={threads} style={{ width: "350px" }} />      </LiveblocksPlugin>      <RichTextPlugin        contentEditable={<ContentEditable />}        placeholder={<div>Enter some text...</div>}        ErrorBoundary={LexicalErrorBoundary}      />    </LexicalComposer>  );}

Changing float position

Using position and offset you can reposition the toolbar relative to the current selection. position can be set to "top" or "bottom", and offset defines the vertical distance in pixels from the selection.

<FloatingToolbar  position="bottom" // Position can be `top` or `bottom`  offset={12} // Distance in px from selection/>

Extending the defaults

You can insert custom content before the first button and after the last button using before and after. Components such as Toolbar.Button and Toolbar.Toggle can be used to create new buttons.

import { FloatingToolbar } from "@liveblocks/react-lexical";import { Icon } from "@liveblocks/react-ui";
<FloatingToolbar  before={<>I'm at the start</>}  after={    <Toolbar.Button      name="Help"      icon={<Icon.QuestionMark />}      shortcut="CMD-H"      onClick={() => console.log("help")}    />  }/>;

For more complex customization, instead read creating a custom floating toolbar.

Creating a custom floating toolbar

By passing elements as children, it’s possible to create a fully custom floating toolbar.

import { FloatingToolbar } from "@liveblocks/react-lexical";
function CustomToolbar() {  return (    <FloatingToolbar>      Hello <strong>world</strong>    </FloatingToolbar>  );}

Each part of our default toolbar is available as blocks which can be slotted together. This is how the default floating toolbar is constructed:

import { FloatingToolbar } from "@liveblocks/react-lexical";
function CustomToolbar() {  return (    <FloatingToolbar>      <Toolbar.BlockSelector />      <Toolbar.SectionInline />      <Toolbar.Separator />      <Toolbar.SectionCollaboration />    </FloatingToolbar>  );}

You can mix these default components with any custom ones of your own. Below the Toolbar.SectionHistory component is added alongside some custom buttons created with Toolbar.Button, Toolbar.Toggle, and Icon.

import { FORMAT_TEXT_COMMAND } from "lexical";import { useLexicalComposerContext } from "@lexical/react/LexicalComposerContext";import { isTextFormatActive, FloatingToolbar } from "@liveblocks/react-lexical";import { Icon } from "@liveblocks/react-ui";
function CustomToolbar() {  const [editor] = useLexicalComposerContext();
  return (    <FloatingToolbar>      <Toolbar.SectionHistory />      <Toolbar.Separator />      <Toolbar.Button        name="Help"        icon={<Icon.QuestionMark />}        shortcut="CMD-H"        onClick={() => console.log("help")}      />      <Toolbar.Toggle        name="Bold"        icon={<strong>B️</strong>}        active={isTextFormatActive(editor, "bold")}        onClick={() => editor.dispatchCommand(FORMAT_TEXT_COMMAND, "bold")}      />    </FloatingToolbar>  );}

To learn more about the different components, read more under Toolbar.

Props

  • editorLexicalEditorRequired

    The Lexical editor.

  • position"top" | "bottom"

    The vertical position of the floating toolbar.

  • offsetnumber

    The vertical offset of the floating toolbar from the selection.

  • childrenReactNode

    The content of the toolbar, overriding the default content. Use the before and after props if you want to keep and extend the default content. Any ReactNode or Toolbar.* components work inside.

  • beforeReactNode

    The content to display at the start of the toolbar. Any ReactNode or Toolbar.* components work inside.

  • afterReactNode

    The content to display at the end of the toolbar. Any ReactNode or Toolbar.* components work inside.

FloatingComposer

Displays a Composer near the current Lexical selection, allowing you to create threads.

<LexicalComposer initialConfig={initialConfig}>  <LiveblocksPlugin>    <FloatingComposer />  </LiveblocksPlugin></LexicalComposer>
FloatingComposer

Submitting a comment will attach an annotation thread at the current selection. Should be nested inside LiveblocksPlugin.

import { LexicalComposer } from "@lexical/react/LexicalComposer";import { RichTextPlugin } from "@lexical/react/LexicalRichTextPlugin";import { ContentEditable } from "@lexical/react/LexicalContentEditable";import { LexicalErrorBoundary } from "@lexical/react/LexicalErrorBoundary";import {  liveblocksConfig,  LiveblocksPlugin,  FloatingComposer,} from "@liveblocks/react-lexical";
const initialConfig = liveblocksConfig({  namespace: "MyEditor",  theme: {},  nodes: [],  onError: (err) => console.error(err),});
function Editor() {  return (    <LexicalComposer initialConfig={initialConfig}>      <LiveblocksPlugin>        <FloatingComposer style={{ width: "350px" }} />      </LiveblocksPlugin>      <RichTextPlugin        contentEditable={<ContentEditable />}        placeholder={<div>Enter some text...</div>}        ErrorBoundary={LexicalErrorBoundary}      />    </LexicalComposer>  );}

Display created threads with AnchoredThreads or FloatingThreads.

Opening the composer

To open the FloatingComposer, you need to dispatch the OPEN_FLOATING_COMPOSER_COMMAND Lexical command.

import { useLexicalComposerContext } from "@lexical/react/LexicalComposerContext";import { OPEN_FLOATING_COMPOSER_COMMAND } from "@liveblocks/react-lexical";
function Toolbar() {  const [editor] = useLexicalComposerContext();
  return (    <button      onClick={() => {        editor.dispatchCommand(OPEN_FLOATING_COMPOSER_COMMAND, undefined);      }}    >      💬 New comment    </button>  );}

Props

  • metadataThreadMetadata

    The metadata of the thread to create.

  • onComposerSubmitfunction

    The event handler called when the composer is submitted.

  • defaultValueCommentBody

    The composer’s initial value.

  • collapsedboolean

    Whether the composer is collapsed. Setting a value will make the composer controlled.

  • onCollapsedChangefunction

    The event handler called when the collapsed state of the composer changes.

  • defaultCollapsedboolean

    Whether the composer is initially collapsed. Setting a value will make the composer uncontrolled.

  • disabledboolean

    Whether the composer is disabled.

  • autoFocusboolean

    Whether to focus the composer on mount.

  • overridesPartial<GlobalOverrides & ComposerOverrides>

    Override the component’s strings.

FloatingThreads

Displays floating Thread components below text highlights in the editor.

<LexicalComposer initialConfig={initialConfig}>  <LiveblocksPlugin>    <FloatingThreads threads={threads} />  </LiveblocksPlugin></LexicalComposer>
FloatingThreads

Takes a list of threads retrieved from useThreads and renders them to the page. Each thread is opened by clicking on its corresponding text highlight.

import { LexicalComposer } from "@lexical/react/LexicalComposer";import { RichTextPlugin } from "@lexical/react/LexicalRichTextPlugin";import { ContentEditable } from "@lexical/react/LexicalContentEditable";import { LexicalErrorBoundary } from "@lexical/react/LexicalErrorBoundary";import { useThreads } from "@liveblocks/react/suspense";import {  liveblocksConfig,  LiveblocksPlugin,  FloatingComposer,  FloatingThreads,} from "@liveblocks/react-lexical";
const initialConfig = liveblocksConfig({  namespace: "MyEditor",  theme: {},  nodes: [],  onError: (err) => console.error(err),});
function Editor() {  const { threads } = useThreads();
  return (    <LexicalComposer initialConfig={initialConfig}>      <LiveblocksPlugin>        <FloatingComposer />        <FloatingThreads threads={threads} style={{ width: "350px" }} />      </LiveblocksPlugin>      <RichTextPlugin        contentEditable={<ContentEditable />}        placeholder={<div>Enter some text...</div>}        ErrorBoundary={LexicalErrorBoundary}      />    </LexicalComposer>  );}

Should be nested inside LiveblocksPlugin.

Recommended usage

FloatingThreads and AnchoredThreads have been designed to work together to provide the optimal experience on mobile and desktop. We generally recommend using both components, hiding one on smaller screens, as we are below with Tailwind classes. Most apps also don’t need to display resolved threads, so we can filter those out with a useThreads option.

import { useThreads } from "@liveblocks/react/suspense";import { AnchoredThreads, FloatingThreads } from "@liveblocks/react-lexical";
function ThreadOverlay() {  const { threads } = useThreads({ query: { resolved: false } });
  return (    <>      <FloatingThreads        threads={threads}        className="w-[350px] block md:hidden"      />      <AnchoredThreads        threads={threads}        className="w-[350px] hidden sm:block"      />    </>  );}

We can place this component inside ClientSideSuspense to prevent it rendering until threads have loaded.

<LexicalComposer initialConfig={initialConfig}>  <LiveblocksPlugin>    <FloatingComposer />    <ClientSideSuspense fallback={null}>      <ThreadOverlay />    </ClientSideSuspense>  </LiveblocksPlugin></LexicalComposer>

Customization

The FloatingThreads component acts as a wrapper around each individual Thread. You can treat the component like you would a div, using classes, listeners, and more.

<FloatingThreads threads={threads} className="my-floating-thread" />

To apply styling to each Thread, you can pass a custom Thread property to components and modify this in any way. This is the best way to modify a thread’s width.

import { Thread } from "@liveblocks/react-ui";
<FloatingThreads  threads={threads}  className="my-floating-thread"  components={{    Thread: (props) => (      <Thread {...props} className="border shadow" style={{ width: "300px" }} />    ),  }}/>;

You can return any custom ReactNode here, including anything from a simple wrapper around Thread, up to a full custom Thread component built using our Comment primitives.

import { Comment } from "@liveblocks/react-ui/primitives";
<FloatingThreads  threads={threads}  className="my-floating-thread"  components={{    Thread: (props) => (      <div>        {props.thread.comments.map((comment) => (          <Comment.Body            key={comment.id}            body={comment.body}            components={/* ... */}          />        ))}      </div>    ),  }}/>;

Props

  • threadsThreadData[]Required

    The threads to display.

  • componentsPartial<AnchoredThreadsComponents>

    Override the component’s components.

  • components.Thread(props: ThreadProps) => ReactNode

    Override the Thread component.

AnchoredThreads

Displays a list of Thread components vertically alongside the editor.

<LexicalComposer initialConfig={initialConfig}>  <LiveblocksPlugin>    <AnchoredThreads threads={threads} />  </LiveblocksPlugin></LexicalComposer>
AnchoredThreads

Takes a list of threads retrieved from useThreads and renders them to the page. Each thread is displayed at the same vertical coordinates as its corresponding text highlight. If multiple highlights are in the same location, each thread is placed in order below the previous thread.

import { LexicalComposer } from "@lexical/react/LexicalComposer";import { RichTextPlugin } from "@lexical/react/LexicalRichTextPlugin";import { ContentEditable } from "@lexical/react/LexicalContentEditable";import { LexicalErrorBoundary } from "@lexical/react/LexicalErrorBoundary";import { useThreads } from "@liveblocks/react/suspense";import {  liveblocksConfig,  LiveblocksPlugin,  FloatingComposer,  AnchoredThreads,} from "@liveblocks/react-lexical";
const initialConfig = liveblocksConfig({  namespace: "MyEditor",  theme: {},  nodes: [],  onError: (err) => console.error(err),});
function Editor() {  const { threads } = useThreads();
  return (    <LexicalComposer initialConfig={initialConfig}>      <LiveblocksPlugin>        <FloatingComposer />        <AnchoredThreads threads={threads} style={{ width: "350px" }} />      </LiveblocksPlugin>      <RichTextPlugin        contentEditable={<ContentEditable />}        placeholder={<div>Enter some text...</div>}        ErrorBoundary={LexicalErrorBoundary}      />    </LexicalComposer>  );}

Should be nested inside LiveblocksPlugin.

Recommended usage

FloatingThreads and AnchoredThreads have been designed to work together to provide the optimal experience on mobile and desktop. We generally recommend using both components, hiding one on smaller screens, as we are below with Tailwind classes. Most apps also don’t need to display resolved threads, so we can filter those out with a useThreads option.

import { useThreads } from "@liveblocks/react/suspense";import { AnchoredThreads, FloatingThreads } from "@liveblocks/react-lexical";
function ThreadOverlay() {  const { threads } = useThreads({ query: { resolved: false } });
  return (    <>      <FloatingThreads        threads={threads}        className="w-[350px] block md:hidden"      />      <AnchoredThreads        threads={threads}        className="w-[350px] hidden sm:block"      />    </>  );}

We can place this component inside ClientSideSuspense to prevent it rendering until threads have loaded.

<LexicalComposer initialConfig={initialConfig}>  <LiveblocksPlugin>    <FloatingComposer />    <ClientSideSuspense fallback={null}>      <ThreadOverlay />    </ClientSideSuspense>  </LiveblocksPlugin></LexicalComposer>

Customization

The AnchoredThreads component acts as a wrapper around each Thread. It has no width, so setting this is required, and each thread will take on the width of the wrapper. You can treat the component like you would a div, using classes, listeners, and more.

<AnchoredThreads  threads={threads}  style={{ width: "350px" }}  className="my-anchored-thread"/>

To apply styling to each Thread, you can pass a custom Thread property to components and modify this in any way.

import { Thread } from "@liveblocks/react-ui";
<AnchoredThreads  threads={threads}  style={{ width: "350px" }}  className="my-anchored-thread"  components={{    Thread: (props) => (      <Thread        {...props}        className="border shadow"        style={{ background: "white" }}      />    ),  }}/>;

You can return any custom ReactNode here, including anything from a simple wrapper around Thread, up to a full custom Thread component built using our Comment primitives.

import { Comment } from "@liveblocks/react-ui/primitives";
<AnchoredThreads  threads={threads}  style={{ width: "350px" }}  className="my-anchored-thread"  components={{    Thread: (props) => (      <div>        {props.thread.comments.map((comment) => (          <Comment.Body            key={comment.id}            body={comment.body}            components={/* ... */}          />        ))}      </div>    ),  }}/>;
Modifying thread floating positions

Using CSS variables you can modify the gap between threads, and the horizontal offset that’s added when a thread is selected.

.lb-lexical-anchored-threads {  /* Minimum gap between threads */  --lb-lexical-anchored-threads-gap: 8px;
  /* How far the active thread is offset to the left */  --lb-lexical-anchored-threads-active-thread-offset: 12px;}

Props

  • threadsThreadData[]Required

    The threads to display.

  • componentsPartial<AnchoredThreadsComponents>

    Override the component’s components.

  • components.Thread(props: ThreadProps) => ReactNode

    Override the Thread component.

HistoryVersionPreview

The HistoryVersionPreview component allows you to display a preview of a specific version of your Lexical editor's content. It also contains a button and logic for restoring. It must be used inside the <LiveblocksPlugin> context. To render a list of versions, see VersionHistory.

Usage

import { HistoryVersionPreview } from "@liveblocks/react-lexical";
function VersionPreview({ selectedVersion, onVersionRestore }) {  return (    <HistoryVersionPreview      version={selectedVersion}      onVersionRestore={onVersionRestore}    />  );}

Props

  • versionHistoryVersionRequired

    The version of the editor content to preview.

  • onVersionRestore(version: HistoryVersion) => void

    Callback function called when the user chooses to restore this version.

The HistoryVersionPreview component renders a read-only view of the specified version of the editor content. It also provides a button for users to restore the displayed version.

Hooks

useIsEditorReady

Used to check if the editor content has been loaded or not, helpful for displaying a loading skeleton.

import { useIsEditorReady } from "@liveblocks/react-lexical";
const status = useIsEditorReady();

Here’s how it can be used in the context of your editor.

import { LexicalComposer } from "@lexical/react/LexicalComposer";import { RichTextPlugin } from "@lexical/react/LexicalRichTextPlugin";import { ContentEditable } from "@lexical/react/LexicalContentEditable";import { LexicalErrorBoundary } from "@lexical/react/LexicalErrorBoundary";import {  liveblocksConfig,  LiveblocksPlugin,  useIsEditorReady,} from "@liveblocks/react-lexical";
const initialConfig = liveblocksConfig({  namespace: "MyEditor",  theme: {},  nodes: [],  onError: (err) => console.error(err),});
function Editor() {  const ready = useIsEditorReady();
  return (    <LexicalComposer initialConfig={initialConfig}>      <LiveblocksPlugin>        <FloatingThreads />        <FloatingComposer />        <AnchoredThreads />      </LiveblocksPlugin>      {!ready ? (        <div>Loading...</div>      ) : (        <RichTextPlugin          contentEditable={<ContentEditable />}          placeholder={<div>Enter some text...</div>}          ErrorBoundary={LexicalErrorBoundary}        />      )}    </LexicalComposer>  );}

useEditorStatus

Returns the current editor status.

import { useEditorStatus } from "@liveblocks/react-lexical";
const status = useEditorStatus();

The possible values are:

  • not-loaded: Initial editor state when entering the room.
  • loading: Once the editor state has been requested by LiveblocksPlugin.
  • synchronized: The editor state is sync with Liveblocks servers.

useIsThreadActive

Accepts a thread id and returns whether the thread annotation for this thread is selected or not in the Lexical editor. This hook must be used in a component nested inside LiveblocksPlugin.

import { useIsThreadActive } from "@liveblocks/react-lexical";
const isActive = useIsThreadActive(thread.id);
Arguments
  • threadIdstrinngRequired

    The ID of the thread.

This hook can be useful to style threads based on whether their associated thread annotations are selected or not in the editor.

Utilities

isTextFormatActive

Checks if a text format (bold, italic, etc.) is active in the current selection. Takes a Lexical editor, and returns a boolean.

import { isTextFormatActive } from "@liveblocks/react-lexical";
// "true" | "false"const isActive = isTextFormatActive(editor, "bold");
Arguments
  • editorLexicalEditorRequired

    The Lexical editor.

  • formatTextFormatTypeRequired

    The Lexical text format to check for in the current selection.

Creating toggle buttons

The isTextFormatActive helper is particularly useful for creating buttons with Toolbar.Toggle.

import { FORMAT_TEXT_COMMAND } from "lexical";import { useLexicalComposerContext } from "@lexical/react/LexicalComposerContext";import { isTextFormatActive, Toolbar } from "@liveblocks/react-lexical";
function CustomToggleButton() {  const [editor] = useLexicalComposerContext();
  return (    <Toolbar.Toggle      name="Bold"      icon={<strong>B️</strong>}      active={isTextFormatActive(editor, "bold")}      onClick={() => editor.dispatchCommand(FORMAT_TEXT_COMMAND, "bold")}    />  );}

isBlockNodeActive

Checks if a block node is active in the current selection. If the selection contains multiple block nodes, it will only return true if all of them are of the same type.

import { isBlockNodeActive } from "@liveblocks/react-lexical";import { $isTextNode } from "lexical";
// Checking if text node is currently activeconst isActive = isBlockNodeActive(editor, $isTextNode);
Arguments
  • editorLexicalEditorRequired

    The Lexical editor.

  • isActive(node: LexicalNode) => booleanRequired

    Function that passes the current node, helping you check if the current block node is active. Helpful in combination with $is___Node functions.

Creating custom block selector items

The isBlockNodeActive helper is particularly useful for adding custom Toolbar.BlockSelector items.

import { isBlockNodeActive, Toolbar } from "@liveblocks/react-lexical";import { $setBlocksType } from "@lexical/selection";import { $isCodeNode } from "@lexical/code";import { $getSelection } from "lexical";
<Toolbar>  <Toolbar.BlockSelector    items={(defaultItems) => [      ...defaultItems,      {        name: "Code block",        icon: <div>❮ ❯</div>,        isActive: (editor) => isBlockNodeActive(editor, $isCodeNode),        setActive: (editor) =>          $setBlocksType($getSelection(), () => $createCodeNode()),      },    ]}  /></Toolbar>;

Stylesheets

React Lexical comes with default styles, and these can be imported into the root of your app or directly into a CSS file with @import. Note that you must also install and import a stylesheet from @liveblocks/react-ui to use these styles.

import "@liveblocks/react-ui/styles.css";import "@liveblocks/react-lexical/styles.css";

Customizing your styles

Adding dark mode and customizing your styles is part of @liveblocks/react-ui, learn how to do this under styling and customization.

We use cookies to collect data to improve your experience on our site. Read our Privacy Policy to learn more.