# Cypress Documentation
# Source: https://raw.githubusercontent.com/cypress-io/cypress-documentation/main/docs/api/commands/find.mdx
# Path: docs/api/commands/find.mdx

---
title: 'find | Cypress Documentation'
description: Get the descendent DOM elements of a specific selector in Cypress.
sidebar_label: find
slug: /api/commands/find
---

<ProductHeading product="app" />

# find

Get the descendent DOM elements of a specific selector.

:::info

The querying behavior of this command matches exactly how
[`.find()`](http://api.jquery.com/find) works in jQuery.

:::

## Syntax

```javascript
.find(selector)
.find(selector, options)
```

### Usage

<Icon name="check-circle" color="green" /> **Correct Usage**

```javascript
cy.get('.article').find('footer') // Yield 'footer' within '.article'
```

<Icon name="exclamation-triangle" color="red" /> **Incorrect Usage**

```javascript
cy.find('.progress') // Errors, cannot be chained off 'cy'
cy.exec('node start').find() // Errors, 'exec' does not yield DOM element
```

### Arguments

<Icon name="angle-right" /> **selector _(String selector)_**

A selector used to filter matching descendent DOM elements.

<Icon name="angle-right" /> **options _(Object)_**

Pass in an options object to change the default behavior of `.find()`.

| Option             | Default                                                                        | Description                                                                                                  |
| ------------------ | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| `log`              | `true`                                                                         | Displays the command in the [Command log](/app/core-concepts/open-mode#Command-Log)                          |
| `timeout`          | [`defaultCommandTimeout`](/app/references/configuration#Timeouts)              | Time to wait for `.find()` to resolve before [timing out](#Timeouts)                                         |
| `includeShadowDom` | [`includeShadowDom` config option value](/app/references/configuration#Global) | Whether to traverse shadow DOM boundaries and include elements within the shadow DOM in the yielded results. |

<HeaderYields />

- `.find()` yields the new DOM element(s) it found.
- `.find()` is a query, and it is _safe_ to chain further commands.

## Examples

### Selector

#### Get li's within parent

```html
<ul id="parent">
  <li class="first"></li>
  <li class="second"></li>
</ul>
```

```javascript
// yields [<li class="first"></li>, <li class="second"></li>]
cy.get('#parent').find('li')
```

## Rules

<HeaderRequirements />

- `.find()` requires being chained off a command that yields DOM element(s).

<HeaderAssertions />

- `.find()` will automatically [retry](/app/core-concepts/retry-ability)
  until the element(s)
  [exist in the DOM](/app/core-concepts/introduction-to-cypress#Implicit-Assertions).
- `.find()` will automatically [retry](/app/core-concepts/retry-ability)
  until all chained assertions have passed.

<HeaderTimeouts />

- `.find()` can time out waiting for the element(s) to
  [exist in the DOM](/app/core-concepts/introduction-to-cypress#Implicit-Assertions).
- `.find()` can time out waiting for assertions you've added to pass.

## Command Log

**_Find the li's within the nav_**

```javascript
cy.get('.left-nav>.nav').find('>li')
```

The commands above will display in the Command Log as:

<DocsImage
  src="/img/api/find/find-li-of-uls-in-test.png"
  alt="Command Log find"
/>

When clicking on the `find` command within the command log, the console outputs
the following:

<DocsImage
  src="/img/api/find/find-in-console-shows-list-and-yields.png"
  alt="console.log find"
/>

## History

| Version                                  | Changes                          |
| ---------------------------------------- | -------------------------------- |
| [5.2.0](/app/references/changelog#5-2-0) | Added `includeShadowDom` option. |

## See also

- [`cy.get()`](/api/commands/get)