Skip to content

Commit 4c1e590

Browse files
ianprime0509diasbruno
ianprime0509
authored and
diasbruno
committed
Expand documentation
* Add more information about styling CSS classes and transitions * Add section on accessibility, including app element details (addresses #576) * Create missing `examples/README.md` and `contributing/README.md` * Reorganize initial book section (with subsection labels)
1 parent 72c57cb commit 4c1e590

File tree

10 files changed

+229
-25
lines changed

10 files changed

+229
-25
lines changed

‎docs/README.md

+6-6
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
55
We maintain that accessibility is a key component of any modern web application. As such, we have created this modal in such a way that it fulfills the accessibility requirements of the modern web. We seek to keep the focus on accessibility while providing a functional, capable modal component for general use.
66

7-
## Installation
7+
## Installation {#installation}
88

99
To install the stable version you can use [npm](https://npmjs.org/) or [yarn](https://yarnpkg.com):
1010

@@ -13,7 +13,7 @@ To install the stable version you can use [npm](https://npmjs.org/) or [yarn](ht
1313
$ yarn add react-modal
1414

1515

16-
## General Usage
16+
## General Usage {#usage}
1717

1818
The following is an example of using react-modal specifying all the possible props and options:
1919

@@ -88,7 +88,7 @@ import ReactModal from 'react-modal';
8888
Boolean indicating if the modal should restore focus to the element that
8989
had focus prior to its display.
9090
*/
91-
shouldReturnFocusAfterClose={true}
91+
shouldReturnFocusAfterClose={true}
9292
/*
9393
String indicating the role of the modal, allowing the 'dialog' role to be applied if desired.
9494
*/
@@ -104,17 +104,17 @@ import ReactModal from 'react-modal';
104104
labelledby: "heading",
105105
describedby: "full_description"
106106
}}
107-
/*
107+
/*
108108
Overlay ref callback.
109109
*/
110110
overlayRef={setOverlayRef}
111-
/*
111+
/*
112112
Content ref callback.
113113
*/
114114
contentRef={setContentRef}
115115
/>
116116
```
117117

118-
## License
118+
## License {#license}
119119

120120
MIT

‎docs/SUMMARY.md

+10-3
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,18 @@
11
# Summary
22

3-
* [Read Me](/README.md)
3+
* [Overview](/README.md)
4+
* [Installation](/README.md#installation)
5+
* [Usage](/README.md#usage)
6+
* [License](/README.md#license)
47

5-
* [Development](dev/README.md)
8+
* [Accessibility](accessibility/README.md)
9+
* [The app element](accessibility/README.md#app-element)
10+
* [Keyboard navigation](accessibility/README.md#keyboard)
11+
* [Custom ARIA attributes](accessibility/README.md#aria)
612

713
* [Styles](styles/README.md)
814
* [Using CSS Classes](styles/classes.md)
9-
* [Overriding Defaults](styles/defaults.md)
15+
* [Transitions](styles/transitions.md)
1016

1117
* [Testing](testing/README.md)
1218

@@ -20,3 +26,4 @@
2026
* [Using Global Style Overrides](examples/global_overrides.md)
2127

2228
* [Contributing](contributing/README.md)
29+
* [Development setup](contributing/development.md)

‎docs/accessibility/README.md

+66
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
## Accessibility
2+
3+
react-modal aims to be fully accessible, using the
4+
[WAI-ARIA](https://www.w3.org/WAI/intro/aria) guidelines to support users of
5+
assistive technologies. This page describes some of react-modal's
6+
accessibility-oriented features, along with their configuration options.
7+
8+
### The app element {#app-element}
9+
10+
It is important for users of screenreaders that other page content be hidden
11+
(via the `aria-hidden` attribute) while the modal is open. To allow
12+
react-modal to do this, you should call `Modal.setAppElement` with a query
13+
selector identifying the root of your app. For example, if your app content is
14+
located inside an element with the ID `root`, you could place the following
15+
call somewhere in your code before any modals are opened:
16+
17+
```js
18+
Modal.setAppElement('#root');
19+
```
20+
21+
You can also pass a DOM element directly, so that the above example could be
22+
rewritten:
23+
24+
```js
25+
Modal.setAppElement(document.getElementById('root'));
26+
```
27+
28+
If you are already applying the `aria-hidden` attribute to your app content
29+
through other means, you can pass the `ariaHideApp={false}` prop to your modal
30+
to avoid getting a warning that your app element is not specified.
31+
32+
### Keyboard navigation {#keyboard}
33+
34+
When the modal is opened, it restricts keyboard navigation using the tab key to
35+
elements within the modal content. This ensures that elements outside the
36+
modal (which are not visible while the modal is open) do not receive focus
37+
unexpectedly.
38+
39+
By default, when the modal is closed, focus will be restored to the element
40+
that was focused before the modal was opened. To disable this behavior, you
41+
can pass the `shouldReturnFocusAfterClose={false}` prop to your modal.
42+
43+
The modal can be closed using the escape key, unless the
44+
`shouldCloseOnEsc={false}` prop is passed. Disabling this behavior may cause
45+
accessibility issues for keyboard users, however, so it is not recommended.
46+
47+
### Custom ARIA attributes {#aria}
48+
49+
To pass custom ARIA attributes to your modal, you can use the `aria` prop,
50+
which accepts an object whose keys are the attributes you want to set (without
51+
the leading `aria-` prefix). For example, you could have an alert modal with a
52+
title as well as a longer description:
53+
54+
```jsx
55+
<Modal
56+
isOpen={modalIsOpen}
57+
aria={{
58+
labelledby: "heading",
59+
describedby: "full_description"
60+
}}>
61+
<h1 id="heading">Alert</h1>
62+
<div id="full_description">
63+
<p>Description goes here.</p>
64+
</div>
65+
</Modal>
66+
```

‎docs/contributing/README.md

+42
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
## Contributing
2+
3+
### Commit Subjects
4+
5+
If your patch **changes the API or fixes a bug** please use one of the
6+
following prefixes in your commit subject:
7+
8+
- `[fixed] ...`
9+
- `[changed] ...`
10+
- `[added] ...`
11+
- `[removed] ...`
12+
13+
That ensures the subject line of your commit makes it into the
14+
auto-generated changelog. Do not use these tags if your change doesn't
15+
fix a bug and doesn't change the public API.
16+
17+
Commits with changed, added, or removed, must be reviewed by another
18+
collaborator.
19+
20+
#### When using `[changed]` or `[removed]`...
21+
22+
Please include an upgrade path with example code in the commit message.
23+
If it doesn't make sense to do this, then it doesn't make sense to use
24+
`[changed]` or `[removed]` :)
25+
26+
### Docs
27+
28+
Please update the README with any API changes, the code and docs should
29+
always be in sync.
30+
31+
### Development
32+
33+
- `npm start` runs the dev server to run/develop examples
34+
- `npm test` will run the tests.
35+
- `scripts/test` same as `npm test` but keeps karma running and watches
36+
for changes
37+
38+
### Build
39+
40+
Please do not include the output of `scripts/build` in your commits, we
41+
only do this when we release. (Also, you probably don't need to build
42+
anyway unless you are fixing something around our global build.)

‎docs/dev/README.md ‎docs/contributing/development.md

+4-4
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Development
1+
### Development setup
22

33
`react-modal` uses `make` to build and publish new versions and documentation.
44

@@ -7,21 +7,21 @@ It works as a checklist for the future releases to keep everything updated such
77

88
The minimun works as a normal `npm script`.
99

10-
## Usage
10+
#### Usage
1111

1212
Once you clone `react-modal`, you can run `sh bootstrap.sh` to check
1313
and download dependencies not managed by `react-modal` such as `gitbook-cli`.
1414

1515
It will also show information about the current versions of `node`, `npm`,
1616
`yarn` and `jq` available.
1717

18-
## List of `npm` commands:
18+
#### List of `npm` commands:
1919

2020
$ npm start -s or yarn start # to run examples
2121
$ npm run tests
2222
$ npm run lint
2323

24-
## List of `make` commands:
24+
#### List of `make` commands:
2525

2626
$ make help # show all make commands available
2727
$ make deps # npm install, gitbook plugins...

‎docs/examples/README.md

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
## Examples
2+
3+
The following sub-sections contain several examples of basic usage, hosted on
4+
[CodePen](https://codepen.io).
5+
6+
The `examples` directory in the project root also contains some examples which
7+
you can run locally. To build and run those examples using a local development
8+
server, run either
9+
10+
```
11+
$ npm start
12+
```
13+
14+
or
15+
16+
```
17+
$ yarn run start
18+
```
19+
20+
and then point your browser to `localhost:8080`.

‎docs/styles/README.md

+7-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
## Styles
22

3-
Styles passed into the Modal via the `style` prop are merged with the defaults. The default styles are:
3+
Styles passed into the Modal via the `style` prop are merged with the defaults.
4+
The default styles are defined in the `Modal.defaultStyles` object and are
5+
shown below.
46

57
```jsx
68
<Modal
@@ -32,3 +34,7 @@ Styles passed into the Modal via the `style` prop are merged with the defaults.
3234
...
3335
>
3436
```
37+
38+
You can change the default styles by modifying `Modal.defaultStyles`. Please
39+
note that specifying a [CSS class](classes.md) for the overlay or the content
40+
will disable the default styles for that component.

‎docs/styles/classes.md

+44-8
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,58 @@
11
### CSS Classes
22

33
Sometimes it may be preferable to use CSS classes rather than inline styles.
4+
react-modal can be configured to use CSS classes to style the modal content and
5+
overlay, as well as the document body and the portal within which the modal is
6+
mounted.
47

5-
You can use the `className` and `overlayClassName` props to specify a given CSS
6-
class for each of those.
8+
#### For the content and overlay
9+
10+
You can use the `className` and `overlayClassName` props to control the CSS
11+
classes that are applied to the modal content and the overlay, respectively.
12+
Each of these props may be a single string containing the class name to apply
13+
to the component.
14+
15+
Alternatively, you may pass an object with the `base`, `afterOpen` and
16+
`beforeClose` keys, where the value corresponding to each key is a class name.
17+
The `base` class will always be applied to the component, the `afterOpen` class
18+
will be applied after the modal has been opened and the `beforeClose` class
19+
will be applied after the modal has requested to be closed (e.g. when the user
20+
presses the escape key or clicks on the overlay).
21+
22+
Please note that the `beforeClose` class will have no effect unless the
23+
`closeTimeoutMS` prop is set to a non-zero value, since otherwise the modal
24+
will be closed immediately when requested. Thus, if you are using the
25+
`afterOpen` and `beforeClose` classes to provide transitions, you may want to
26+
set `closeTimeoutMS` to the length (in milliseconds) of your closing
27+
transition.
28+
29+
If you specify `className`, the [default content styles](README.md) will not be
30+
applied. Likewise, if you specify `overlayClassName`, the default overlay
31+
styles will not be applied.
32+
33+
If no class names are specified for the overlay, the default classes
34+
`ReactModal__Overlay`, `ReactModal__Overlay--after-open` and
35+
`ReactModal__Overlay--before-close` will be applied; the default classes for
36+
the content use the analogous prefix `ReactModal__Content`. Please note that
37+
any styles applied using these default classes will not override the default
38+
styles as they would if specified using the `className` or `overlayClassName`
39+
props.
40+
41+
#### For the document body
742

843
You can override the default class that is added to `document.body` when the
944
modal is open by defining a property `bodyOpenClassName`.
1045

11-
It's required that `bodyOpenClassName` must be `constant string`, otherwise we
12-
would end up with a complex system to manage which class name should appear or
13-
be removed from `document.body` from which modal (if using multiple modals
46+
The `bodyOpenClassName` prop must be a *constant string*; otherwise, we would
47+
require a complex system to manage which class name should be added to or
48+
removed from `document.body` from which modal (if using multiple modals
1449
simultaneously).
1550

1651
`bodyOpenClassName` can support adding multiple classes to `document.body` when
1752
the modal is open. Add as many class names as you desire, delineated by spaces.
1853

19-
Note: If you provide those props all default styles will not be applied, leaving
20-
all styles under control of the CSS class.
54+
#### For the entire portal
2155

22-
The `portalClassName` can also be used however there are no styles by default applied
56+
To specify a class to be applied to the entire portal, you may use the
57+
`portalClassName` prop. By default, there are no styles applied to the portal
58+
itself.

‎docs/styles/defaults.md

-3
This file was deleted.

‎docs/styles/transitions.md

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
### Transitions
2+
3+
Using [CSS classes](classes.md), it is possible to implement transitions for
4+
when the modal is opened or closed. By placing the following CSS somewhere in
5+
your project's styles, you can make the modal content fade in when it is opened
6+
and fade out when it is closed:
7+
8+
```css
9+
.ReactModal__Content {
10+
opacity: 0;
11+
}
12+
13+
.ReactModal__Content--after-open {
14+
opacity: 1;
15+
transition: opacity 150ms;
16+
}
17+
18+
.ReactModal__Content--before-close {
19+
opacity: 0;
20+
}
21+
```
22+
23+
In order for the close transition to take effect, you will also need to pass
24+
the `closeTimeoutMS={150}` prop to each of your modals.
25+
26+
The above example will apply the fade transition globally, affecting all modals
27+
whose `afterOpen` and `beforeClose` classes have not been set via the
28+
`className` prop. To apply the transition to one modal only, you can change
29+
the above class names and pass an object to your modal's `className` prop as
30+
described in the [previous section](classes.md).

0 commit comments

Comments
 (0)