docs(within): add within docs

Thanks to @Dajust

Closes #111

Author: Kent C. Dodds

.all-contributorsrc

@@ -342,6 +342,15 @@
       "contributions": [
         "doc"
       ]
+    },
+    {
+      "login": "Dajust",
+      "name": "Justice Mba",
+      "avatar_url": "https://avatars3.githubusercontent.com/u/8015514?v=4",
+      "profile": "https://github.com/Dajust",
+      "contributions": [
+        "doc"
+      ]
     }
   ]
 }

README.md

@@ -15,7 +15,7 @@
 [![version][version-badge]][package] [![downloads][downloads-badge]][npmtrends]
 [![MIT License][license-badge]][license]
 
-[![All Contributors](https://img.shields.io/badge/all_contributors-34-orange.svg?style=flat-square)](#contributors)
+[![All Contributors](https://img.shields.io/badge/all_contributors-35-orange.svg?style=flat-square)](#contributors)
 [![PRs Welcome][prs-badge]][prs] [![Code of Conduct][coc-badge]][coc]
 [![Join the community on Spectrum][spectrum-badge]][spectrum]
 
@@ -85,6 +85,7 @@ facilitate testing implementation details). Read more about this in
   - [`fireEvent(node: HTMLElement, event: Event)`](#fireeventnode-htmlelement-event-event)
   - [`waitForElement`](#waitforelement)
   - [`wait`](#wait)
+  - [`within`](#within)
 - [`TextMatch`](#textmatch)
 - [`query` APIs](#query-apis)
 - [`queryAll` and `getAll` APIs](#queryall-and-getall-apis)
@@ -541,6 +542,29 @@ test('can fill in the form after loaded', async () => {
 })
 ```
 
+### `within`
+
+> [Read full docs from `dom-testing-library`](https://github.com/kentcdodds/dom-testing-library/blob/master/README.md#within-and-getqueriesforelement-apis)
+
+The queries returned from `render` are scoped to the entire page. Sometimes,
+there is no garauntee that the text, placeholder, or label you want to query is
+unique on the page. So you might want to explicity tell react-render-dom to get
+an element only within a particular section of the page. within is a helper
+function for this case.
+
+Example: To get the text 'hello' only within a section called 'messages', you
+could do:
+
+```javascript
+import {render, within} from 'react-testing-library'
+
+// ...
+
+const {getByTestId} = render(/* stuff */)
+const messagesSection = getByTestId('messages')
+const hello = within(messagesSection).getByText('hello')
+```
+
 ## `TextMatch`
 
 Several APIs accept a `TextMatch` which can be a `string`, `regex` or a
@@ -921,7 +945,7 @@ Thanks goes to these people ([emoji key][emojis]):
 | [<img src="https://avatars1.githubusercontent.com/u/1241511?s=460&v=4" width="100px;"/><br /><sub><b>Anto Aravinth</b></sub>](https://github.com/antoaravinth)<br />[💻](https://github.com/kentcdodds/react-testing-library/commits?author=antoaravinth "Code") [⚠️](https://github.com/kentcdodds/react-testing-library/commits?author=antoaravinth "Tests") [📖](https://github.com/kentcdodds/react-testing-library/commits?author=antoaravinth "Documentation") | [<img src="https://avatars2.githubusercontent.com/u/3462296?v=4" width="100px;"/><br /><sub><b>Jonah Moses</b></sub>](https://github.com/JonahMoses)<br />[📖](https://github.com/kentcdodds/react-testing-library/commits?author=JonahMoses "Documentation") | [<img src="https://avatars1.githubusercontent.com/u/4002543?v=4" width="100px;"/><br /><sub><b>Łukasz Gandecki</b></sub>](http://team.thebrain.pro)<br />[💻](https://github.com/kentcdodds/react-testing-library/commits?author=lgandecki "Code") [⚠️](https://github.com/kentcdodds/react-testing-library/commits?author=lgandecki "Tests") [📖](https://github.com/kentcdodds/react-testing-library/commits?author=lgandecki "Documentation") | [<img src="https://avatars2.githubusercontent.com/u/498274?v=4" width="100px;"/><br /><sub><b>Ivan Babak</b></sub>](https://sompylasar.github.io)<br />[🐛](https://github.com/kentcdodds/react-testing-library/issues?q=author%3Asompylasar "Bug reports") [🤔](#ideas-sompylasar "Ideas, Planning, & Feedback") | [<img src="https://avatars3.githubusercontent.com/u/4439618?v=4" width="100px;"/><br /><sub><b>Jesse Day</b></sub>](https://github.com/jday3)<br />[💻](https://github.com/kentcdodds/react-testing-library/commits?author=jday3 "Code") | [<img src="https://avatars0.githubusercontent.com/u/15199?v=4" width="100px;"/><br /><sub><b>Ernesto García</b></sub>](http://gnapse.github.io)<br />[💬](#question-gnapse "Answering Questions") [💻](https://github.com/kentcdodds/react-testing-library/commits?author=gnapse "Code") [📖](https://github.com/kentcdodds/react-testing-library/commits?author=gnapse "Documentation") | [<img src="https://avatars2.githubusercontent.com/u/2747424?v=4" width="100px;"/><br /><sub><b>Josef Maxx Blake</b></sub>](http://jomaxx.com)<br />[💻](https://github.com/kentcdodds/react-testing-library/commits?author=jomaxx "Code") [📖](https://github.com/kentcdodds/react-testing-library/commits?author=jomaxx "Documentation") [⚠️](https://github.com/kentcdodds/react-testing-library/commits?author=jomaxx "Tests") |
 | [<img src="https://avatars1.githubusercontent.com/u/29602306?v=4" width="100px;"/><br /><sub><b>Michal Baranowski</b></sub>](https://twitter.com/baranovskim)<br />[📝](#blog-mbaranovski "Blogposts") [✅](#tutorial-mbaranovski "Tutorials") | [<img src="https://avatars3.githubusercontent.com/u/13985684?v=4" width="100px;"/><br /><sub><b>Arthur Puthin</b></sub>](https://github.com/aputhin)<br />[📖](https://github.com/kentcdodds/react-testing-library/commits?author=aputhin "Documentation") | [<img src="https://avatars2.githubusercontent.com/u/21194045?v=4" width="100px;"/><br /><sub><b>Thomas Chia</b></sub>](https://github.com/thchia)<br />[💻](https://github.com/kentcdodds/react-testing-library/commits?author=thchia "Code") [📖](https://github.com/kentcdodds/react-testing-library/commits?author=thchia "Documentation") | [<img src="https://avatars3.githubusercontent.com/u/20430611?v=4" width="100px;"/><br /><sub><b>Thiago Galvani</b></sub>](http://ilegra.com/)<br />[📖](https://github.com/kentcdodds/react-testing-library/commits?author=thiagopaiva99 "Documentation") | [<img src="https://avatars1.githubusercontent.com/u/19828824?v=4" width="100px;"/><br /><sub><b>Christian</b></sub>](http://Chriswcs.github.io)<br />[⚠️](https://github.com/kentcdodds/react-testing-library/commits?author=ChrisWcs "Tests") | [<img src="https://avatars3.githubusercontent.com/u/1571667?v=4" width="100px;"/><br /><sub><b>Alex Krolick</b></sub>](https://alexkrolick.com)<br />[💬](#question-alexkrolick "Answering Questions") [📖](https://github.com/kentcdodds/react-testing-library/commits?author=alexkrolick "Documentation") [💡](#example-alexkrolick "Examples") [🤔](#ideas-alexkrolick "Ideas, Planning, & Feedback") | [<img src="https://avatars3.githubusercontent.com/u/1239401?v=4" width="100px;"/><br /><sub><b>Johann Hubert Sonntagbauer</b></sub>](https://github.com/johann-sonntagbauer)<br />[💻](https://github.com/kentcdodds/react-testing-library/commits?author=johann-sonntagbauer "Code") [📖](https://github.com/kentcdodds/react-testing-library/commits?author=johann-sonntagbauer "Documentation") [⚠️](https://github.com/kentcdodds/react-testing-library/commits?author=johann-sonntagbauer "Tests") |
 | [<img src="https://avatars2.githubusercontent.com/u/2224291?v=4" width="100px;"/><br /><sub><b>Maddi Joyce</b></sub>](http://www.maddijoyce.com)<br />[💻](https://github.com/kentcdodds/react-testing-library/commits?author=maddijoyce "Code") | [<img src="https://avatars2.githubusercontent.com/u/10080111?v=4" width="100px;"/><br /><sub><b>Ryan Vice</b></sub>](http://www.vicesoftware.com)<br />[📖](https://github.com/kentcdodds/react-testing-library/commits?author=RyanAtViceSoftware "Documentation") | [<img src="https://avatars1.githubusercontent.com/u/7942604?v=4" width="100px;"/><br /><sub><b>Ian Wilson</b></sub>](https://ianwilson.io)<br />[📝](#blog-iwilsonq "Blogposts") [✅](#tutorial-iwilsonq "Tutorials") | [<img src="https://avatars2.githubusercontent.com/u/1635491?v=4" width="100px;"/><br /><sub><b>Daniel</b></sub>](https://github.com/InExtremaRes)<br />[🐛](https://github.com/kentcdodds/react-testing-library/issues?q=author%3AInExtremaRes "Bug reports") [💻](https://github.com/kentcdodds/react-testing-library/commits?author=InExtremaRes "Code") | [<img src="https://avatars0.githubusercontent.com/u/767959?v=4" width="100px;"/><br /><sub><b>Giorgio Polvara</b></sub>](https://twitter.com/Gpx)<br />[🐛](https://github.com/kentcdodds/react-testing-library/issues?q=author%3AGpx "Bug reports") [🤔](#ideas-Gpx "Ideas, Planning, & Feedback") | [<img src="https://avatars2.githubusercontent.com/u/132233?v=4" width="100px;"/><br /><sub><b>John Gozde</b></sub>](https://github.com/jgoz)<br />[💻](https://github.com/kentcdodds/react-testing-library/commits?author=jgoz "Code") | [<img src="https://avatars0.githubusercontent.com/u/8203211?v=4" width="100px;"/><br /><sub><b>Sam Horton</b></sub>](https://twitter.com/SavePointSam)<br />[📖](https://github.com/kentcdodds/react-testing-library/commits?author=SavePointSam "Documentation") [💡](#example-SavePointSam "Examples") [🤔](#ideas-SavePointSam "Ideas, Planning, & Feedback") |
-| [<img src="https://avatars2.githubusercontent.com/u/10452163?v=4" width="100px;"/><br /><sub><b>Richard Kotze (mobile)</b></sub>](http://www.richardkotze.com)<br />[📖](https://github.com/kentcdodds/react-testing-library/commits?author=rkotze "Documentation") | [<img src="https://avatars2.githubusercontent.com/u/10819833?v=4" width="100px;"/><br /><sub><b>Brahian E. Soto Mercedes</b></sub>](https://github.com/sotobuild)<br />[📖](https://github.com/kentcdodds/react-testing-library/commits?author=sotobuild "Documentation") | [<img src="https://avatars2.githubusercontent.com/u/7151559?v=4" width="100px;"/><br /><sub><b>Benoit de La Forest</b></sub>](https://github.com/bdelaforest)<br />[📖](https://github.com/kentcdodds/react-testing-library/commits?author=bdelaforest "Documentation") | [<img src="https://avatars3.githubusercontent.com/u/6624197?v=4" width="100px;"/><br /><sub><b>Salah</b></sub>](https://github.com/thesalah)<br />[💻](https://github.com/kentcdodds/react-testing-library/commits?author=thesalah "Code") [⚠️](https://github.com/kentcdodds/react-testing-library/commits?author=thesalah "Tests") | [<img src="https://avatars2.githubusercontent.com/u/370054?v=4" width="100px;"/><br /><sub><b>Adam Gordon</b></sub>](http://gordonizer.com)<br />[🐛](https://github.com/kentcdodds/react-testing-library/issues?q=author%3Aicfantv "Bug reports") [💻](https://github.com/kentcdodds/react-testing-library/commits?author=icfantv "Code") | [<img src="https://avatars2.githubusercontent.com/u/471278?v=4" width="100px;"/><br /><sub><b>Matija Marohnić</b></sub>](https://silvenon.com)<br />[📖](https://github.com/kentcdodds/react-testing-library/commits?author=silvenon "Documentation") |
+| [<img src="https://avatars2.githubusercontent.com/u/10452163?v=4" width="100px;"/><br /><sub><b>Richard Kotze (mobile)</b></sub>](http://www.richardkotze.com)<br />[📖](https://github.com/kentcdodds/react-testing-library/commits?author=rkotze "Documentation") | [<img src="https://avatars2.githubusercontent.com/u/10819833?v=4" width="100px;"/><br /><sub><b>Brahian E. Soto Mercedes</b></sub>](https://github.com/sotobuild)<br />[📖](https://github.com/kentcdodds/react-testing-library/commits?author=sotobuild "Documentation") | [<img src="https://avatars2.githubusercontent.com/u/7151559?v=4" width="100px;"/><br /><sub><b>Benoit de La Forest</b></sub>](https://github.com/bdelaforest)<br />[📖](https://github.com/kentcdodds/react-testing-library/commits?author=bdelaforest "Documentation") | [<img src="https://avatars3.githubusercontent.com/u/6624197?v=4" width="100px;"/><br /><sub><b>Salah</b></sub>](https://github.com/thesalah)<br />[💻](https://github.com/kentcdodds/react-testing-library/commits?author=thesalah "Code") [⚠️](https://github.com/kentcdodds/react-testing-library/commits?author=thesalah "Tests") | [<img src="https://avatars2.githubusercontent.com/u/370054?v=4" width="100px;"/><br /><sub><b>Adam Gordon</b></sub>](http://gordonizer.com)<br />[🐛](https://github.com/kentcdodds/react-testing-library/issues?q=author%3Aicfantv "Bug reports") [💻](https://github.com/kentcdodds/react-testing-library/commits?author=icfantv "Code") | [<img src="https://avatars2.githubusercontent.com/u/471278?v=4" width="100px;"/><br /><sub><b>Matija Marohnić</b></sub>](https://silvenon.com)<br />[📖](https://github.com/kentcdodds/react-testing-library/commits?author=silvenon "Documentation") | [<img src="https://avatars3.githubusercontent.com/u/8015514?v=4" width="100px;"/><br /><sub><b>Justice Mba</b></sub>](https://github.com/Dajust)<br />[📖](https://github.com/kentcdodds/react-testing-library/commits?author=Dajust "Documentation") |
 
 <!-- ALL-CONTRIBUTORS-LIST:END -->