---
id: api/commands/find
title: find | Cypress Documentation
description: Get the descendent DOM elements of a specific selector in Cypress.
section: api
source_path: docs/api/commands/find.mdx
version: 204dffbf7fbb64b1fe8343a54ddcd869cc275f1f
updated_at: '2026-05-12T20:33:17.938Z'
---
# find

Get the descendent DOM elements of a specific selector.

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

## Syntax

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

### Usage

**Correct Usage**

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

**Incorrect Usage**

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

### Arguments

**selector _(String selector)_**

A selector used to filter matching descendent DOM elements.

**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](/llm/markdown/app/core-concepts/open-mode.md#Command-Log) |
| `timeout` | [`defaultCommandTimeout`](/llm/markdown/app/references/configuration.md#Timeouts) | Time to wait for `.find()` to resolve before [timing out](#Timeouts) |
| `includeShadowDom` | [`includeShadowDom` config option value](/llm/markdown/app/references/configuration.md#Global) | Whether to traverse shadow DOM boundaries and include elements within the shadow DOM in the yielded results. |

### Yields [Learn about subject management](/llm/markdown/app/core-concepts/introduction-to-cypress.md#Subject-Management)

*   `.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

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

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

## Rules

### Requirements [Learn about chaining commands](/llm/markdown/app/core-concepts/introduction-to-cypress.md#Chains-of-Commands)

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

### Assertions [Learn about assertions](/llm/markdown/app/core-concepts/introduction-to-cypress.md#Assertions)

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

### Timeouts [Learn about timeouts](/llm/markdown/app/core-concepts/introduction-to-cypress.md#Timeouts)

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

## Command Log

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

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

The commands above will display in the Command Log as:

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

## History

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

## See also

*   [`cy.get()`](/llm/markdown/api/commands/get.md)