Skip to content

Commit

Permalink
[chore] Move API documentation from README to gitbook
Browse files Browse the repository at this point in the history
  • Loading branch information
@ianprime0509 @diasbruno
ianprime0509 authored and diasbruno committed Feb 20, 2018
1 parent 4c1e590 commit 241b8a6
Show file tree
Hide file tree
Showing 5 changed files with 91 additions and 226 deletions.
236 changes: 18 additions & 218 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
isOpen={bool}
onAfterOpen={afterOpenFn}
onRequestClose={requestCloseFn}
closeTimeoutMS={n}
style={customStyle}
contentLabel="Modal"
>
<h1>Modal Content</h1>
<p>Etc.</p>
</Modal>
```

> 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
<Modal
isOpen={modalIsOpen}
aria={{
labelledby: "heading",
describedby: "full_description"
}}>
<h1 id="heading">H1</h1>
<div id="full_description">
<p>Description goes here.</p>
</div>
</Modal>
```

## Styles

Styles are passed with the `style` prop, an object with 2 keys, 'overlay' and 'content' like so

```jsx
<Modal
...
style={{
overlay: {
position: 'fixed',
top: 0,
left: 0,
right: 0,
bottom: 0,
backgroundColor: 'rgba(255, 255, 255, 0.75)'
},
content: {
position: 'absolute',
top: '40px',
left: '40px',
right: '40px',
bottom: '40px',
border: '1px solid #ccc',
background: '#fff',
overflow: 'auto',
WebkitOverflowScrolling: 'touch',
borderRadius: '4px',
outline: 'none',
padding: '20px'
}
}}
...
>
```

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
<Modal
...
className={{
base: 'myClass',
afterOpen: 'myClass_after-open',
beforeClose: 'myClass_before-close'
}}
overlayClassName={{
base: 'myOverlayClass',
afterOpen: 'myOverlayClass_after-open',
beforeClose: 'myOverlayClass_before-close'
}}
...
>
```

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
...
parentSelector={getParent}
...
>
<p>Modal Content.</p>
</Modal>
```

### 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
<Modal
...
overlayRef={node => this.overlayRef = node}
contentRef={node => this.contentRef = node}
...
>
<p>Modal Content.</p>
</Modal>
```
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';
Expand Down Expand Up @@ -294,33 +109,18 @@ class App extends React.Component {
ReactDOM.render(<App />, 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
<Modal
isOpen={bool}
onAfterOpen={afterOpenFn}
onRequestClose={requestCloseFn}
closeTimeoutMS={n}
shouldCloseOnOverlayClick={false}
style={customStyle}
contentLabel="No Overlay Click Modal"
>

<h1>Force Modal</h1>
<p>Modal cannot be closed when clicking the overlay area</p>
<button onClick={handleCloseFunc}>Close Modal...</button>
</Modal>
```
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)
44 changes: 43 additions & 1 deletion docs/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand Down Expand Up @@ -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
...
parentSelector={getParent}
...
>
<p>Modal Content.</p>
</Modal>
```

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
<Modal
...
overlayRef={node => this.overlayRef = node}
contentRef={node => this.contentRef = node}
...
>
<p>Modal Content.</p>
</Modal>
```

## License {#license}

MIT
6 changes: 4 additions & 2 deletions docs/SUMMARY.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
19 changes: 15 additions & 4 deletions docs/accessibility/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
12 changes: 11 additions & 1 deletion docs/styles/classes.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 241b8a6

Please sign in to comment.