-
Notifications
You must be signed in to change notification settings - Fork 4.2k
/
README.md
284 lines (166 loc) · 10.2 KB
/
README.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
# Modal
Modals give users information and choices related to a task they’re trying to accomplish. They can contain critical information, require decisions, or involve multiple tasks.
![An alert modal for trashing a post](https://wordpress.org/gutenberg/files/2019/04/Modal.png)
## Design guidelines
### Usage
A modal is a type of floating window that appears in front of content to provide critical information or ask for a decision. Modals disable all other functionality when they appear. A modal remains on screen until the user confirms it, dismisses it, or takes the required action.
While modals can be an effective way to disclose additional controls or information, they can also be a source of interruption for the user. For this reason, always question whether a modal is necessary, and work to avoid the situations in which they are required.
#### Principles
- **Focused**. Modals pull user attention away from the rest of the screen to focus their attention, ensuring that the modal’s content is addressed.
- **Direct**. Modal text should communicate important information and be dedicated to helping the user appropriately complete a task.
- **Helpful**. Modals should appear in response to a user task or an action to offer relevant and contextual information.
#### When to use
Modals are used for:
- Errors that block normal operation.
- Critical information that requires a specific user task, decision, or acknowledgement.
- Contextual information that appears in response to a user task or action.
### Anatomy
![A modal diagram with labels](https://wordpress.org/gutenberg/files/2019/04/Modal-diagram.png)
1. Container
2. Title
3. Supporting text
4. Buttons
5. Scrim
6. Close button (optional)
### Modal box and scrim
A modal is a type of window. Access to the rest of the UI is disabled until the modal is addressed. All modals are interruptive by design – their purpose is to have the user focus on content, so the modal surface appears in front of all other surfaces.
To clarify that the rest of the screen is inaccessible and to focus attention on the modal, surfaces behind the modal are scrimmed — they get a temporary overlay to obscure their content and make it less prominent.
### Title
A modal’s purpose is communicated through its title and button text.
All modals should have a title for accessibility reasons (the `contentLabel` prop can be used to set titles that aren't visible).
Titles should:
- Contain a brief, clear statement or question
- Avoid apologies (“Sorry for the interruption”), alarm (“Warning!”), or ambiguity (“Are you sure?”).
![A modal that asks "Trash post?"](https://wordpress.org/gutenberg/files/2019/04/Modal-do-1.png)
**Do**
This modal title poses a specific question, concisely explains the purpose the request, and provides clear actions.
![A modal that asks "Are you sure?"](https://wordpress.org/gutenberg/files/2019/04/Modal-dont-1.png)
**Don’t**
This modal creates ambiguity, and therefore unease — it leaves the user unsure about how to respond, or causes them to second-guess their answer.
### Buttons
#### Side-by-side buttons (recommended)
Side-by-side buttons display two text buttons next to one another.
![A modal with two buttons next to each other](https://wordpress.org/gutenberg/files/2019/04/Modal-buttons.png)
#### Stacked or full-width buttons
Use stacked buttons when you need to accommodate longer button text. Always place confirming actions above dismissive actions.
![A modal with two buttons stacked on top of each other](https://wordpress.org/gutenberg/files/2019/04/Modal-buttons-stacked.png)
### Behavior
Modals appear without warning, requiring users to stop their current task. They should be used sparingly — not every choice or setting warrants this kind of abrupt interruption.
#### Position
Modals retain focus until dismissed or the user completes an action, like choosing a setting. They shouldn’t be obscured by other elements or appear partially on screen.
#### Scrolling
Most modal content should avoid scrolling. Scrolling is permissible if the modal content exceeds the height of the modal (e.g. a list component with many rows). When a modal scrolls, the modal title is pinned at the top and the buttons are pinned at the bottom. This ensures that content remains visible alongside the title and buttons, even while scrolling.
Modals don’t scroll with elements outside of the modal, like the background.
When viewing a scrollable list of options, the modal title and buttons remain fixed.
#### Dismissing modals
Modals are dismissible in three ways:
- Tapping outside of the modal
- Tapping the “Cancel” button
- Tapping the “Close” icon button, or pressing the `esc` key
If the user’s ability to dismiss a modal is disabled, they must choose a modal action to proceed.
## Development guidelines
The modal is used to create an accessible modal over an application.
**Note:** The API for this modal has been mimicked to resemble [`react-modal`](https://github.com/reactjs/react-modal).
### Usage
The following example shows you how to properly implement a modal. For the modal to properly work it's important you implement the close logic for the modal properly.
```jsx
import { useState } from 'react';
import { Button, Modal } from '@wordpress/components';
const MyModal = () => {
const [ isOpen, setOpen ] = useState( false );
const openModal = () => setOpen( true );
const closeModal = () => setOpen( false );
return (
<>
<Button variant="secondary" onClick={ openModal }>
Open Modal
</Button>
{ isOpen && (
<Modal title="This is my modal" onRequestClose={ closeModal }>
<Button variant="secondary" onClick={ closeModal }>
My custom close button
</Button>
</Modal>
) }
</>
);
};
```
### Props
The set of props accepted by the component will be specified below.
Props not included in this set will be applied to the input elements.
#### `aria.describedby`: `string`
If this property is added, it will be added to the modal content `div` as `aria-describedby`.
- Required: No
#### `aria.labelledby`: `string`
If this property is added, it will be added to the modal content `div` as `aria-labelledby`.
Use this when you are rendering the title yourself within the modal's content area instead of using the `title` prop. This ensures the title is usable by assistive technology.
Titles are required for accessibility reasons, see `contentLabel` and `title` for other ways to provide a title.
- Required: No
- Default: if the `title` prop is provided, this will default to the id of the element that renders `title`
#### `bodyOpenClassName`: `string`
Class name added to the body element when the modal is open.
- Required: No
- Default: `modal-open`
#### `className`: `string`
If this property is added, it will an additional class name to the modal content `div`.
- Required: No
#### `contentLabel`: `string`
If this property is added, it will be added to the modal content `div` as `aria-label`.
Titles are required for accessibility reasons, see `aria.labelledby` and `title` for other ways to provide a title.
- Required: No
#### `focusOnMount`: `boolean | 'firstElement'` | 'firstContentElement'
If this property is true, it will focus the first tabbable element rendered in the modal.
If this property is false, focus will not be transferred and it is the responsibility of the consumer to ensure accessible focus management.
If set to `firstElement` focus will be placed on the first tabbable element anywhere within the Modal.
If set to `firstContentElement` focus will be placed on the first tabbable element within the Modal's **content** (i.e. children). Note that it is the responsibility of the consumer to ensure there is at least one tabbable element within the children **or the focus will be lost**.
- Required: No
- Default: `true`
#### headerActions
An optional React node intended to contain additional actions or other elements related to the modal, for example, buttons. Content is rendered in the top right corner of the modal and to the left of the close button, if visible.
- Required: No
- Default: `null`
#### `isDismissible`: `boolean`
If this property is set to false, the modal will not display a close icon and cannot be dismissed.
- Required: No
- Default: `true`
#### `isFullScreen`: `boolean`
This property when set to `true` will render a full screen modal.
- Required: No
- Default: `false`
#### `size`: `'small' | 'medium' | 'large' | 'fill'`
If this property is added it will cause the modal to render at a preset width, or expand to fill the screen. This prop will be ignored if `isFullScreen` is set to `true`.
- Required: No
Note: `Modal`'s width can also be controlled by adjusting the width of the modal's contents via CSS.
#### `onRequestClose`: ``
This function is called to indicate that the modal should be closed.
- Required: Yes
#### `overlayClassName`: `string`
If this property is added, it will an additional class name to the modal overlay `div`.
- Required: No
#### `role`: `AriaRole`
If this property is added, it will override the default role of the modal.
- Required: No
- Default: `dialog`
#### `shouldCloseOnClickOutside`: `boolean`
If this property is added, it will determine whether the modal requests to close when a mouse click occurs outside of the modal content.
- Required: No
- Default: `true`
#### `shouldCloseOnEsc`: `boolean`
If this property is added, it will determine whether the modal requests to close when the escape key is pressed.
- Required: No
- Default: `true`
#### `style`: `CSSProperties`
If this property is added, it will be added to the modal frame `div`.
- Required: No
#### `title`: `string`
This property is used as the modal header's title.
Titles are required for accessibility reasons, see `aria.labelledby` and `contentLabel` for other ways to provide a title.
- Required: No
#### `__experimentalHideHeader`: `boolean`
When set to `true`, the Modal's header (including the icon, title and close button) will not be rendered.
_Warning_: This property is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
- Required: No
- Default: `false`
## Related components
- To notify a user with a message of medium importance, use `Notice`.