4f:I[314491,["/_next/static/immutable/chunks/3arlv5bvukoo2.js","/_next/static/immutable/chunks/39v64hmfyo-sr.js","/_next/static/immutable/chunks/2nvof3-29tvc3.js","/_next/static/immutable/chunks/3tjobt77z_9dj.js","/_next/static/immutable/chunks/04j_o97cgxn2x.js","/_next/static/immutable/chunks/3upr08c9vtj8w.js","/_next/static/immutable/chunks/1ww0328si-u8x.js","/_next/static/immutable/chunks/11mfl5ymqld9-.js","/_next/static/immutable/chunks/2xxcqy6ppds3l.js","/_next/static/immutable/chunks/3j06ow7w40nxu.js","/_next/static/immutable/chunks/31nn7jwsjvqii.js","/_next/static/immutable/chunks/43_s7jweyypoh.js","/_next/static/immutable/chunks/0p6vao205o1jc.js","/_next/static/immutable/chunks/1_kyvgkyokw92.js","/_next/static/immutable/chunks/1lo-zn37dolb5.js","/_next/static/immutable/chunks/1v8k6yxw1rg0u.js"],"FilesView"] 50:T15e3,--- title: Controlled Editor Value description: Control initial values, persistence, replacement, and async initialization. --- Plate is not a normal controlled text input. The editor owns content, selection, history, plugin state, and normalization. This guide shows the safe control points: initial values, change persistence, explicit replacement, reset, and delayed initialization. ## Value Ownership Do not mirror `editor.children` into React state and pass it back on every change. That fights Slate selection/history and turns normal typing into a full-document replacement loop. | Goal | API | | --- | --- | | Set initial content. | `value` in `usePlateEditor` or `createPlateEditor`. | | Persist edits. | `` or ``. | | Replace content from outside the editor. | `editor.tf.setValue(value)`. | | Reset editor state. | `editor.tf.reset()`. | | Delay initialization. | `skipInitialization: true` plus `editor.tf.init(...)`. | ### Set the Initial Value Pass a `Value`, an HTML string, a function, or an async function to `value`. ```tsx title="components/editor.tsx" showLineNumbers import type { Value } from 'platejs'; import { Plate, usePlateEditor } from 'platejs/react'; import { Editor, EditorContainer } from '@/components/ui/editor'; const initialValue: Value = [ { children: [{ text: 'Initial value' }], type: 'p', }, ]; export function MyEditor() { const editor = usePlateEditor({ value: initialValue, }); return ( ); } ``` ### Persist Changes Use `onValueChange` when you only need the document value. ```tsx title="components/editor.tsx" showLineNumbers {15-19,25} import type { Value } from 'platejs'; import { Plate, usePlateEditor } from 'platejs/react'; import { Editor, EditorContainer } from '@/components/ui/editor'; const STORAGE_KEY = 'plate-value'; const initialValue: Value = [ { children: [{ text: 'Autosaved value' }], type: 'p', }, ]; function saveValue(value: Value) { localStorage.setItem(STORAGE_KEY, JSON.stringify(value)); } export function MyEditor() { const editor = usePlateEditor({ value: () => { const saved = localStorage.getItem(STORAGE_KEY); return saved ? JSON.parse(saved) : initialValue; }, }); return ( saveValue(value)}> ); } ``` Use `onChange` when the callback needs the editor instance too. ```tsx title="components/editor.tsx" { console.info(editor.id, value); }} /> ``` ### Replace or Reset Content Use transforms for external changes. `setValue` replaces the document and `reset` returns the editor to its initialized state. ```tsx title="components/replace-controls.tsx" showLineNumbers import type { Value } from 'platejs'; import { useEditorRef } from 'platejs/react'; import { Button } from '@/components/ui/button'; const replacementValue: Value = [ { children: [{ text: 'Replaced value' }], type: 'p', }, ]; export function ReplaceControls() { const editor = useEditorRef(); return (

); } ``` `editor.tf.setValue` replaces nodes at the document root. Use it for explicit outside-editor changes, not for every `onValueChange`. ### Load Async Initial Content Use an async `value` function when the editor can initialize as soon as the data resolves. ```tsx title="components/async-editor.tsx" showLineNumbers import { Plate, usePlateEditor } from 'platejs/react'; import { Editor, EditorContainer } from '@/components/ui/editor'; export function AsyncEditor() { const editor = usePlateEditor({ autoSelect: 'end', value: async () => { const response = await fetch('/api/document'); const data = await response.json(); return data.content; }, onReady: ({ isAsync, value }) => { if (isAsync) console.info('Loaded value:', value); }, }); return ( ); } ``` ### Initialize Manually Use `skipInitialization` when another system owns the startup moment, such as collaboration or a multi-step loader. ```tsx title="components/manual-init-editor.tsx" showLineNumbers {8,13-18} import * as React from 'react'; import { Plate, usePlateEditor } from 'platejs/react'; import { Editor, EditorContainer } from '@/components/ui/editor'; export function ManualInitEditor() { const editor = usePlateEditor({ skipInitialization: true, }); React.useEffect(() => { void fetch('/api/document') .then((response) => response.json()) .then((data) => { editor.tf.init({ autoSelect: 'end', value: data.content, }); }); }, [editor]); return ( ); } ``` Done. Plate owns live editor state; your app controls the entry points around it. 4e:["$","div",null,{"className":"mt-3 flex min-h-0 min-w-0 flex-1 flex-col gap-3","children":[null,["$","$L4f",null,{"files":[{"path":"../../content/docs/(guides)/controlled.mdx","content":"$50","type":"registry:file","target":"content/docs/plate/(guides)/controlled.mdx"}],"className":"h-[70svh] min-h-80"}]]}]