From 241b8a697c2141f1631b9666bda07b01f4972f56 Mon Sep 17 00:00:00 2001 From: Ian Johnson Date: Mon, 19 Feb 2018 19:23:53 -0500 Subject: [PATCH] [chore] Move API documentation from README to gitbook --- README.md | 236 +++-------------------------------- docs/README.md | 44 ++++++- docs/SUMMARY.md | 6 +- docs/accessibility/README.md | 19 ++- docs/styles/classes.md | 12 +- 5 files changed, 91 insertions(+), 226 deletions(-) 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