Yjs: Editor adds leading/trailing empty paragraph in addition to what server returned from onLoadDocument

[eriksson-daniel]

Description

When loading the editor (after a refresh for example) it will add an empty leading or trailing paragraph itself.

Attempts to normalize this away only led to the document moving the last node to the top.

Oh, and the editor does not seem to render at all with skipInitialization: true on [email protected] or higher.

Reproduction URL

https://github.com/eriksson-daniel/yjs-init

Reproduction steps

1. Let content be loaded from onLoadDocument in HocusPocus
2. Refresh
3. Observe that a trailing or leading empty paragraph is added

Plate version

49.0.3

Slate React version

0.117.1

Screenshots

Logs

Browsers

Chrome, Firefox

[dosubot[bot]]

Hi @eriksson-daniel! I'm Dosu and I’m helping the plate team.

The extra leading or trailing empty paragraph comes from Plate's normalization logic, which always ensures at least one top-level block node is present. When loading content from Yjs (like onLoadDocument), if the content doesn't meet Plate's minimum block requirements, it may add an empty paragraph—sometimes at the start or end—especially if the document appears empty or is missing a block node. This is a side effect of how Plate, Slate, and Yjs interact during initialization and normalization.

For the rendering issue with skipInitialization: true on 49.0.4+, there was a change to prevent the editor from rendering until the value is loaded when using async value or skipInitialization. If the value never arrives (for example, if Yjs sync is delayed), the editor stays blank. The new docs suggest using shouldInitialize: false for more control, then manually calling editor.tf.init after your content is ready, which can help avoid this blank state and give you more control over when normalization runs. See the details and code examples in the relevant PR and Yjs docs.

If you want to avoid the extra paragraph, ensure your loaded document always contains at least one valid block node (like a paragraph) before passing it to Plate, or adjust your normalization logic to better fit your use case.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}   

[dosubot[bot]]

The extra leading or trailing empty paragraph is likely caused by normalization logic that ensures the document always has a valid structure—often inserting a paragraph if the document is empty or doesn't end with a block. When using Yjs, the timing between loading the remote document and Plate's normalization can cause redundant empty paragraphs to appear, especially if the editor initializes before the Yjs content is fully loaded.

For the rendering issue with skipInitialization: true on Plate 49.0.4+, recent changes mean the editor won't render until a value is set synchronously. If the value is loaded asynchronously (like from Yjs), you need to manually initialize the editor after the content arrives. Use the new editor.tf.init transform to initialize the editor, and consider the editor.api.shouldNormalizeNode API to prevent normalization before the editor is ready. You can also set shouldInitialize: false and call editor.tf.init yourself for more control over timing and to avoid unwanted paragraph insertion. See the related pull request for details.

In summary: ensure you initialize the editor only after your Yjs content is loaded, and use the new APIs to control normalization and rendering. This should help prevent both the extra paragraph issue and the rendering problem with skipInitialization.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}   

[eriksson-daniel]

@dosu I'm confused.

1. I can see that shouldInitialize is indeed documented here: https://platejs.org/docs/controlled, but it's not an allowed prop in usePlateEditor and it does not exist anywhere in the Plate codebase except for a few documentation files.
2. The docs here: https://platejs.org/docs/yjs tells me to use editor.getApi(YjsPlugin).yjs.init and not editor.tf.init. I'm not sure how I could insert the intitial Yjs value into editor.tf.init?
3. Even if I initialize the editor with a valid value (i.e. a dummy paragraph) like so: const editor = usePlateEditor({ value: [{ type: 'p', children: [{ text: 'Initial empty paragraph' }] }] }); the editor still insists on adding and empty paragraph (after it has removed my initial one).
4. Disabling normalization does not seem to help

[dosubot[bot]]

You're right—shouldInitialize is not implemented in the Plate codebase, it's just a leftover in the docs and not a real prop in usePlateEditor or anywhere else in the code [source].

For Yjs, the correct way is to use editor.getApi(YjsPlugin).yjs.init after mounting, with skipInitialization: true on the editor. This lets Yjs manage the document state and avoids Plate's default value logic, which can cause double-initialization and extra paragraphs [source]. editor.tf.init is for local transforms, not for collaborative Yjs docs.

The extra empty paragraph happens because Plate enforces a "must have at least one block" rule at the core level, and its normalization can still run even if you disable normalization plugins. If Plate thinks the doc is empty (even briefly, due to async Yjs loading), it inserts a paragraph. Disabling normalization plugins doesn't fully prevent this [source].

To avoid the extra paragraph: always use skipInitialization: true and only call editor.getApi(YjsPlugin).yjs.init after the editor is mounted. Make sure the Y.Doc is empty before passing an initial value, or else the existing content will be synced and your initial value ignored. There isn't a built-in way to fully defer or suppress core normalization until after Yjs sync, so the timing of initialization is key.

If you still see extra paragraphs, double-check that Plate isn't initializing with a default value before Yjs syncs, and that your Yjs provider isn't briefly presenting an empty doc on load. This is a timing/integration quirk, not a widely reported bug.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}   

[eriksson-daniel]

@dosu I can't see that I'm doing anything wrong here: https://github.com/eriksson-daniel/yjs-init/tree/main
Besides, it worked fine in v44: https://github.com/eriksson-daniel/yjs-init/tree/v44

[dosubot[bot]]

You're not doing anything wrong—this is a timing quirk introduced by changes in Plate v48+ and v49+. In these versions, Plate's normalization runs before Yjs content is fully synced, so if the doc looks empty (even briefly), Plate inserts an extra paragraph. In v44, the process was more forgiving and async-friendly, which is why you didn't see the issue there.

The current best practice is to use skipInitialization: true and call editor.getApi(YjsPlugin).yjs.init after mount, letting Yjs manage the state. But even with this, if Yjs is slow to sync, Plate's normalization can still insert an empty paragraph before your real content arrives. This is a known architectural race, not a misconfiguration on your part [docs].

Workarounds are limited, but you can try to ensure Yjs syncs as early as possible and avoid passing any initial value to Plate itself. If you must support Plate 49+, you may need to filter out empty paragraphs in your app logic after sync, or patch the normalization to ignore the first insert if Yjs is still syncing. There’s no official fix yet—this is a side effect of stricter lifecycle and normalization in recent Plate versions [changelog].

If you want a minimal working pattern for v49+, let me know and I can share a snippet based on the latest Plate/Yjs demo.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}   

[zbeyens]

It looks like you need to wait for onConnect/onSync before calling init

[eriksson-daniel]

Thanks! We added a "normalization" in onSync. :)