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

---
title: 'click | Cypress Documentation'
description: Click a DOM element in Cypress.
sidebar_label: click
slug: /api/commands/click
---

<ProductHeading product="app" />

# click

Click a DOM element.

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

## Syntax

```javascript
.click()
.click(options)
.click(position)
.click(position, options)
.click(x, y)
.click(x, y, options)
```

### Usage

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

```javascript
cy.get('.btn').click() // Click on button
cy.focused().click() // Click on el with focus
cy.contains('Welcome').click() // Click on first el containing 'Welcome'
```

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

```javascript
cy.click('.btn') // Errors, cannot be chained off 'cy'
cy.window().click() // Errors, 'window' does not yield DOM element
```

### Arguments

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

The position where the click should be issued. The `center` position is the
default position. Valid positions are `topLeft`, `top`, `topRight`, `left`,
`center`, `right`, `bottomLeft`, `bottom`, and `bottomRight`.

<DocsImage
  src="/img/api/coordinates-diagram.jpg"
  alt="cypress-command-positions-diagram"
/>

<Icon name="angle-right" /> **x _(Number)_**

The distance in pixels from the element's left to issue the click.

<Icon name="angle-right" /> **y _(Number)_**

The distance in pixels from the element's top to issue the click.

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

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

| Option                       | Default                                                                     | Description                                                                                                                                     |
| ---------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `altKey`                     | `false`                                                                     | Activates the alt key (option key for Mac). Aliases: `optionKey`.                                                                               |
| `animationDistanceThreshold` | [`animationDistanceThreshold`](/app/references/configuration#Actionability) | The distance in pixels an element must exceed over time to be [considered animating](/app/core-concepts/interacting-with-elements#Animations).  |
| `ctrlKey`                    | `false`                                                                     | Activates the control key. Aliases: `controlKey`.                                                                                               |
| `log`                        | `true`                                                                      | Displays the command in the [Command log](/app/core-concepts/open-mode#Command-Log)                                                             |
| `force`                      | `false`                                                                     | Forces the action, disables [waiting for actionability](#Assertions)                                                                            |
| `metaKey`                    | `false`                                                                     | Activates the meta key (Windows key or command key for Mac). Aliases: `commandKey`, `cmdKey`.                                                   |
| `multiple`                   | `false`                                                                     | Serially click multiple elements                                                                                                                |
| `scrollBehavior`             | [`scrollBehavior`](/app/references/configuration#Actionability)             | Viewport position to where an element [should be scrolled](/app/core-concepts/interacting-with-elements#Scrolling) before executing the command |
| `shiftKey`                   | `false`                                                                     | Activates the shift key.                                                                                                                        |
| `timeout`                    | [`defaultCommandTimeout`](/app/references/configuration#Timeouts)           | Time to wait for `.click()` to resolve before [timing out](#Timeouts)                                                                           |
| `waitForAnimations`          | [`waitForAnimations`](/app/references/configuration#Actionability)          | Whether to wait for elements to [finish animating](/app/core-concepts/interacting-with-elements#Animations) before executing the command.       |

<HeaderYields />

- `.click()` 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 `.click()`.

## Examples

### No Args

#### Click a link in a nav

```javascript
cy.get('.nav > a').click()
```

### Position

#### Specify a corner of the element to click

Click the top right corner of the button.

```javascript
cy.get('img').click('topRight')
```

### Coordinates

#### Specify explicit coordinates relative to the top left corner

The click below will be issued inside of the element (15px from the left and
40px from the top).

```javascript
cy.get('#top-banner').click(15, 40)
```

### Options

#### Force a click regardless of its actionable state

Forcing a click overrides the
[actionable checks](/app/core-concepts/interacting-with-elements#Forcing)
Cypress applies and will automatically fire the events.

```javascript
cy.get('.close').as('closeBtn')
cy.get('@closeBtn').click({ force: true })
```

#### Force a click with position argument

```javascript
cy.get('#collapse-sidebar').click('bottomLeft', { force: true })
```

#### Force a click with relative coordinates

```javascript
cy.get('#footer .next').click(5, 60, { force: true })
```

#### Click all elements with id starting with 'btn'

By default, Cypress will error if you're trying to click multiple elements. By
passing `{ multiple: true }` Cypress will iteratively apply the click to each
element and will also log to the
[Command Log](/app/core-concepts/open-mode#Command-Log) multiple times.

```javascript
cy.get('[id^=btn]').click({ multiple: true })
```

#### Click with key combinations

The `.click()` command may also be fired with key modifiers in order to simulate
holding key combinations while clicking, such as `ALT + click`.

:::info

You can also use key combinations during [.type()](/api/commands/type). This
offers options to hold down keys across multiple commands. See
[Key Combinations](/api/commands/type#Key-Combinations) for more information.

:::

The following keys can be combined with `.click()` through the `options`.

| Option     | Notes                                                                                         |
| ---------- | --------------------------------------------------------------------------------------------- |
| `altKey`   | Activates the alt key (option key for Mac). Aliases: `optionKey`.                             |
| `ctrlKey`  | Activates the control key. Aliases: `controlKey`.                                             |
| `metaKey`  | Activates the meta key (Windows key or command key for Mac). Aliases: `commandKey`, `cmdKey`. |
| `shiftKey` | Activates the shift key.                                                                      |

#### Shift click

```js
// execute a SHIFT + click on the first <li>
cy.get('li:first').click({
  shiftKey: true,
})
```

## Notes

### Actionability

#### The element must first reach actionability

`.click()` is an "action command" that follows all the rules of
[Actionability](/app/core-concepts/interacting-with-elements).

### Focus

#### Focus is given to the first focusable element

For example, clicking a `<span>` inside of a `<button>` gives the focus to the
button, since that's what would happen in a real user scenario.

However, Cypress additionally handles situations where a child descendent is
clicked inside of a focusable parent, but actually isn't visually inside the
parent (per the CSS Object Model). In those cases if no focusable parent is
found the window is given focus instead (which matches real browser behavior).

### Cancellation

#### Mousedown cancellation will not cause focus

If the mousedown event has its default action prevented ( `e.preventDefault()` )
then the element will not receive focus as per the spec.

## Rules

<HeaderRequirements />

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

<HeaderAssertions />

- `.click()` will automatically wait for the element to reach an
  [actionable state](/app/core-concepts/interacting-with-elements).
- `.click()`will automatically [retry](/app/core-concepts/retry-ability)
  until all chained assertions have passed.

<HeaderTimeouts />

- `.click()` can time out waiting for the element to reach an
  [actionable state](/app/core-concepts/interacting-with-elements).
- `.click()` can time out waiting for assertions you've added to pass.

## Command Log

**_Click the button_**

```javascript
cy.get('.action-btn').click()
```

The commands above will display in the Command Log as:

<DocsImage
  src="/img/api/click/click-button-in-form-during-test.png"
  alt="Command log for click"
/>

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

<DocsImage
  src="/img/api/click/click-coords-and-events-in-console.png"
  alt="console.log for click"
/>

## History

| Version                                  | Changes                                                                                                             |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| [6.1.0](/app/references/changelog#6-1-0) | Added option `scrollBehavior`                                                                                       |
| [3.5.0](/app/references/changelog#3-5-0) | Added sending `mouseover`, `mousemove`, `mouseout`, `pointerdown`, `pointerup`, and `pointermove` during `.click()` |

## See also

- [`.check()`](/api/commands/check)
- [`.click()` examples in kitchensink app](https://github.com/cypress-io/cypress-example-kitchensink/blob/master/cypress/e2e/2-advanced-examples/actions.cy.js#L67)
- [`.dblclick()`](/api/commands/dblclick)
- [`.rightclick()`](/api/commands/rightclick)
- [`.select()`](/api/commands/select)
- [`.submit()`](/api/commands/submit)
- [`.type()`](/api/commands/type)
- ['When can the test click?' blog](https://www.cypress.io/blog/2019/01/22/when-can-the-test-click/)