|
| 1 | +import {Layout} from '../../src/Layout'; |
| 2 | +export default Layout; |
| 3 | + |
| 4 | +export const section = 'Guides'; |
| 5 | +export const description = 'How to build with accessibility, internationalization, and interactions.'; |
| 6 | + |
| 7 | +# Quality |
| 8 | + |
| 9 | +<PageDescription>React Aria is built around three core principles: **Accessibility**, **Internationalization**, and **Interactions**. Learn how to apply these tools to build high quality UIs that work for everyone, everywhere, and on every device.</PageDescription> |
| 10 | + |
| 11 | +## Accessibility |
| 12 | + |
| 13 | +Accessible applications are usable by everyone, including people with disabilities. Accessibility benefits all users — not just those using assistive technologies — by improving efficiency, consistency, and usability. |
| 14 | + |
| 15 | +React Aria provides built-in support for screen readers and keyboard navigation, following the [WAI-ARIA](https://www.w3.org/TR/wai-aria-1.2/) and [ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/) guidelines. It supplies the correct semantics via ARIA roles and attributes, handles keyboard and pointer events, manages focus, and provides screen reader announcements. React Aria components are tested across a wide variety of devices, browsers, and screen readers. |
| 16 | + |
| 17 | +Be sure to create an accessible visual design with meaningful labels, sufficient [color contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast) and [hit target sizes](https://www.w3.org/WAI/WCAG22/Understanding/target-size-enhanced), visible [focus rings](https://www.w3.org/WAI/WCAG22/Understanding/focus-appearance), and respect [motion preferences](https://www.w3.org/WAI/WCAG21/Understanding/animation-from-interactions). The [WCAG guidelines](https://www.w3.org/WAI/WCAG22/Understanding/) are a good resource to reference when designing and building components with React Aria. |
| 18 | + |
| 19 | +### Labeling |
| 20 | + |
| 21 | +Most components should have a visible label, which is usually provided by rendering a `<Label>` element within it. This is associated with the component automatically. |
| 22 | + |
| 23 | +```tsx |
| 24 | +import {TextField, Label, Input} from 'react-aria-components'; |
| 25 | + |
| 26 | +<TextField> |
| 27 | + {/*- begin highlight -*/} |
| 28 | + <Label>First name</Label> |
| 29 | + {/*- end highlight -*/} |
| 30 | + <Input /> |
| 31 | +</TextField> |
| 32 | +``` |
| 33 | + |
| 34 | +When a component doesn't have a visible label, it must have an [aria-label](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) or [aria-labelledby](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) prop to provide an accessible name. |
| 35 | + |
| 36 | +```tsx |
| 37 | +import {ProgressBar} from 'react-aria-components'; |
| 38 | + |
| 39 | +<ProgressBar |
| 40 | + /*- begin highlight -*/ |
| 41 | + aria-label="Processing" /> |
| 42 | + /*- end highlight -*/ |
| 43 | +``` |
| 44 | + |
| 45 | +### Supported screen readers |
| 46 | + |
| 47 | +React Aria is tested across a variety of devices, browsers, and screen readers. |
| 48 | + |
| 49 | +* [VoiceOver on macOS](https://www.apple.com/accessibility/mac/vision/) in Safari and Chrome |
| 50 | +* [JAWS](https://www.freedomscientific.com/products/software/jaws/) on Windows in Firefox and Chrome |
| 51 | +* [NVDA](https://www.nvaccess.org) on Windows in Firefox and Chrome |
| 52 | +* [VoiceOver on iOS](https://www.apple.com/accessibility/iphone/vision/) |
| 53 | +* [TalkBack](https://www.android.com/accessibility/) on Android in Chrome |
| 54 | + |
| 55 | +### Automated testing |
| 56 | + |
| 57 | +Automated accessibility testing tools sometimes catch false positives in React Aria. These are documented in our [wiki](https://github.com/adobe/react-spectrum/wiki/Known-accessibility-false-positives). |
| 58 | + |
| 59 | +## Internationalization |
| 60 | + |
| 61 | +Localization is an important way to make your application usable by the widest number of people. React Aria includes localized strings for 30+ languages, handles dates and numbers in many calendar and numbering systems, and supports right-to-left interactions (e.g. keyboard navigation). |
| 62 | + |
| 63 | +Make sure your design supports right-to-left layout, and adapts to different languages (e.g. using appropriate fonts). Modern CSS grid and flex layouts are automatically mirrored depending on the direction, and [logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values) can be used to adapt margins, paddings, borders, etc. |
| 64 | + |
| 65 | +### Setting the locale |
| 66 | + |
| 67 | +React Aria automatically detects the user's current language by default. Use the `I18nProvider` component to set the locale to a specific value. You should also set the `lang` and `dir` attributes on the root-most element of your application. |
| 68 | + |
| 69 | +```tsx |
| 70 | +import {I18nProvider, useLocale} from 'react-aria-components'; |
| 71 | + |
| 72 | +<I18nProvider locale="fr-FR"> |
| 73 | + <App /> |
| 74 | +</I18nProvider> |
| 75 | + |
| 76 | +function App() { |
| 77 | + let {locale, direction} = useLocale(); |
| 78 | + |
| 79 | + return ( |
| 80 | + <html lang={locale} dir={direction}> |
| 81 | + {/* your app here */} |
| 82 | + </html> |
| 83 | + ); |
| 84 | +} |
| 85 | +``` |
| 86 | + |
| 87 | +### Supported locales |
| 88 | + |
| 89 | +<ul style={{columnWidth: 200, paddingLeft: 16, fontFamily: 'adobe-clean-spectrum-vf'}}> |
| 90 | + <li>Arabic (United Arab Emirates)</li> |
| 91 | + <li>Bulgarian (Bulgaria)</li> |
| 92 | + <li>Chinese (Simplified)</li> |
| 93 | + <li>Chinese (Traditional)</li> |
| 94 | + <li>Croatian (Croatia)</li> |
| 95 | + <li>Czech (Czech Republic)</li> |
| 96 | + <li>Danish (Denmark)</li> |
| 97 | + <li>Dutch (Netherlands)</li> |
| 98 | + <li>English (Great Britain)</li> |
| 99 | + <li>English (United States)</li> |
| 100 | + <li>Estonian (Estonia)</li> |
| 101 | + <li>Finnish (Finland)</li> |
| 102 | + <li>French (Canada)</li> |
| 103 | + <li>French (France)</li> |
| 104 | + <li>German (Germany)</li> |
| 105 | + <li>Greek (Greece)</li> |
| 106 | + <li>Hebrew (Israel)</li> |
| 107 | + <li>Hungarian (Hungary)</li> |
| 108 | + <li>Italian (Italy)</li> |
| 109 | + <li>Japanese (Japan)</li> |
| 110 | + <li>Korean (Korea)</li> |
| 111 | + <li>Latvian (Latvia)</li> |
| 112 | + <li>Lithuanian (Lithuania)</li> |
| 113 | + <li>Norwegian (Norway)</li> |
| 114 | + <li>Polish (Poland)</li> |
| 115 | + <li>Portuguese (Brazil)</li> |
| 116 | + <li>Romanian (Romania)</li> |
| 117 | + <li>Russian (Russia)</li> |
| 118 | + <li>Serbian (Serbia)</li> |
| 119 | + <li>Slovakian (Slovakia)</li> |
| 120 | + <li>Slovenian (Slovenia)</li> |
| 121 | + <li>Spanish (Spain)</li> |
| 122 | + <li>Swedish (Sweden)</li> |
| 123 | + <li>Turkish (Turkey)</li> |
| 124 | + <li>Ukrainian (Ukraine)</li> |
| 125 | +</ul> |
| 126 | + |
| 127 | +## Interactions |
| 128 | + |
| 129 | +Modern web apps run on everything from desktops to mobile devices to TVs, with users interacting through mouse, touch, keyboard, and assistive technologies. React Aria normalizes these differences, delivering consistent “press”, “hover”, and “focus” behaviors across all browsers and input types. |
| 130 | + |
| 131 | +React Aria components provide data attributes and render props to style these states: |
| 132 | + |
| 133 | +* `data-pressed` – like the `:active` pseudo class, but removed when the pointer is dragged off. |
| 134 | +* `data-hovered` – like `:hover`, but not applied on touch devices, preventing sticky hover states. |
| 135 | +* `data-focus-visible` – like `:focus-visible`, but not on input click or programmatic focus. |
| 136 | + |
| 137 | +These states also come with corresponding events such as `onPress` and `onHoverStart`. To use these events in your own custom components, see hooks such as [usePress](usePress.html), [useHover](useHover.html), [useMove](useMove.html), and [useFocusRing](useFocusRing.html). |
| 138 | + |
| 139 | +Read our blog post series to learn more about the intricacies behind these interactions. |
| 140 | + |
| 141 | +* [Building a Button Part 1: Press Events](blog/building-a-button-part-1.html) |
| 142 | +* [Building a Button Part 2: Hover Interactions](blog/building-a-button-part-2.html) |
| 143 | +* [Building a Button Part 3: Keyboard Focus Behavior](blog/building-a-button-part-3.html) |
| 144 | + |
| 145 | +Higher level interaction patterns such as [selection](selection.html) and [drag and drop](dnd.html) are also built on top of these low level primitives. |
0 commit comments