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

---
title: 'get | Cypress Documentation'
description: Get one or more DOM elements by selector or alias in Cypress.
sidebar_label: get
slug: /api/commands/get
---

<ProductHeading product="app" />

# get

Get one or more DOM elements by selector or
[alias](/app/core-concepts/variables-and-aliases).

:::info

The querying behavior of this command is similar to how
[`$(...)`](http://api.jquery.com/jQuery/) works in jQuery.

:::

## Syntax

```javascript
cy.get(selector)
cy.get(alias)
cy.get(selector, options)
cy.get(alias, options)
```

### Usage

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

```javascript
cy.get('.list > li') // Yield the <li>'s in .list
```

### Arguments

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

A selector used to filter matching DOM elements.

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

An alias as defined using the [`.as()`](/api/commands/as) command and referenced
with the `@` character and the name of the alias.

You can use `cy.get()` for aliases of primitives, regular objects, or even DOM
elements.

When using aliases with DOM elements, Cypress will query the DOM again if the
previously aliased DOM element has gone stale.

:::info

<strong>Core Concept</strong>

[You can read more about aliasing objects and elements in our Core Concept Guide](/app/core-concepts/variables-and-aliases#Aliases).

:::

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

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

| 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 `cy.get()` to resolve before [timing out](#Timeouts)                                        |
| `withinSubject`    | null                                                                           | Element to search for children in. If null, search begins from root-level DOM element                        |
| `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 />

- `cy.get()` yields the DOM element(s) it found, or the results of the alias
  lookup.
- `cy.get()` is a query, and it is _safe_ to chain further commands.

## Examples

### Selector

#### Get the input element

```javascript
cy.get('input').should('be.disabled')
```

#### Find the first `li` descendent within a `ul`

```javascript
cy.get('ul li:first').should('have.class', 'active')
```

#### Find the dropdown-menu and click it

```javascript
cy.get('.dropdown-menu').click()
```

#### Find 5 elements with the given data attribute

```javascript
cy.get('[data-test-id="test-example"]').should('have.length', 5)
```

#### Find the link with an href attribute containing the word "questions" and click it

```javascript
cy.get('a[href*="questions"]').click()
```

#### Find the element with id that starts with "local-"

```javascript
cy.get('[id^=local-]')
```

#### Find the element with id that ends with "-remote"

```javascript
cy.get('[id$=-remote]')
```

#### Find the element with id that starts with "local-" and ends with "-remote"

```javascript
cy.get('[id^=local-][id$=-remote]')
```

#### Find the element with id that has characters used in CSS like ".", ":".

```javascript
cy.get('#id\\.\\.\\.1234') // escape the character with \\
```

### `cy.get()` in the [`.within()`](/api/commands/within) command

Since `cy.get()` is chained off of `cy`, it always looks for the selector within
the entire `document`. The only exception is when used inside a
[.within()](/api/commands/within) command.

```javascript
cy.get('form').within(() => {
  cy.get('input').type('Pamela') // Only yield inputs within form
  cy.get('textarea').type('is a developer') // Only yield textareas within form
})
```

### Get vs Find

The `cy.get` command always starts its search from the
[cy.root](/api/commands/root) element. In most cases, it is the
`document` element, unless used inside the [.within()](/api/commands/within)
command. The [.find](/api/commands/find) command starts its search from
the current subject.

```html
<div class="test-title">cy.get vs .find</div>
<section id="comparison">
  <div class="feature">Both are querying commands</div>
</section>
```

```js
cy.get('#comparison')
  .get('div')
  // finds the div.test-title outside the #comparison
  // and the div.feature inside
  .should('have.class', 'test-title')
  .and('have.class', 'feature')
cy.get('#comparison')
  .find('div')
  // the search is limited to the tree at #comparison element
  // so it finds div.feature only
  .should('have.length', 1)
  .and('have.class', 'feature')
```

### Alias

For a detailed explanation of aliasing,
[read more about aliasing here](/app/core-concepts/variables-and-aliases#Aliases).

#### Get the aliased 'todos' elements

```javascript
cy.get('ul#todos').as('todos')

//...hack hack hack...

//later retrieve the todos
cy.get('@todos')
```

#### Get the aliased 'submitBtn' element

```javascript
beforeEach(() => {
  cy.get('button[type=submit]').as('submitBtn')
})

it('disables on click', () => {
  cy.get('@submitBtn').should('be.disabled')
})
```

#### Get the aliased 'users' fixture

```javascript
beforeEach(() => {
  cy.fixture('users.json').as('users')
})

it('disables on click', () => {
  // access the array of users
  cy.get('@users').then((users) => {
    // get the first user
    const user = users[0]

    cy.get('header').contains(user.name)
  })
})
```

## Rules

<HeaderRequirements />

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

<HeaderAssertions />

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

<HeaderTimeouts />

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

## Command Log

**_Get an input and assert on the value_**

```javascript
cy.get('input[name="firstName"]').should('have.value', 'Homer')
```

The commands above will display in the Command Log as:

<DocsImage
  src="/img/api/get/get-element-and-make-an-assertion.png"
  alt="Command Log get"
/>

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

<DocsImage
  src="/img/api/get/console-log-get-command-and-elements-found.png"
  alt="Console Log get"
/>

## History

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

## See also

- [`.as()`](/api/commands/as)
- [`cy.contains()`](/api/commands/contains)
- [`.find()`](/api/commands/find)
- [`.within()`](/api/commands/within)
- [Retry-ability](/app/core-concepts/retry-ability)