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

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

<ProductHeading product="app" />

# dblclick

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

## Syntax

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

### Usage

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

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

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

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

### Arguments

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

The position where the double 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 double click.

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

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

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

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

| 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`                   | `true`                                                                      | 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 `.dblclick()` 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 />

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

## Examples

### No Args

#### Double click an anchor link

```javascript
cy.get('a#nav1').dblclick() // yields the <a>
```

### Position

#### Specify a position of the element to double click

Click the bottom center of the button.

```javascript
cy.get('button').dblclick('bottom')
```

### Coordinates

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

The double click below will be issued inside of the element (30px from the left
and 10px from the top).

```javascript
cy.get('button').dblclick(30, 10)
```

### Options

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

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

```javascript
cy.get('button').dblclick({ force: true })
```

#### Force a double click with position argument

```javascript
cy.get('button').dblclick('topRight', { force: true })
```

#### Force a double click with relative coordinates

```javascript
cy.get('button').dblclick(60, 60, { force: true })
```

#### Double click all buttons found on the page

By default, Cypress will iteratively apply the double click to each element and
will also log to the
[Command Log](/app/core-concepts/open-mode#Command-Log) multiple times.

You can turn this off by passing `multiple: false` to `.dblclick()`.

```javascript
cy.get('button').dblclick({ multiple: false })
```

#### Double click with key combinations

The `.dblclick()` command may also be fired with key modifiers in order to
simulate holding key combinations while double clicking, such as
`SHIFT + double 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 modifiers can be combined with `.dblclick()`.

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

##### Alt click

```js
// execute ALT + dblclick on the first <li>
cy.get('li:first').dblclick({
  altKey: true,
})
```

## Notes

### Actionability

#### The element must first reach actionability

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

## Rules

<HeaderRequirements />

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

<HeaderAssertions />

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

<HeaderTimeouts />

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

## Command Log

**_Double click on a div_**

```javascript
cy.get('.action-div').dblclick()
```

The commands above will display in the Command Log as:

<DocsImage
  src="/img/api/dblclick/double-click-in-testing.png"
  alt="Command Log dblclick"
/>

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

<DocsImage
  src="/img/api/dblclick/element-double-clicked-on.png"
  alt="console.log dblclick"
/>

## 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 support for options `force` and `multiple`.                                                                       |
| [3.5.0](/app/references/changelog#3-5-0) | Added support for `position`, `x`, and `y` arguments.                                                                   |
| [3.5.0](/app/references/changelog#3-5-0) | Added sending `mouseover`, `mousemove`, `mouseout`, `pointerdown`, `pointerup`, and `pointermove` during `.dblclick()`. |

## See also

- [`.click()`](/api/commands/click)
- [`.rightclick()`](/api/commands/rightclick)