Skip to content

Commit d80c584

Browse files
eps1lontimdeschryverMatanBobi
authored
feat(ByRole): Allow filter by value state (#1230)
* feat(ByRole): Allow filter by value state * Update docs/queries/byrole.mdx Co-authored-by: Tim Deschryver <28659384+timdeschryver@users.noreply.github.com> * Update docs/queries/byrole.mdx Co-authored-by: Matan Borenkraout <Matanbobi@gmail.com> * Update docs/queries/byrole.mdx Co-authored-by: Tim Deschryver <28659384+timdeschryver@users.noreply.github.com> --------- Co-authored-by: Tim Deschryver <28659384+timdeschryver@users.noreply.github.com> Co-authored-by: Matan Borenkraout <Matanbobi@gmail.com>
1 parent 4575c9d commit d80c584

File tree

1 file changed

+69
-0
lines changed

1 file changed

+69
-0
lines changed

‎docs/queries/byrole.mdx‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,12 @@ getByRole(
2929
expanded?: boolean,
3030
queryFallbacks?: boolean,
3131
level?: number,
32+
value?: {
33+
min?: number,
34+
max?: number,
35+
now?: number,
36+
text?: TextMatch,
37+
}
3238
}): HTMLElement
3339
```
3440

@@ -343,6 +349,69 @@ To learn more about the `aria-level` property, see
343349
> The `level` option is _only_ applicable to the `heading` role. An error will
344350
> be thrown when used with any other role.
345351
352+
### `value`
353+
354+
A range widget can be queried by any value `getByRole('heading')` or by a
355+
specific value using the `level` option
356+
`getByRole('spinbutton', { value: { now: 5, min: 0, max: 10, text: 'medium' } })`.
357+
358+
Note that you don't have to specify all properties in `value`. A subset is
359+
sufficient e.g. `getByRole('heading', { value: { now: 5, text: 'medium' } })`.
360+
361+
Given the example below,
362+
363+
```html
364+
<body>
365+
<section>
366+
<button
367+
role="spinbutton"
368+
aria-valuenow="5"
369+
aria-valuemin="0"
370+
aria-valuemax="10"
371+
aria-valuetext="medium"
372+
>
373+
Volume
374+
</button>
375+
<button
376+
role="spinbutton"
377+
aria-valuenow="3"
378+
aria-valuemin="0"
379+
aria-valuemax="10"
380+
aria-valuetext="medium"
381+
>
382+
Pitch
383+
</button>
384+
</section>
385+
</body>
386+
```
387+
388+
you can query specific spinbutton(s) with the following queries,
389+
390+
```js
391+
getByRole('heading', {value: {now: 5}})
392+
// <button>Volume</button>
393+
394+
getAllByRole('heading', {value: {min: 0}})
395+
// [
396+
// <button>Volume</button>,
397+
// <button>Pitch</button>
398+
// ]
399+
```
400+
401+
> Every specified property in `value` must match. For example, if you query for
402+
> `{value: {min: 0, now: 3}}` `aria-valuemin` must be equal to 0 **AND**
403+
> `aria-valuenow` must be equal to 3
404+
405+
> The `value` option is _only_ applicable to certain roles (check the linked MDN
406+
> pages below for applicable roles). An error will be thrown when used with any
407+
> other role.
408+
409+
To learn more about the `aria-value*` properties, see
410+
[MDN `aria-valuemin`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemin),
411+
[MDN `aria-valuemax`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemax),
412+
[MDN `aria-valuenow`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuenow),
413+
[MDN `aria-valuetext`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuetext).
414+
346415
### `description`
347416

348417
You can filter the returned elements by their

0 commit comments

Comments
 (0)