Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit 1af023f

Browse files
PaquitoSoftCarlosCortizasCT
andauthoredApr 5, 2022
docs: queryByRole new description option (#1035)
Co-authored-by: Carlos Martinez <[email protected]>
1 parent 83cf800 commit 1af023f

File tree

1 file changed

+39
-5
lines changed

1 file changed

+39
-5
lines changed
 

‎docs/queries/byrole.mdx

Lines changed: 39 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ getByRole(
2020
exact?: boolean = true,
2121
hidden?: boolean = false,
2222
name?: TextMatch,
23+
description?: TextMatch,
2324
normalizer?: NormalizerFn,
2425
selected?: boolean,
2526
checked?: boolean,
@@ -50,11 +51,11 @@ because the `button` element has default characteristics that conflict with the
5051
> will not include elements with a subclass role like `switch`.
5152
5253
You can query the returned element(s) by their
53-
[accessible name](https://www.w3.org/TR/accname-1.1/). The accessible name is
54-
for simple cases equal to e.g. the label of a form element, or the text content
55-
of a button, or the value of the `aria-label` attribute. It can be used to query
56-
a specific element if multiple elements with the same role are present on the
57-
rendered content. For an in-depth guide check out
54+
[accessible name or description](https://www.w3.org/TR/accname-1.1/). The
55+
accessible name is for simple cases equal to e.g. the label of a form element,
56+
or the text content of a button, or the value of the `aria-label` attribute. It
57+
can be used to query a specific element if multiple elements with the same role
58+
are present on the rendered content. For an in-depth guide check out
5859
["What is an accessible name?" from ThePacielloGroup](https://developer.paciellogroup.com/blog/2017/04/what-is-an-accessible-name/).
5960
If you only query for a single element with `getByText('The name')` it's
6061
oftentimes better to use `getByRole(expectedRole, { name: 'The name' })`. The
@@ -314,3 +315,36 @@ To learn more about the `aria-level` property, see
314315

315316
> The `level` option is _only_ applicable to the `heading` role. An error will
316317
> be thrown when used with any other role.
318+
319+
### `description`
320+
321+
You can filter the returned elements by their
322+
[accessible description](https://www.w3.org/TR/accname-1.1/#mapping_additional_nd_description)
323+
for those cases where you have several elements with the same role and they
324+
don't have an accessible name but they do have a description.<br /> This would
325+
be the case for elements with
326+
[alertdialog](https://www.w3.org/TR/wai-aria-1.1/#alertdialog) role, where the
327+
`aria-describedby` attribute is used to describe the element's content.
328+
329+
For example in
330+
331+
```html
332+
<body>
333+
<ul>
334+
<li role="alertdialog" aria-describedby="notification-id-1">
335+
<div><button>Close</button></div>
336+
<div id="notification-id-1">You have unread emails</div>
337+
</li>
338+
<li role="alertdialog" aria-describedby="notification-id-2">
339+
<div><button>Close</button></div>
340+
<div id="notification-id-2">Your session is about to expire</div>
341+
</li>
342+
</ul>
343+
</body>
344+
```
345+
346+
You can query a specific element like this
347+
348+
```js
349+
getByrole('alertdialog', {description: 'Your session is about to expire'})
350+
```

0 commit comments

Comments
 (0)
Please sign in to comment.