From 915a1cbd941ad1da2df595783a4375bba7558c4a Mon Sep 17 00:00:00 2001
From: Aaron Pettengill <aaron.pettengill.violin@gmail.com>
Date: Sun, 6 Oct 2019 10:19:10 -0400
Subject: [PATCH] Update documentation for `ByLabelText` queries

Relates to [this PR](https://github.com/testing-library/dom-testing-library/pull/373).
---
 docs/dom-testing-library/api-queries.md | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

diff --git a/docs/dom-testing-library/api-queries.md b/docs/dom-testing-library/api-queries.md
index 1be322750..8c383faf3 100644
--- a/docs/dom-testing-library/api-queries.md
+++ b/docs/dom-testing-library/api-queries.md
@@ -131,11 +131,20 @@ cy.getByLabelText('username').should('exist')
 
 <!--END_DOCUSAURUS_CODE_TABS-->
 
-It will NOT find the input node for label text broken up by elements. For this
-case, you can provide a `selector` in the options:
+You may also need to filter down the results of the query.
+For that you can use the `selector` option:
 
-```html
-<label> <span>Username</span> <input /> </label>
+```js
+// Label containing multiple elements
+<label>
+  <span>Username</span>
+  <input />
+</label>
+
+// Multiple elements labelled via aria-labelledby
+<label id="username">Username</label>
+<input aria-labelledby="username" />
+<span aria-labelledby="username">Please enter your username</span>
 ```
 
 ```js