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

---
title: 'each | Cypress Documentation'
description: Iterate through an array like structure in Cypress (arrays or objects with a `length` property).
sidebar_label: each
---

<ProductHeading product="app" />

# each

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

It is [unsafe](/app/core-concepts/retry-ability#Only-queries-are-retried) to
chain further commands that rely on the subject after `.each()`.

## Syntax

```javascript
.each(callbackFn)
```

### Usage

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

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

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

```javascript

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

### Arguments

<Icon name="angle-right" /> **callbackFn _(Function)_**

Pass a function that is invoked with the following arguments:

- `value`
- `index`
- `collection`

<HeaderYields />

- `.each()` yields the same subject it was given.
- It is [unsafe](/app/core-concepts/retry-ability#Only-queries-are-retried)
  to chain further commands that rely on the subject after `.each()`.

## Examples

### DOM Elements

**Iterate over an array of DOM elements**

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

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

### Promises

**Promises are awaited**

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

```javascript
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

<HeaderRequirements />

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

<HeaderAssertions />

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

<HeaderTimeouts />

- `.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()`](/api/commands/spread)
- [`.then()`](/api/commands/then)