feat(byRole): add documentation for new option of ByRole queries

savcni01 · savcni01 · commit c9b362c4b7ca · 2021-05-05T12:11:09.000+03:00
- docs for PR: testing-library/dom-testing-library#943 - according to issue: testing-library/dom-testing-library#864
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,
     expanded?: boolean,
     queryFallbacks?: boolean,
     level?: number,
@@ -162,6 +163,32 @@ you can get the "👍" button by calling `getByRole('button', { pressed: true })
 To learn more about the pressed state see
 [ARIA `aria-pressed`](https://www.w3.org/TR/wai-aria-1.2/#aria-pressed).
 
+### `current`
+
+Elements can represent the current item within a container or set of related
+elements.
+
+Despite current have list of values: `date`, `location`, `page`, `step`, `time`,
+`true`, `false`
+
+You can filter the returned elements by their current status by setting
+`current: true` (for any valid value) or `current: false` (for false).
+
+For example in
+
+```html
+<body>
+  <section>
+    <link href="current/page" aria-current="true">👍</link>
+    <link href="another/page" aria-current="false">👎</link>
+  </section>
+</body>
+```
+
+you can get the "👍" link by calling `getByRole('button', { current: true })`.
+To learn more about the current status see
+[ARIA `aria-current`](https://www.w3.org/TR/wai-aria-1.2/#aria-current).
+
 ### `expanded`
 
 You can filter the returned elements by their expanded state by setting
