diff --git a/docs/docs/08-working-with-the-browser.md b/docs/docs/08-working-with-the-browser.md index 2a5a3e6a25a..dcf7458ae72 100644 --- a/docs/docs/08-working-with-the-browser.md +++ b/docs/docs/08-working-with-the-browser.md @@ -18,13 +18,13 @@ Additionally, React implements a full synthetic event system such that all event Most of the time you should stay within React's "faked browser" world since it's more performant and easier to reason about. However, sometimes you simply need to access the underlying API, perhaps to work with a third-party library like a jQuery plugin. React provides escape hatches for you to use the underlying DOM API directly. -## Refs and getDOMNode() +## Refs and findDOMNode() -To interact with the browser, you'll need a reference to a DOM node. Every mounted React component has a `getDOMNode()` function which you can call to get a reference to it. +To interact with the browser, you'll need a reference to a DOM node. React has a `React.findDOMNode(component)` function which you can call to get a reference to the component's DOM node. > Note: > -> `getDOMNode()` only works on mounted components (that is, components that have been placed in the DOM). If you try to call this on a component that has not been mounted yet (like calling `getDOMNode()` in `render()` on a component that has yet to be created) an exception will be thrown. +> `findDOMNode()` only works on mounted components (that is, components that have been placed in the DOM). If you try to call this on a component that has not been mounted yet (like calling `findDOMNode()` in `render()` on a component that has yet to be created) an exception will be thrown. In order to get a reference to a React component, you can either use `this` to get the current React component, or you can use refs to refer to a component you own. They work like this: @@ -32,7 +32,7 @@ In order to get a reference to a React component, you can either use `this` to g var MyComponent = React.createClass({ handleClick: function() { // Explicitly focus the text input using the raw DOM API. - this.refs.myTextInput.getDOMNode().focus(); + React.findDOMNode(this.refs.myTextInput).focus(); }, render: function() { // The ref attribute adds a reference to the component to @@ -97,7 +97,7 @@ React provides lifecycle methods that you can specify to hook into this process. _Mounted_ composite components also support the following methods: -* `getDOMNode(): DOMElement` can be invoked on any mounted component in order to obtain a reference to its rendered DOM node. +* `findDOMNode(): DOMElement` can be invoked on any mounted component in order to obtain a reference to its rendered DOM node. * `forceUpdate()` can be invoked on any mounted component when you know that some deeper aspect of the component's state has changed without using `this.setState()`. diff --git a/docs/docs/08.1-more-about-refs.md b/docs/docs/08.1-more-about-refs.md index fc6c95960d9..e3bbde68230 100644 --- a/docs/docs/08.1-more-about-refs.md +++ b/docs/docs/08.1-more-about-refs.md @@ -83,7 +83,7 @@ It's as simple as: this.refs.myInput ``` - You can access the component's DOM node directly by calling `this.refs.myInput.getDOMNode()`. + You can access the component's DOM node directly by calling `React.findDOMNode(this.refs.myInput)`. ## Completing the Example @@ -99,7 +99,7 @@ It's as simple as: // Clear the input this.setState({userInput: ''}, function() { // This code executes after the component is re-rendered - this.refs.theInput.getDOMNode().focus(); // Boom! Focused! + React.findDOMNode(this.refs.theInput).focus(); // Boom! Focused! }); }, render: function() { @@ -129,7 +129,7 @@ Refs are a great way to send a message to a particular child instance in a way t ### Benefits: - You can define any public method on your component classes (such as a reset method on a Typeahead) and call those public methods through refs (such as `this.refs.myTypeahead.reset()`). -- Performing DOM measurements almost always requires reaching out to a "native" component such as `` and accessing its underlying DOM node via `this.refs.myInput.getDOMNode()`. Refs are one of the only practical ways of doing this reliably. +- Performing DOM measurements almost always requires reaching out to a "native" component such as `` and accessing its underlying DOM node via `React.findDOMNode(this.refs.myInput)`. Refs are one of the only practical ways of doing this reliably. - Refs are automatically book-kept for you! If that child is destroyed, its ref is also destroyed for you. No worrying about memory here (unless you do something crazy to retain a reference yourself). ### Cautions: diff --git a/docs/docs/10.4-test-utils.md b/docs/docs/10.4-test-utils.md index faa15661957..78d56d7abdd 100644 --- a/docs/docs/10.4-test-utils.md +++ b/docs/docs/10.4-test-utils.md @@ -19,7 +19,7 @@ Simulate an event dispatch on a DOM node with optional `eventData` event data. * Example usage: ```javascript -var node = this.refs.input.getDOMNode(); +var node = React.findDOMNode(this.refs.input); React.addons.TestUtils.Simulate.click(node); React.addons.TestUtils.Simulate.change(node, {target: {value: 'Hello, world'}}); React.addons.TestUtils.Simulate.keyDown(node, {key: "Enter"}); diff --git a/docs/docs/ref-01-top-level-api.md b/docs/docs/ref-01-top-level-api.md index 29d429d65e4..6bea7670c3a 100644 --- a/docs/docs/ref-01-top-level-api.md +++ b/docs/docs/ref-01-top-level-api.md @@ -110,6 +110,14 @@ boolean isValidElement(* object) Verifies the object is a ReactElement. +### React.findDOMNode + +```javascript +DOMElement findDOMNode(ReactComponent component) +``` +If this component has been mounted into the DOM, this returns the corresponding native browser DOM element. This method is useful for reading values out of the DOM, such as form field values and performing DOM measurements. When `render` returns `null` or `false`, `this.getDOMNode()` returns `null`. + + ### React.DOM `React.DOM` provides convenience wrappers around `React.createElement` for DOM components. These should only be used when not using JSX. For example, `React.DOM.div(null, 'Hello World!')` diff --git a/docs/docs/ref-02-component-api.md b/docs/docs/ref-02-component-api.md index 4ca1d2a607d..b2d3bf99dda 100644 --- a/docs/docs/ref-02-component-api.md +++ b/docs/docs/ref-02-component-api.md @@ -60,6 +60,10 @@ DOMElement getDOMNode() If this component has been mounted into the DOM, this returns the corresponding native browser DOM element. This method is useful for reading values out of the DOM, such as form field values and performing DOM measurements. When `render` returns `null` or `false`, `this.getDOMNode()` returns `null`. +> Note: +> +> getDOMNode is deprecated and has been replaced with [React.findDOMNode()](/react/docs/top-level-api.html#react.finddomnode). + ### isMounted diff --git a/docs/docs/ref-03-component-specs.md b/docs/docs/ref-03-component-specs.md index 0bf75261b4a..85924f94c27 100644 --- a/docs/docs/ref-03-component-specs.md +++ b/docs/docs/ref-03-component-specs.md @@ -21,7 +21,7 @@ The `render()` method is required. When called, it should examine `this.props` and `this.state` and return a single child component. This child component can be either a virtual representation of a native DOM component (such as `
` or `React.DOM.div()`) or another composite component that you've defined yourself. -You can also return `null` or `false` to indicate that you don't want anything rendered. Behind the scenes, React renders a `