diff --git a/packages/block-editor/src/components/link-control/README.md b/packages/block-editor/src/components/link-control/README.md index c3fc7262adb956..9522f91ec2d6b0 100644 --- a/packages/block-editor/src/components/link-control/README.md +++ b/packages/block-editor/src/components/link-control/README.md @@ -4,6 +4,26 @@ Renders a link control. A link control is a controlled input which maintains a v It is designed to provide a standardized UI for the creation of a link throughout the Editor, see History section at bottom for further background. +## Best Practices + +### Ensuring unique instances + +It is possible that a given editor may render multiple instances of the `` component. As a result, it is important to ensure each instance is unique across the editor to avoid state "leaking" between components. + +Why would this happen? + +React's reconciliation algorithm means that if you return the same element from a component, it keeps the nodes around as an optimization, even if the props change. This means that if you render two (or more) ``s, it is possible that the `value` from one will appear in the other as you move between them. + +As a result it is recommended that consumers provide a `key` prop to each instance of ``: + +```jsx + +``` + +This will cause React to return the same component/element type but force remount a new instance, thus avoiding the issues described above. + +For more information see: https://github.com/WordPress/gutenberg/pull/34742. + ## Relationship to `` As of Gutenberg 7.4, `` became the default link creation interface within the Block Editor, replacing previous disparate uses of `` and standardizing the UI. @@ -69,9 +89,7 @@ An array of settings objects associated with a link (for example: a setting to d To disable settings, pass in an empty array. for example: ```jsx - + ``` ### onChange @@ -192,6 +210,7 @@ A `suggestion` should have the following shape: )} /> ``` + ### renderControlBottom - Type: `Function`