update readme, update example

Author: hartzis

README.md

@@ -2,7 +2,7 @@
 
 [![Build Status][travis.img]][travis.url] [![npm version][npm.img]][npm.url] [![npm downloads][npm.dl.img]][npm.dl.url] [![Dependencies][deps.img]][deps.url]
 
-Component wrapper for [Google reCAPTCHA v2][reCAPTCHA]
+React component for [Google reCAPTCHA v2][reCAPTCHA].
 
 ## Installation
 
@@ -12,10 +12,13 @@ npm install --save react-google-recaptcha
 
 ## Usage
 
-All you need to do is [sign up for an API key pair][signup]. You will need the client key.
+All you need to do is [sign up for an API key pair][signup]. You will need the client key then you can use `<ReCAPTCHA />`.
 
-You can then use the reCAPTCHA. The default require imports a wrapped component that loads the reCAPTCHA script asynchronously.
+The default usage imports a wrapped component that loads the google recaptcha script asynchronously then instantiates a `reCAPTCHA` the user can then interact with.
 
+Here is a simple working [example on codesandbox.io](https://codesandbox.io/s/1y4zzjq37l).
+
+Code Example:
 ```jsx
 import ReCAPTCHA from "react-google-recaptcha";
 
@@ -25,47 +28,31 @@ function onChange(value) {
 
 ReactDOM.render(
   <ReCAPTCHA
-    ref="recaptcha"
     sitekey="Your client site key"
     onChange={onChange}
   />,
   document.body
 );
 ```
 
-### Rendering Props
+### Component Props
 
-Other properties can be used to customise the rendering.
+Properties used to customise the rendering:
 
 | Name | Type | Description |
 |:---- | ---- | ------ |
 | sitekey | string | The API client key |
 | onChange | func | The function to be called when the user successfully completes the captcha |
-| theme | enum | *optional* `light` or `dark` The theme of the widget *(__defaults:__ light)*. See [example][docs_theme]
-| type | enum | *optional* `image` or `audio` The type of initial captcha *(__defaults:__ image)*
-| tabindex | number | *optional* The tabindex on the element *(__default:__ 0)*
+| theme | enum | *optional* `light` or `dark` The theme of the widget *(__defaults:__ `light`)*. See [example][docs_theme]
+| type | enum | *optional* `image` or `audio` The type of initial captcha *(__defaults:__ `image`)*
+| tabindex | number | *optional* The tabindex on the element *(__default:__ `0`)*
 | onExpired | func | *optional* callback when the challenge is expired and has to be redone by user. By default it will call the onChange with null to signify expired callback. |
 | onErrored | func | *optional* callback when the challenge errored, most likely due to network issues. |
 | stoken | string | *optional* set the stoken parameter, which allows the captcha to be used from different domains, see [reCAPTCHA secure-token] |
 | size | enum | *optional* `compact`, `normal` or `invisible`. This allows you to change the size or do an invisible captcha |
 | badge | enum | *optional* `bottomright`, `bottomleft` or `inline`. Positions reCAPTCHA badge. *Only for invisible reCAPTCHA* |
 
-
-__lang__: In order to translate the reCaptcha widget, you should create a global variable configuring the desired language. If you don't provide it, reCaptcha will pick up the user's interface language.
-
-__useRecaptchaNet__: If google.com is blocked, you can set useRecaptchaNet to `true` so that the component uses recaptcha.net instead.
-
-__removeOnUnmount__: If you plan to change the lang dynamically, removeOnUnmount should probably be true. This will allow you to unmount the reCAPTCHA component and remount it with a new language.
-
-```js
-window.recaptchaOptions = {
-  lang: 'fr',
-  useRecaptchaNet: true,
-  removeOnUnmount: false,
-};
-```
-
-## Component API
+### Component Instance API
 
 The component instance also has some utility functions that can be called. These can be accessed via `ref`.
 
@@ -75,23 +62,44 @@ The component instance also has some utility functions that can be called. These
 - `execute()` programmatically invoke the challenge
   - need to call when using `"invisible"` reCAPTCHA - [example below](#invisible-recaptcha)
 
+Example:
+```javascript
+const recaptchaRef = React.createRef();
+...
+onSubmit = () ={
+  const recaptchaValue = recaptchaRef.getValue();
+  this.props.onSubmit(recaptchaValue);
+}
+render() {
+  return (
+    <form onSubmit={this.onSubmit} >
+      <ReCAPTCHA
+        ref={recaptchaRef}
+        sitekey="Your client site key"
+        onChange={onChange}
+      />
+    </form>
+  )
+}
+```
+
 ### Invisible reCAPTCHA
 
 [Invisible reCAPTCHA](https://developers.google.com/recaptcha/docs/versions)
 
-Starting with 0.7.0, the component now supports invisible options. See the [reCAPTCHA documentation](https://developers.google.com/recaptcha/docs/invisible) to see how to configure it.
+See the [reCAPTCHA documentation](https://developers.google.com/recaptcha/docs/invisible) to see how to configure it.
 
 With the invisible option, you need to handle things a bit differently. You will need to call the `execute` method yourself.
 
 ```jsx
 import ReCAPTCHA from "react-google-recaptcha";
 
-let captcha;
+const recaptchaRef = React.createRef();
 
 ReactDOM.render(
   <form onSubmit={() => { captcha.execute(); }}>
     <ReCAPTCHA
-      ref={(el) => { captcha = el; }}
+      ref={recaptchaRef}
       size="invisible"
       sitekey="Your client site key"
     />
@@ -103,6 +111,25 @@ ReactDOM.render(
 
 ### Advanced usage
 
+#### Global properties used by reCaptcha
+
+__lang__: By default google reCaptcha infers the user's interface language. In order to overwrite the language and update the translation for the reCaptcha widget, you can create a global variable configuring the desired language via `lang`.
+
+__useRecaptchaNet__: If google.com is blocked, you can set `useRecaptchaNet` to `true` so that the component uses recaptcha.net instead.
+
+__removeOnUnmount__: If you plan to change the lang dynamically, `removeOnUnmount` should probably be `true`. This unloads the google recaptcha script on `componetWillUnmount` to allow for a new google recaptcha script to load next time the reCAPTCHA component is used to facilitate a new language if needed.
+
+Example global properties:
+```js
+window.recaptchaOptions = {
+  lang: 'fr',
+  useRecaptchaNet: true,
+  removeOnUnmount: false,
+};
+```
+
+#### ReCaptcha loading google recaptcha script manually
+
 You can also use the barebone components doing the following. Using that component will oblige you to manage the grecaptcha dep and load the script by yourself.
 
 ```jsx
@@ -121,7 +148,7 @@ render(
 ```
 
 ## Notes on Requirements
-At least `[email protected]` is required due to `forwardRef` usage in [react-async-script](https://github.com/dozoisch/react-async-script).
+At least `[email protected]` is required due to `forwardRef` usage in the dependency [react-async-script](https://github.com/dozoisch/react-async-script).
 
 ## Notes