---
id: api/commands/each
title: cy.each()
description: >-
  Iterate through an array like structure in Cypress (arrays or objects with a
  length property).
section: api
source_path: docs/api/commands/each.mdx
version: e6c8d867c21227247f14714fb5690c7c018983c5
updated_at: '2026-08-08T12:39:37.868Z'
---
# each

Iterate through an array like structure (arrays or objects with a `length` property).

## Syntax

```
.each(callbackFn)
```

### Usage

**Correct Usage**

```
cy.get('ul>li').each(() => {...}) // Iterate through each 'li'cy.getCookies().each(() => {...}) // Iterate through each cookie
```

**Incorrect Usage**

```
cy.each(() => {...})            // Errors, cannot be chained off 'cy'cy.clock().each(() => {...})    // Errors, 'clock' does not yield an array
```

### Arguments

**callbackFn _(Function)_**

Pass a function that is invoked with the following arguments:

*   `value` - the current item in the collection
*   `index` - the 0-based index of the current item in the collection
*   `collection` - the original collection being iterated over

### Yields

*   `.each()` yields the same subject it was given.
*   Because `.each()` is not a [query](/llm/markdown/app/core-concepts/retry-ability.md#Only-queries-are-retried), it is unsafe to chain further commands that act or assert on DOM elements after `.each()`, as those elements may have re-rendered and gone stale during iteration. Reading the yielded subject in a [`.then()`](/llm/markdown/api/commands/then.md) callback (as in the example below) is safe.

## Examples

### DOM Elements

**Iterate over an array of DOM elements**

```
cy.get('ul>li').each(($el, index, $list) => {  // $el is a wrapped jQuery element  if ($el.someMethod() === 'something') {    // wrap this element so we can    // use cypress commands on it    cy.wrap($el).click()  } else {    // do something else  }})
```

**The original array is always yielded**

No matter what is returned in the callback function, `.each()` will always yield the original array.

```
cy.get('li')  .should('have.length', 3)  .each(($li, index, $lis) => {    return 'something else'  })  .then(($lis) => {    expect($lis).to.have.length(3) // true  })
```

Here the `.then()` callback only _reads_ the yielded array, which is safe. If instead you needed to act or assert on DOM elements that your application may have re-rendered during iteration, re-query them with a Cypress query rather than reusing the subject yielded by `.each()`.

### Promises

**Promises are awaited**

If your callback function returns a `Promise`, it will be awaited before iterating over the next element in the collection.

```
cy.wrap([1, 2, 3]).each((num, i, array) => {  return new Cypress.Promise((resolve) => {    setTimeout(() => {      resolve()    }, num * 100)  })})
```

## Notes

### Return early

**Stop `each` prematurely**

You can stop the `.each()` loop early by returning `false` in the callback function.

## Rules

### Requirements

*   `.each()` requires being chained off a previous command.

### Assertions

*   `.each()` will only run assertions you have chained once, and will not [retry](/llm/markdown/app/core-concepts/retry-ability.md).

### Timeouts

*   `.each()` can time out waiting for a promise you've returned to resolve.

## Command Log

*   `cy.each()` does _not_ log in the Command Log

## See also

*   [`.spread()`](/llm/markdown/api/commands/spread.md)
*   [`.then()`](/llm/markdown/api/commands/then.md)