feat(byRole): add documentation for new option (aria-current) of ByRole queries (#822)

savcni01 · eps1lon · web-flow · commit a888cd8e98e9 · 2021-08-25T15:42:55.000+02:00
Co-authored-by: eps1lon &lt;silbermann.sebastian@gmail.com&gt;
diff --git a/docs/queries/byrole.mdx b/docs/queries/byrole.mdx
@@ -24,6 +24,7 @@ getByRole(
     selected?: boolean,
     checked?: boolean,
     pressed?: boolean,
+    current?: boolean | string,
     expanded?: boolean,
     queryFallbacks?: boolean,
     level?: number,
@@ -142,6 +143,27 @@ state and which elements can have this state see
 > Checkboxes have a "mixed" state, which is considered neither checked nor
 > unchecked (details [here](https://www.w3.org/TR/html-aam-1.0/#details-id-56)).
 
+### `current`
+
+You can filter the returned elements by their current state by setting
+`current: boolean | string`.
+Note that no `aria-current` attribute will match `current: false` since `false` is the default value for `aria-current`.
+
+For example in
+
+```html
+<body>
+  <nav>
+    <a href="current/page" aria-current="true">👍</a>
+    <a href="another/page">👎</a>
+  </nav>
+</body>
+```
+
+you can get the "👍" link by calling `getByRole('link', { current: true })` and the "👎" by calling `getByRole('link', { current: false })`.
+To learn more about the current state see
+[ARIA `aria-current`](https://www.w3.org/TR/wai-aria-1.2/#aria-current).
+
 ### `pressed`
 
 Buttons can have a pressed state. You can filter the returned elements by their
