{
37 | expect(getRef(ref).tagName.toLowerCase()).toBe('div');
38 | }}
39 | />
40 | );
41 |
42 | TestUtils.renderIntoDocument();
43 | });
44 |
45 | it('should warn if not provided a ref object or inside a ref callback', () => {
46 | const error = console.error;
47 | console.error = jest.fn();
48 | getRef(() => {});
49 | expect(console.error).toHaveBeenLastCalledWith(
50 | 'Warning: getRef: It looks like you may have passed `getRef` the ref ' +
51 | 'callback as an argument. `getRef` should be used with a ref object ' +
52 | 'created by `createRef` or inside a ref callback.'
53 | );
54 | console.error.mockClear();
55 | const ref = getRef(createRef());
56 | expect(console.error).not.toBeCalled();
57 | expect(ref).toEqual(null);
58 | console.error = error;
59 | });
60 | });
61 | });
62 | });
63 |
--------------------------------------------------------------------------------
/src/__tests__/createRef.test.js:
--------------------------------------------------------------------------------
1 | import withReact from '../../test-utils/withReact';
2 |
3 | const name = 'cjs';
4 |
5 | describe(`create-react-ref (${name})`, () => {
6 | withReact(({ React, ReactDOM, TestUtils, version }) => {
7 | describe(`react@${version}`, () => {
8 | let createRef;
9 |
10 | beforeEach(() => {
11 | jest.resetModules();
12 | jest.setMock('react', React);
13 | jest.setMock('react-dom', ReactDOM);
14 | createRef = require('../createRef');
15 | });
16 |
17 | it('should create a function with a current property if polyfilled', () => {
18 | const ref = createRef();
19 |
20 | if (React.createRef) {
21 | expect(typeof ref).toEqual('object');
22 | } else {
23 | expect(typeof ref).toEqual('function');
24 | }
25 | expect(ref.current).toEqual(null);
26 | });
27 |
28 | // Borrowed from React's tests
29 | it('should support object-style refs', () => {
30 | const innerObj = {};
31 | const outerObj = {};
32 |
33 | class Wrapper extends React.Component {
34 | getObject = () => {
35 | return this.props.object;
36 | };
37 |
38 | render() {
39 | return
{this.props.children}
;
40 | }
41 | }
42 |
43 | let mounted = false;
44 |
45 | class Component extends React.Component {
46 | constructor() {
47 | super();
48 | this.innerRef = createRef();
49 | this.outerRef = createRef();
50 | }
51 | render() {
52 | const inner = ;
53 | const outer = (
54 |
55 | {inner}
56 |
57 | );
58 | return outer;
59 | }
60 |
61 | componentDidMount() {
62 | expect(this.innerRef.current.getObject()).toEqual(innerObj);
63 | expect(this.outerRef.current.getObject()).toEqual(outerObj);
64 | mounted = true;
65 | }
66 | }
67 |
68 | TestUtils.renderIntoDocument();
69 | expect(mounted).toBe(true);
70 | });
71 | });
72 | });
73 | });
74 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # create-react-ref
2 |
3 | ## What is this?
4 |
5 | React version 16.3 introduces 2 new APIs, `React.createRef` ([React RFC #17](https://github.com/reactjs/rfcs/blob/master/text/0017-new-create-ref.md)) and `React.forwardRef` ([React RFC #30](https://github.com/reactjs/rfcs/blob/master/text/0030-ref-forwarding.md)).
6 |
7 | 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.
8 |
9 | #### This project is not recommended for libraries if you intend to expose the component whose ref is fowarded. The reason is that if your users use a version of React before 16.3, they will receive the internal `RefForwarder` component of this package. This package was created to allow users to use the new API as long as the user is the creator and consumer of the forwarding ref. While there is a method in this lib that will always grab the correct ref `getRef`, it is not a good idea to ask your users to depend on and use this package. If you want to forward refs, you may want to fallback to using an additional prop, for example `inputRef`.
10 |
11 | ## How to install
12 |
13 | NPM:
14 |
15 | ```
16 | npm install create-react-ref
17 | ```
18 |
19 | YARN:
20 |
21 | ```
22 | yarn add create-react-ref
23 | ```
24 |
25 | You'll need to also have `react` installed
26 |
27 | ## API and examples
28 |
29 | ### createRef()
30 |
31 | 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.
32 |
33 | ```javascript
34 | import createRef from 'create-react-ref/lib/createRef';
35 |
36 | class MyComponent extends React.Component {
37 | // Once input ref is mounted, it is accessed
38 | // under the `current` proprty
39 | inputRef = createRef();
40 |
41 | render() {
42 | return (
43 |
44 |
45 |
46 | );
47 | }
48 |
49 | componentDidMount() {
50 | this.inputRef.current.focus();
51 | }
52 | }
53 | ```
54 |
55 | ### forwardRef(render)
56 |
57 | The `forwardRef` API allows forwarding refs to a child (inner) component when a ref is attached to the parent (outer) component.
58 | Arguments
59 |
60 | * [`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.
61 |
62 | ```javascript
63 | import forwardRef from 'create-react-ref/lib/forwardRef';
64 | import createRef from 'create-react-ref/lib/createRef';
65 |
66 | const ThemeContext = React.createContext('light');
67 |
68 | // Example HOC
69 | function withTheme(ThemedComponent) {
70 | function ThemeContextInjector(props) {
71 | return (
72 |
73 | {value => (
74 |
75 | )}
76 |
77 | );
78 | }
79 |
80 | // Forward refs through to the inner, "themed" component:
81 | return forwardRef((props, ref) => (
82 |
83 | ));
84 | }
85 |
86 | const ThemedButton = withTheme(Button);
87 | // For the polyfilled forwardRef, you must use `createRef`.
88 | const buttonRef = createRef();
89 |
90 | // buttonRef.current will point to ThemedButton, rather than ThemeContextInjector
91 | ;
92 | ```
93 |
94 | ### Caveats
95 |
96 | 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).
97 |
98 | ## Extra APIs not in React
99 |
100 | ### getRef(ref)
101 |
102 | Arguments
103 |
104 | * [`ref`: `Node | Instance | null`]: Use this function to get the actual ref from a ref object created by `createRef` or `React.createRef`.
105 |
106 | Example:
107 |
108 | Using with `createRef`
109 |
110 | ```javascript
111 | class {
112 | divRef = createRef();
113 |
114 | componentDidMount() {
115 | // When using React.createRef or polyfilled createRef,
116 | // to get the actual div dom node, you have to access
117 | // it on the `current` property.
118 | // For example, this.divRef.current === getRef(this.divRef);
119 | const node = getRef(this.divRef); // returns div node
120 | }
121 | render() {
122 | return