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 asdata-
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 onwindow
for you.globalName
: string : Can provide the name of the global that the script attaches towindow
. Async-script will pass this as a prop to the wrapped component. (props[globalName] = window[globalName]
)removeOnUnmount
: boolean default=false : If set totrue
removes the script tag when component unmounts.scriptId
: string : If set, it adds the following id on the script tag.
HOC Component props
const AsyncScriptComponent = Component;// ---<AsyncScriptComponent asyncScriptOnLoad=callAfterScriptLoads />
asyncScriptOnLoad
: function : called after script finishes loading. usingscript.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:
const AsyncHoc = ComponentNeedsScript; Component { superprops; this_internalRef = React; } { console; } { return <AsyncHoc ref=this_internalRef />}
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
// recaptcha.jsComponent { // recaptcha has loaded via async script if !prevPropsgrecaptcha && thispropsgrecaptcha thispropsgrecaptcha } { return <div ref= this_container = r /> } // recaptcha-wrapper.js;; const callbackName = "onloadcallback";const URL = `https://www.google.com/recaptcha/api.js?onload=&render=explicit`;// the name of the global that recaptcha/api.js sets on window ie: window.grecaptchaconst globalName = "grecaptcha"; URL callbackName: callbackName globalName: globalNameReCAPTCHA; // main.js const onLoad = console React;
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!
-export default makeAsyncScriptLoader(ReCAPTCHA, getURL, {+export default makeAsyncScriptLoader(getURL, { callbackName, globalName,- removeOnMount: initialOptions.removeOnMount || false,+ removeOnUnmount: initialOptions.removeOnUnmount || false,- exposeFuncs: ["getValue", "getWidgetId", "reset", "execute"],-});+})(ReCAPTCHA);
Notes
Pre 1.0.0
and - React < React@16.4.1
support details in 0.11.1.