diff --git a/README.md b/README.md
index 21ab5667..d5404efa 100644
--- a/README.md
+++ b/README.md
@@ -25,201 +25,16 @@ To install, you can use [npm](https://npmjs.org/) or [yarn](https://yarnpkg.com)
$ yarn add react-modal
-## Usage
+## API documentation
-The Modal object has one required prop:
-
-- `isOpen` to render its children.
-
-Example:
-
-```jsx
-
-
Modal Content
-
Etc.
-
-```
-
-> Use the prop `contentLabel` which adds `aria-label` to the modal if there is no label text visible on the screen, otherwise specify the element including the label text using `aria-labelledby`
-
-### App Element
-
-The app element allows you to specify the portion
-of your app that should be hidden (via aria-hidden)
-to prevent assistive technologies such as screenreaders
-from reading content outside of the content of
-your modal.
-
-If you are doing server-side rendering, you should use
-this property.
-
-It can be specified in the following ways:
-
-- DOMElement
-
-```js
-Modal.setAppElement(appElement);
-```
-
-- query selector - uses the first element found if you pass in a class.
-
-```js
-Modal.setAppElement('#your-app-element');
-```
-
-### Additional Aria Attributes
-
-Use the property `aria` to pass any additional aria attributes. It accepts
-an object where the keys are the names of the attributes without the prefix
-`aria-`.
-
-Example:
-
-```jsx
-
-
H1
-
-
Description goes here.
-
-
-```
-
-## Styles
-
-Styles are passed with the `style` prop, an object with 2 keys, 'overlay' and 'content' like so
-
-```jsx
-
-```
-
-Styles passed to the modal are merged in with the above defaults and applied to their respective elements.
-At this time, media queries will need to be handled by the consumer.
-
-### Using CSS Classes
-
-If you prefer not to use inline styles or are unable to do so in your project,
-you can pass `className` and `overlayClassName` props to the Modal. If you do
-this then none of the default styles will apply and you will have full control
-over styling via CSS.
-
-If you want to override default content and overlay classes you can pass object
-with three required properties: `base`, `afterOpen`, `beforeClose`.
-
-```jsx
-
-```
-
-You can also pass a `portalClassName` to change the wrapper's class (*ReactModalPortal*).
-This doesn't affect styling as no styles are applied to this element by default.
-
-### Overriding styles globally
-
-The default styles above are available on `Modal.defaultStyles`. Changes to this
-object will apply to all instances of the modal.
-
-### Appended to custom node
-
-You can choose an element for the modal to be appended to, rather than using
-body tag. To do this, provide a function to `parentSelector` prop that return
-the element to be used.
-
-```jsx
-
-function getParent() {
- return document.querySelector('#root');
-}
-
-
-
Modal Content.
-
-```
-
-### Body class
-
-When the modal is opened a `ReactModal__Body--open` class is added to the `body` tag.
-You can use this to remove scrolling on the body while the modal is open.
-
-```CSS
-/* Remove scroll on the body when react-modal is open */
-.ReactModal__Body--open {
- overflow: hidden;
-}
-```
-
-### Refs
-
-You can use ref callbacks to get overlay and content DOM nodes:
-
-```jsx
- this.overlayRef = node}
- contentRef={node => this.contentRef = node}
- ...
->
-
Modal Content.
-
-```
+The primary documentation for react-modal is the
+[reference book](https://reactjs.github.io/react-modal), which describes the API
+and gives examples of its usage.
## Examples
-Inside an app:
+Here is a simple example of react-modal being used in an app with some custom
+styles and focusable input elements within the modal content:
```jsx
import React from 'react';
@@ -294,33 +109,18 @@ class App extends React.Component {
ReactDOM.render(, appElement);
```
-## Testing
-
-When using React Test Utils with this library, here are some things to keep in mind:
-
-- You need to set `isOpen={true}` on the modal component for it to render its children.
-- You need to use the `.portal` property, as in `ReactDOM.findDOMNode(renderedModal.portal)` or `TestUtils.scryRenderedDOMComponentsWithClass(Modal.portal, 'my-modal-class')` to acquire a handle to the inner contents of your modal.
-
-By default the modal is closed when clicking outside of it (the overlay area). If you want to prevent this behavior you can
-pass the 'shouldCloseOnOverlayClick' prop with 'false' value.
-
-```jsx
-
-
-
Force Modal
-
Modal cannot be closed when clicking the overlay area
-
-
-```
+You can find more examples in the `examples` directory, which you can run in a
+local development server using `npm start` or `yarn run start`.
## Demos
-* http://reactjs.github.io/react-modal/
+There are several demos hosted on [CodePen](https://codepen.io) which
+demonstrate various features of react-modal:
+
+* [Minimal example](https://codepen.io/claydiffrient/pen/KNxgav)
+* [Using setAppElement](https://codepen.io/claydiffrient/pen/ENegGJ)
+* [Using onRequestClose](https://codepen.io/claydiffrient/pen/KNjVBx)
+* [Using shouldCloseOnOverlayClick](https://codepen.io/claydiffrient/pen/woLzwo)
+* [Using inline styles](https://codepen.io/claydiffrient/pen/ZBmyKz)
+* [Using CSS classes for styling](https://codepen.io/claydiffrient/pen/KNjVrG)
+* [Customizing the default styles](https://codepen.io/claydiffrient/pen/pNXgqQ)
diff --git a/docs/README.md b/docs/README.md
index 49bb3f6a..78b936d8 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -15,7 +15,9 @@ To install the stable version you can use [npm](https://npmjs.org/) or [yarn](ht
## General Usage {#usage}
-The following is an example of using react-modal specifying all the possible props and options:
+The only required prop for the modal object is `isOpen`, which indicates
+whether the modal should be displayed. The following is an example of using
+react-modal specifying all the possible props and options:
```js
import ReactModal from 'react-modal';
@@ -115,6 +117,46 @@ import ReactModal from 'react-modal';
/>
```
+## Using a custom parent node {#custom-parent}
+
+By default, the modal portal will be appended to the document's body. You can
+choose a different parent element by providing a function to the
+`parentSelector` prop that returns the element to be used:
+
+```jsx
+function getParent() {
+ return document.querySelector('#root');
+}
+
+
+
Modal Content.
+
+```
+
+If you do this, please ensure that your
+[app element](accessibility/README.md#app-element) is set correctly. The app
+element should not be a parent of the modal, to prevent modal content from
+being hidden to screenreaders while it is open.
+
+## Refs {#refs}
+
+You can use ref callbacks to get the overlay and content DOM nodes directly:
+
+```jsx
+ this.overlayRef = node}
+ contentRef={node => this.contentRef = node}
+ ...
+>
+
Modal Content.
+
+```
+
## License {#license}
MIT
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index 9b68fbe1..b3678b27 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -2,13 +2,15 @@
* [Overview](/README.md)
* [Installation](/README.md#installation)
- * [Usage](/README.md#usage)
+ * [Usage summary](/README.md#usage)
+ * [Using a custom parent node](/README.md#custom-parent)
+ * [Refs](/README.md#refs)
* [License](/README.md#license)
* [Accessibility](accessibility/README.md)
* [The app element](accessibility/README.md#app-element)
* [Keyboard navigation](accessibility/README.md#keyboard)
- * [Custom ARIA attributes](accessibility/README.md#aria)
+ * [ARIA attributes](accessibility/README.md#aria)
* [Styles](styles/README.md)
* [Using CSS Classes](styles/classes.md)
diff --git a/docs/accessibility/README.md b/docs/accessibility/README.md
index dd5d8321..8208a12a 100644
--- a/docs/accessibility/README.md
+++ b/docs/accessibility/README.md
@@ -44,11 +44,22 @@ The modal can be closed using the escape key, unless the
`shouldCloseOnEsc={false}` prop is passed. Disabling this behavior may cause
accessibility issues for keyboard users, however, so it is not recommended.
-### Custom ARIA attributes {#aria}
+### ARIA attributes {#aria}
-To pass custom ARIA attributes to your modal, you can use the `aria` prop,
-which accepts an object whose keys are the attributes you want to set (without
-the leading `aria-` prefix). For example, you could have an alert modal with a
+Besides the `aria-hidden` attribute which is applied to the app element when
+the modal is shown, there are many other ARIA attributes which you can use to
+make your app more accessible. A complete list of ARIA attributes can be found
+in the [ARIA specification](https://www.w3.org/TR/wai-aria-1.1/#state_prop_def).
+
+One ARIA attribute is given a dedicated prop by react-modal: you should use the
+`contentLabel` prop to provide a label for the modal content (via `aria-label`)
+if there is no visible label on the screen. If the modal is already labeled
+with visible text, you should specify the element including the label with the
+`aria-labelledby` attribute using the `aria` prop described below.
+
+To pass other ARIA attributes to your modal, you can use the `aria` prop, which
+accepts an object whose keys are the attributes you want to set (without the
+leading `aria-` prefix). For example, you could have an alert modal with a
title as well as a longer description:
```jsx
diff --git a/docs/styles/classes.md b/docs/styles/classes.md
index 3ec161c0..e48f2d9b 100644
--- a/docs/styles/classes.md
+++ b/docs/styles/classes.md
@@ -46,11 +46,21 @@ modal is open by defining a property `bodyOpenClassName`.
The `bodyOpenClassName` prop must be a *constant string*; otherwise, we would
require a complex system to manage which class name should be added to or
removed from `document.body` from which modal (if using multiple modals
-simultaneously).
+simultaneously). The default value is `ReactModal__Body--open`.
`bodyOpenClassName` can support adding multiple classes to `document.body` when
the modal is open. Add as many class names as you desire, delineated by spaces.
+One potential application for the body class is to remove scrolling on the body
+when the modal is open. To do this for all modals (except those that specify a
+non-default `bodyOpenClassName`), you could use the following CSS:
+
+```CSS
+.ReactModal__Body--open {
+ overflow: hidden;
+}
+```
+
#### For the entire portal
To specify a class to be applied to the entire portal, you may use the