create-react-ref

What is this?

React version 16.3 introduces 2 new APIs, React.createRef (React RFC #17) and React.forwardRef (React RFC #30).

This lib was created to allow using the new ref APIs without an immediate upgrade. Once upgraded to React 16.3, you should be able to remove this lib from your imports and just import React's version. However, this lib also checks for React's version and, if it is installed, it will use it instead of the polyfilled version. This way, you can remove the polyfill when you're ready and not at the same time that you upgrade.

How to install

NPM:

``
npm install create-react-ref
`

YARN:

`
yarn add create-react-ref
`

You'll need to also have react installed

API and examples

$3

The createRef API returns an object which attaches the ref to a current property. The polyfill works by returning a function which when invoked internall by React with the ref, will attach it to a current property or the function.

`javascript
import createRef from 'create-react-ref/lib/createRef';

class MyComponent extends React.Component {
// Once input ref is mounted, it is accessed
// under the current proprty
inputRef = createRef();

render() {
return (


);
}

componentDidMount() {
this.inputRef.current.focus();
}
}
`

$3

The forwardRef API allows forwarding refs to a child (inner) component when a ref is attached to the parent (outer) component.
Arguments

* [render(props, ref): ReactElement]: Render should be a function that when called returns a ReactElement to render. It gets passed the current props and the ref to foward. Attach the ref to the inner child component's ref prop that you want a user to receive when attaching a ref to the outer component.

`javascript
import forwardRef from 'create-react-ref/lib/forwardRef';
import createRef from 'create-react-ref/lib/createRef';

const ThemeContext = React.createContext('light');

// Example HOC
function withTheme(ThemedComponent) {
function ThemeContextInjector(props) {
return (

{value => (

)}

);
}

// Forward refs through to the inner, "themed" component:
return forwardRef((props, ref) => (

));
}

const ThemedButton = withTheme(Button);
// For the polyfilled forwardRef, you must use createRef.
const buttonRef = createRef();

// buttonRef.current will point to ThemedButton, rather than ThemeContextInjector
;
`

$3

The polyfilled forwardRef is only compatible with refs created from createRef and not compatible with ref callbacks/functions. If you attach a ref callback to a component returned from the polyfilled forwardRef, you will get a RefForwarder component instance. This is one instance of how this library differs from React's implementation. React actually built an internal type to handle this, which cannot be polyfilled, and returns the actual forwared child. However, this polyfill provides a getRef function you can use to make sure the correct ref is always returned (polyfilled or not).

Extra APIs not in React

$3

Arguments

* [ref: Node | Instance | null]: Use this function to get the actual ref from a ref object created by createRef or React.createRef.

Example:

Using with createRef

`javascript
class {
divRef = createRef();

componentDidMount() {
// When using React.createRef or polyfilled createRef,
// to get the actual div dom node, you have to access
// it on the current property.
// For example, this.divRef.current === getRef(this.divRef);
const node = getRef(this.divRef); // returns div node
}
render() {
return


}
}
`

Using in a ref callback

`javascript
const ForwardingRefComponent = forwardRef((props, ref) => {
return

});

class {
handleRef = (node) => {
// If using the polyfilled forwardRef:
// node instanceof RefForwarder === true
const actualForwardedNode = getRef(node);
// If using React.forwardRef
// node instanceof HTMLDivElement === true
const actualForwardedNode = node; // || getRef(node);
}

render() {
return text
}
}
``