React Async Script Loader

*NOTE - These are the docs for the upcoming 1.0.0 release - for v0.11.1 documention go to tag here: 0.11.1

A React HOC for loading 3rd party scripts asynchronously. This HOC allows you to wrap a component that needs 3rd party resources, like reCAPTCHA or Google Maps, and have them load the script asynchronously.

Usage

Async Script HOC api

makeAsyncScriptLoader(getScriptUrl, options)(Component)

• Component: The Component to wrap.
• getScriptUrl: string or function that returns the full URL of the script tag.
• options (optional):
  • attributes: object : If the script needs attributes (such as data- attributes), then provide them as key/value pairs of strings and they will be added to the generated script tag.
  • callbackName: string : If the script needs to call a global function when finished loading (for example: recaptcha/api.js?onload=callbackName). Please provide the callback name here and it will be autoregistered on window for you.
  • globalName: string : Can provide the name of the global that the script attaches to window. Async-script will pass this as a prop to the wrapped component. (props[globalName] = window[globalName])
  • removeOnUnmount: boolean default=false : If set to true removes the script tag when component unmounts.
  • scriptId: string : If set, it adds the following id on the script tag.

HOC Component props

1const AsyncScriptComponent = makeAsyncScriptLoader(URL)(Component);
2// ---
3<AsyncScriptComponent asyncScriptOnLoad={callAfterScriptLoads} />

• asyncScriptOnLoad: function : called after script finishes loading. using script.onload

Ref and forwardRef

react-async-script uses react's forwardRef method to pass along the ref applied to the wrapped component.

If you pass a ref prop you'll have access to your wrapped components instance. See the tests for detailed example.

Simple Example:

1const AsyncHoc = makeAsyncScriptLoader(URL)(ComponentNeedsScript);
2
3class DisplayComponent extends React.Component {
4  constructor(props) {
5    super(props);
6    this._internalRef = React.createRef();
7  }
8  componentDidMount() {
9    console.log("ComponentNeedsScript's Instance -", this._internalRef.current);
10  }
11  render() { return (<AsyncHoc ref={this._internalRef} />)}
12}

Notes on Requirements

At least React@16.4.1 is required due to forwardRef usage internally.

Example

See https://github.com/dozoisch/react-google-recaptcha

1// recaptcha.js
2export class ReCAPTCHA extends React.Component {
3  componentDidUpdate(prevProps) {
4    // recaptcha has loaded via async script
5    if (!prevProps.grecaptcha && this.props.grecaptcha) {
6      this.props.grecaptcha.render(this._container)
7    }
8  }
9  render() { return (
10    <div ref={(r) => this._container = r} />)
11  }
12}
13
14// recaptcha-wrapper.js
15import makeAsyncScriptLoader from "react-async-script";
16import { ReCAPTCHA } from "./recaptcha";
17
18const callbackName = "onloadcallback";
19const URL = `https://www.google.com/recaptcha/api.js?onload=${callbackName}&render=explicit`;
20// the name of the global that recaptcha/api.js sets on window ie: window.grecaptcha
21const globalName = "grecaptcha";
22
23export default makeAsyncScriptLoader(URL, {
24  callbackName: callbackName,
25  globalName: globalName,
26})(ReCAPTCHA);
27
28// main.js
29import ReCAPTCHAWrapper from "./recaptcha-wrapper.js"
30
31const onLoad = () => console.log("script loaded")
32
33React.render(
34  <ReCAPTCHAWrapper asyncScriptOnLoad={onLoad} />,
35  document.body
36);

Migration to 1.0

• Component is now passed as a second function call
• removeOnMount is now removeOnUnmount (typo fixed!)
• exposeFuncs is no longer needed as it's done automatically!

1-export default makeAsyncScriptLoader(ReCAPTCHA, getURL, {
2+export default makeAsyncScriptLoader(getURL, {
3   callbackName,
4   globalName,
5-  removeOnMount: initialOptions.removeOnMount || false,
6+  removeOnUnmount: initialOptions.removeOnUnmount || false,
7-  exposeFuncs: ["getValue", "getWidgetId", "reset", "execute"],
8-});
9+})(ReCAPTCHA);

Notes

Pre 1.0.0 and - React < React@16.4.1 support details in 0.11.1.

---