Skip to content

Commit

Permalink
Update docs with best practices
Browse files Browse the repository at this point in the history
  • Loading branch information
getdave committed Jul 27, 2023
1 parent d735be3 commit 85a3075
Showing 1 changed file with 22 additions and 3 deletions.
25 changes: 22 additions & 3 deletions packages/block-editor/src/components/link-control/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<LinkControl>` 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) `<LinkControl>`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 `<LinkControl>`:

```jsx
<LinkControl key="some-unique-key" { ...props } />
```

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 `<URLInput>`

As of Gutenberg 7.4, `<LinkControl>` became the default link creation interface within the Block Editor, replacing previous disparate uses of `<URLInput>` and standardizing the UI.
Expand Down Expand Up @@ -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
<LinkControl
settings={ [] }
/>
<LinkControl settings={ [] } />
```

### onChange
Expand Down Expand Up @@ -192,6 +210,7 @@ A `suggestion` should have the following shape:
)}
/>
```

### renderControlBottom

- Type: `Function`
Expand Down

0 comments on commit 85a3075

Please sign in to comment.