Rename <Slate> component value prop to initialValue (#5421)

* Rename `slate-react` Slate component `value` prop to `initialValue` Fixes #4992 * Update documentation: `value` -> `initialValue` * Add a changeset record * Make props order consistent
2025-08-28 09:29:49 +02:00 · 2023-05-26 17:53:39 +03:00
parent 0b1799091a
commit 91e388ecd9
34 changed files with 71 additions and 56 deletions
--- a/.changeset/tiny-suns-lick.md
+++ b/.changeset/tiny-suns-lick.md
@@ -0,0 +1,5 @@
+---
+'slate-react': minor
+---
+
+Rename `<Slate>` component prop from `value` to `initialValue` to emphasize uncontrolled nature of it
--- a/docs/concepts/12-typescript.md
+++ b/docs/concepts/12-typescript.md
@@ -53,7 +53,7 @@ const App = () => {
  const [editor] = useState(() => withReact(createEditor()))

  return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
      <Editable />
    </Slate>
  )
--- a/docs/general/changelog.md
+++ b/docs/general/changelog.md
@@ -309,7 +309,7 @@ const [value, setValue] = useState(initialValue)
 const [selection, setSelection] = useState(null)

 <Slate
-  value={value}
+  initialValue={initialValue}
  selection={selection}
  onChange={(value, selection) => {
    setValue(value)
--- a/docs/walkthroughs/01-installing-slate.md
+++ b/docs/walkthroughs/01-installing-slate.md
@@ -81,7 +81,7 @@ const initialValue = [
 const App = () => {
  const [editor] = useState(() => withReact(createEditor()))
  // Render the Slate context.
-  return <Slate editor={editor} value={initialValue} />
+  return <Slate editor={editor} initialValue={initialValue} />
 }
 ```

@@ -107,7 +107,7 @@ const App = () => {
  const [editor] = useState(() => withReact(createEditor()))
  return (
    // Add the editable component inside the context.
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
      <Editable />
    </Slate>
  )
--- a/docs/walkthroughs/02-adding-event-handlers.md
+++ b/docs/walkthroughs/02-adding-event-handlers.md
@@ -20,7 +20,7 @@ const App = () => {
  const [editor] = useState(() => withReact(createEditor()))

  return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
      <Editable />
    </Slate>
  )
@@ -41,7 +41,7 @@ const App = () => {
  const [editor] = useState(() => withReact(createEditor()))

  return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
      <Editable
        // Define a new handler which prints the key that was pressed.
        onKeyDown={event => {
@@ -71,7 +71,7 @@ const App = () => {
  const [editor] = useState(() => withReact(createEditor()))

  return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
      <Editable
        onKeyDown={event => {
          if (event.key === '&') {
--- a/docs/walkthroughs/03-defining-custom-elements.md
+++ b/docs/walkthroughs/03-defining-custom-elements.md
@@ -18,7 +18,7 @@ const App = () => {
  const [editor] = useState(() => withReact(createEditor()))

  return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
      <Editable
        onKeyDown={event => {
          if (event.key === '&') {
@@ -88,7 +88,7 @@ const App = () => {
  }, [])

  return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
      <Editable
        // Pass in the `renderElement` function.
        renderElement={renderElement}
@@ -142,7 +142,7 @@ const App = () => {
  }, [])

  return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
      <Editable
        renderElement={renderElement}
        onKeyDown={event => {
@@ -200,7 +200,7 @@ const App = () => {
  }, [])

  return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
      <Editable
        renderElement={renderElement}
        onKeyDown={event => {
--- a/docs/walkthroughs/04-applying-custom-formatting.md
+++ b/docs/walkthroughs/04-applying-custom-formatting.md
@@ -27,7 +27,7 @@ const App = () => {
  const [editor] = useState(() => withReact(createEditor()))

  return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
      <Editable
        renderElement={renderElement}
        onKeyDown={event => {
@@ -72,7 +72,7 @@ const App = () => {
  }, [])

  return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
      <Editable
        renderElement={renderElement}
        onKeyDown={event => {
@@ -163,7 +163,7 @@ const App = () => {
  }, [])

  return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
      <Editable
        renderElement={renderElement}
        // Pass in the `renderLeaf` function.
--- a/docs/walkthroughs/05-executing-commands.md
+++ b/docs/walkthroughs/05-executing-commands.md
@@ -35,7 +35,7 @@ const App = () => {
  }, [])

  return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
      <Editable
        renderElement={renderElement}
        renderLeaf={renderLeaf}
@@ -142,7 +142,7 @@ const App = () => {
  }, [])

  return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
      <Editable
        renderElement={renderElement}
        renderLeaf={renderLeaf}
@@ -200,7 +200,7 @@ const App = () => {

  return (
    // Add a toolbar with buttons that call the same methods.
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
      <div>
        <button
          onMouseDown={event => {
--- a/docs/walkthroughs/06-saving-to-a-database.md
+++ b/docs/walkthroughs/06-saving-to-a-database.md
@@ -18,7 +18,7 @@ const App = () => {
  const [editor] = useState(() => withReact(createEditor()))

  return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
      <Editable />
    </Slate>
  )
@@ -45,7 +45,7 @@ const App = () => {
  return (
    <Slate
      editor={editor}
-      value={initialValue}
+      initialValue={initialValue}
      onChange={value => {
        const isAstChange = editor.operations.some(
          op => 'set_selection' !== op.type
@@ -85,7 +85,7 @@ const App = () => {
  return (
    <Slate
      editor={editor}
-      value={initialValue}
+      initialValue={initialValue}
      onChange={value => {
        const isAstChange = editor.operations.some(
          op => 'set_selection' !== op.type
@@ -145,7 +145,7 @@ const App = () => {
  return (
    <Slate
      editor={editor}
-      value={initialValue}
+      initialValue={initialValue}
      onChange={value => {
        const isAstChange = editor.operations.some(
          op => 'set_selection' !== op.type
--- a/packages/slate-react/src/components/slate.tsx
+++ b/packages/slate-react/src/components/slate.tsx
@@ -19,18 +19,18 @@ import { EDITOR_TO_ON_CHANGE } from '../utils/weak-maps'

 export const Slate = (props: {
  editor: ReactEditor
-  value: Descendant[]
+  initialValue: Descendant[]
  children: React.ReactNode
  onChange?: (value: Descendant[]) => void
 }) => {
-  const { editor, children, onChange, value, ...rest } = props
+  const { editor, children, onChange, initialValue, ...rest } = props
  const unmountRef = useRef(false)

  const [context, setContext] = React.useState<SlateContextValue>(() => {
-    if (!Node.isNodeList(value)) {
+    if (!Node.isNodeList(initialValue)) {
      throw new Error(
-        `[Slate] value is invalid! Expected a list of elements but got: ${Scrubber.stringify(
-          value
+        `[Slate] initialValue is invalid! Expected a list of elements but got: ${Scrubber.stringify(
+          initialValue
        )}`
      )
    }
@@ -39,7 +39,7 @@ export const Slate = (props: {
        `[Slate] editor is invalid! You passed: ${Scrubber.stringify(editor)}`
      )
    }
-    editor.children = value
+    editor.children = initialValue
    Object.assign(editor, rest)
    return { v: 0, editor }
  })
--- a/packages/slate-react/test/index.spec.tsx
+++ b/packages/slate-react/test/index.spec.tsx
@@ -10,7 +10,9 @@ const createNodeMock = () => ({

 class MockResizeObserver {
  observe() {}
+
  unobserve() {}
+
  disconnect() {}
 }

@@ -21,14 +23,18 @@ describe('slate-react', () => {
    describe('NODE_TO_KEY logic', () => {
      test('should not unmount the node that gets split on a split_node operation', async () => {
        const editor = withReact(createEditor())
-        const value = [{ type: 'block', children: [{ text: 'test' }] }]
+        const initialValue = [{ type: 'block', children: [{ text: 'test' }] }]
        const mounts = jest.fn()

        let el: ReactTestRenderer

        act(() => {
          el = create(
-            <Slate editor={editor} value={value} onChange={() => {}}>
+            <Slate
+              editor={editor}
+              initialValue={initialValue}
+              onChange={() => {}}
+            >
              <Editable
                renderElement={({ children }) => {
                  useEffect(() => mounts(), [])
@@ -52,7 +58,7 @@ describe('slate-react', () => {

      test('should not unmount the node that gets merged into on a merge_node operation', async () => {
        const editor = withReact(createEditor())
-        const value = [
+        const initialValue = [
          { type: 'block', children: [{ text: 'te' }] },
          { type: 'block', children: [{ text: 'st' }] },
        ]
@@ -62,7 +68,11 @@ describe('slate-react', () => {

        act(() => {
          el = create(
-            <Slate editor={editor} value={value} onChange={() => {}}>
+            <Slate
+              editor={editor}
+              initialValue={initialValue}
+              onChange={() => {}}
+            >
              <Editable
                renderElement={({ children }) => {
                  useEffect(() => mounts(), [])
--- a/site/examples/check-lists.tsx
+++ b/site/examples/check-lists.tsx
@@ -73,7 +73,7 @@ const CheckListsExample = () => {
  )

  return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
      <Editable
        renderElement={renderElement}
        placeholder="Get to work…"
--- a/site/examples/code-highlighting.tsx
+++ b/site/examples/code-highlighting.tsx
@@ -46,7 +46,7 @@ const CodeHighlightingExample = () => {
  const onKeyDown = useOnKeydown(editor)

  return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
      <ExampleToolbar />
      <SetNodeToDecorations />
      <Editable
@@ -324,7 +324,7 @@ const App = () => {
  const [editor] = useState(() => withReact(createEditor()))

  return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
      <Editable />
    </Slate>
  )
--- a/site/examples/custom-placeholder.tsx
+++ b/site/examples/custom-placeholder.tsx
@@ -13,7 +13,7 @@ const initialValue: Descendant[] = [
 const PlainTextExample = () => {
  const editor = useMemo(() => withHistory(withReact(createEditor())), [])
  return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
      <Editable
        placeholder="Type something"
        renderPlaceholder={({ children, attributes }) => (
--- a/site/examples/editable-voids.tsx
+++ b/site/examples/editable-voids.tsx
@@ -15,7 +15,7 @@ const EditableVoidsExample = () => {
  )

  return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
      <Toolbar>
        <InsertEditableVoidButton />
      </Toolbar>
--- a/site/examples/embeds.tsx
+++ b/site/examples/embeds.tsx
@@ -16,7 +16,7 @@ import {
 const EmbedsExample = () => {
  const editor = useMemo(() => withEmbeds(withReact(createEditor())), [])
  return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
      <Editable
        renderElement={props => <Element {...props} />}
        placeholder="Enter some text..."
--- a/site/examples/forced-layout.tsx
+++ b/site/examples/forced-layout.tsx
@@ -74,7 +74,7 @@ const ForcedLayoutExample = () => {
    []
  )
  return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
      <Editable
        renderElement={renderElement}
        placeholder="Enter a title…"
--- a/site/examples/hovering-toolbar.tsx
+++ b/site/examples/hovering-toolbar.tsx
@@ -17,7 +17,7 @@ const HoveringMenuExample = () => {
  const editor = useMemo(() => withHistory(withReact(createEditor())), [])

  return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
      <HoveringToolbar />
      <Editable
        renderLeaf={props => <Leaf {...props} />}
--- a/site/examples/huge-document.tsx
+++ b/site/examples/huge-document.tsx
@@ -25,7 +25,7 @@ const HugeDocumentExample = () => {
  const renderElement = useCallback(props => <Element {...props} />, [])
  const editor = useMemo(() => withReact(createEditor()), [])
  return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
      <Editable renderElement={renderElement} spellCheck autoFocus />
    </Slate>
  )
--- a/site/examples/iframe.tsx
+++ b/site/examples/iframe.tsx
@@ -25,7 +25,7 @@ const IFrameExample = () => {
  const handleBlur = useCallback(() => ReactEditor.deselect(editor), [editor])

  return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
      <Toolbar>
        <MarkButton format="bold" icon="format_bold" />
        <MarkButton format="italic" icon="format_italic" />
--- a/site/examples/images.tsx
+++ b/site/examples/images.tsx
@@ -25,7 +25,7 @@ const ImagesExample = () => {
  )

  return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
      <Toolbar>
        <InsertImageButton />
      </Toolbar>
--- a/site/examples/inlines.tsx
+++ b/site/examples/inlines.tsx
@@ -98,7 +98,7 @@ const InlinesExample = () => {
  }

  return (
-    <SlateReact.Slate editor={editor} value={initialValue}>
+    <SlateReact.Slate editor={editor} initialValue={initialValue}>
      <Toolbar>
        <AddLinkButton />
        <RemoveLinkButton />
--- a/site/examples/markdown-preview.tsx
+++ b/site/examples/markdown-preview.tsx
@@ -48,7 +48,7 @@ const MarkdownPreviewExample = () => {
  }, [])

  return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
      <Editable
        decorate={decorate}
        renderLeaf={renderLeaf}
--- a/site/examples/markdown-shortcuts.tsx
+++ b/site/examples/markdown-shortcuts.tsx
@@ -70,7 +70,7 @@ const MarkdownShortcutsExample = () => {
  )

  return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
      <Editable
        onDOMBeforeInput={handleDOMBeforeInput}
        renderElement={renderElement}
--- a/site/examples/mentions.tsx
+++ b/site/examples/mentions.tsx
@@ -73,7 +73,7 @@ const MentionExample = () => {
  return (
    <Slate
      editor={editor}
-      value={initialValue}
+      initialValue={initialValue}
      onChange={() => {
        const { selection } = editor

--- a/site/examples/paste-html.tsx
+++ b/site/examples/paste-html.tsx
@@ -91,7 +91,7 @@ const PasteHtmlExample = () => {
    []
  )
  return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
      <Editable
        renderElement={renderElement}
        renderLeaf={renderLeaf}
--- a/site/examples/plaintext.tsx
+++ b/site/examples/plaintext.tsx
@@ -6,7 +6,7 @@ import { withHistory } from 'slate-history'
 const PlainTextExample = () => {
  const editor = useMemo(() => withHistory(withReact(createEditor())), [])
  return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
      <Editable placeholder="Enter some plain text..." />
    </Slate>
  )
--- a/site/examples/read-only.tsx
+++ b/site/examples/read-only.tsx
@@ -5,7 +5,7 @@ import { Slate, Editable, withReact } from 'slate-react'
 const ReadOnlyExample = () => {
  const editor = useMemo(() => withReact(createEditor()), [])
  return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
      <Editable readOnly placeholder="Enter some plain text..." />
    </Slate>
  )
--- a/site/examples/richtext.tsx
+++ b/site/examples/richtext.tsx
@@ -28,7 +28,7 @@ const RichTextExample = () => {
  const editor = useMemo(() => withHistory(withReact(createEditor())), [])

  return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
      <Toolbar>
        <MarkButton format="bold" icon="format_bold" />
        <MarkButton format="italic" icon="format_italic" />
--- a/site/examples/scroll-into-view.tsx
+++ b/site/examples/scroll-into-view.tsx
@@ -51,7 +51,7 @@ const ScrollIntoViewExample = () => {
 const PlainTextEditor = () => {
  const editor = useMemo(() => withHistory(withReact(createEditor())), [])
  return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
      <Editable placeholder="Enter some plain text..." />
    </Slate>
  )
--- a/site/examples/search-highlighting.tsx
+++ b/site/examples/search-highlighting.tsx
@@ -37,7 +37,7 @@ const SearchHighlightingExample = () => {
  )

  return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
      <Toolbar>
        <div
          className={css`
--- a/site/examples/shadow-dom.tsx
+++ b/site/examples/shadow-dom.tsx
@@ -31,7 +31,7 @@ const ShadowEditor = () => {
  const editor = useMemo(() => withHistory(withReact(createEditor())), [])

  return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
      <Editable placeholder="Enter some plain text..." />
    </Slate>
  )
--- a/site/examples/styling.tsx
+++ b/site/examples/styling.tsx
@@ -11,7 +11,7 @@ const StylingExample = () => {
    <div style={{ display: 'flex', flexDirection: 'column', gap: '40px' }}>
      <Slate
        editor={editor1}
-        value={[
+        initialValue={[
          {
            type: 'paragraph',
            children: [{ text: 'This editor is styled using the style prop.' }],
@@ -29,7 +29,7 @@ const StylingExample = () => {

      <Slate
        editor={editor2}
-        value={[
+        initialValue={[
          {
            type: 'paragraph',
            children: [
--- a/site/examples/tables.tsx
+++ b/site/examples/tables.tsx
@@ -18,7 +18,7 @@ const TablesExample = () => {
    []
  )
  return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
      <Editable renderElement={renderElement} renderLeaf={renderLeaf} />
    </Slate>
  )