Skip to content

Make the callback example more similar to the new API #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Mar 6, 2018
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 21 additions & 8 deletions content/docs/refs-and-the-dom.md
Original file line number Diff line number Diff line change
Expand Up @@ -265,28 +265,43 @@ All things considered, we advise against exposing DOM nodes whenever possible, b

### Callback Refs

React also supports another way to set refs called "callback refs", which give more fine-grain control over when refs are set and unset.
React also supports another way to set refs called "callback refs", which gives more fine-grain control over when refs are set and unset.

Instead of passing a `ref` attribute created by `createRef()`, you pass a function. The function receives the React component instance or HTML DOM element as its argument, which can be stored and accessed elsewhere. This example uses the `ref` callback to store a reference to a DOM node:
Instead of passing a `ref` attribute created by `createRef()`, you pass a function. The function receives the React component instance or HTML DOM element as its argument, which can be stored and accessed elsewhere.

```javascript{6,17}
The example below implements a common pattern: using the `ref` callback to store a reference to a DOM node in an instance property.

```javascript{5,7-9,11-14,19,29,34}
class CustomTextInput extends React.Component {
constructor(props) {
super(props);

this.textInput = { value: null }; // initial placeholder for the ref

this.setTextInputRef = element => {
this.textInput.value = element
};

this.focusTextInput = () => {
// Explicitly focus the text input using the raw DOM API
this.textInput.focus();
// Focus the text input using the raw DOM API
this.textInput.value.focus();
};
}

componentDidMount () {
// autofocus the input on mount
if (this.textInput.value) this.focusTextInput()
}

render() {
// Use the `ref` callback to store a reference to the text input DOM
// element in an instance field (for example, this.textInput).
return (
<div>
<input
type="text"
ref={(input) => { this.textInput = input; }} />
ref={this.setTextInputRef}
/>
<input
type="button"
value="Focus the text input"
Expand All @@ -300,8 +315,6 @@ class CustomTextInput extends React.Component {

React will call the `ref` callback with the DOM element when the component mounts, and call it with `null` when it unmounts. `ref` callbacks are invoked before `componentDidMount` or `componentDidUpdate` lifecycle hooks.

Using the `ref` callback to set a property on the class is a common pattern for accessing DOM elements. The preferred way is to set the property in the `ref` callback like in the above example. There is even a shorter way to write it: `ref={input => this.textInput = input}`.

You can pass callback refs between components like you can with object refs that were created with `React.createRef()`.

```javascript{4,13}
Expand Down