y-richtext-viewer

Render Yjs richtext Y.XmlFragments with react to plain html (or your own custom components). Each html element subscribes to changes in the Yjs document, only re-rendering the parts of the document that have changed.

This has been tested with documents created with the tiptap collaboration extension, but should also work with prosemirror and other editors that support persisting changes to Y.XmlFragments.

Install

yarn add y-richtext-viewer

Example

import React, { useMemo } from 'react'
import { Viewer } from 'y-richtext-viewer'

const Example = () => {
  const richtext = useMemo(() => {
    const doc = new Y.Doc()
    return doc.getXmlFragment('richtext')
  }, [])

  return <Viewer value={richtext} />
}

To override the default element renderer, you can pass custom element components to the <Viewer>. y-richtext-viewer will continue to watch for changes and automatically re-render custom elements on changes.

// instead of rendering <p> tags, render <div> tags with a className
<Viewer
  value={richtext}
  customElements={{
    paragraph: ({ style, children }) => (
      <div className="text-red-600" style={style}>
        {children}
      </div>
    ),
    text: ({ textParts, TextMark }) => (
      <>
        {textParts.map(({ marks, content }, i) => (
          <TextMark key={i} marks={marks} content={content} />
        ))}
        !
      </>
    ),
  }}
/>

For a more information, see the complete example

Status

y-richtext-viewer currently supports the following elements by default:

• paragraph (<p>)
• orderedList (<ol>)
• bulletList (<ul>)
• listItem (<li>)
• heading (<h1>-<h6>)
• blockquote (<blockquote>)
• horizontalRule (<hr>)

New element types can be added by passing them to the customElements prop.

Elements support textAlign attribute ('left' | 'right' | 'center' | 'justify') and output a style attribute with the textAlign value.

Text elements also support the following formatting attributes:

• bold (<strong>)
• italic (<em>)
• underline (<u>)
• superscript (<sup>)
• subscript (<sub>)
• strike (<s>)
• highlight (<mark>)

Contribution

Thanks to mustafaKamal-fe who made the initial implementation of the viewer.

Additional contributions are welcome, but should be discussed before undertaking work.

Changelog

0.6.1

• Empty property now returns true for elements that have a single text node that is empty

0.6.0

• React 18 support

0.5.2

• Add support for additional formatting attributes (sup, sub, s and mark)

0.5.1

• Forward styles to the root element

0.5.0

• Add support for non-default elements

0.4.0

• Move from yarn to pnpm
• Default tag for unknown elements was changed from span to div
• Add support for custom text element

0.3.2

• Fix ref forwarding

0.3.1

• Add optional ref param

0.3.0

• Update skip empty paragraphs option to skip empty elements
• Pass an empty flag to custom elements

0.2.0

• Add option to skip empty paragraphs
• Add id factory option
• Allow a catch all CustomElement via { '*': CustomElement }
• Pass additional props to custom elements (id, tag, textAlign, depth)
• Improve types for custom elements

0.1.2

• Add readme

0.1.1

• Remove the dependency on tailwind

0.1.0

• Initial release

License

Y Richtext Viewer is licensed under the MIT License.

• Garth Williams [e-mail]