--- id: api/commands/dblclick title: cy.dblclick() description: Double-click a DOM element in Cypress. section: api source_path: docs/api/commands/dblclick.mdx version: f97f06d85653c51afe39a9bd3cefda946807f150 updated_at: '2026-10-05T21:01:45.863Z' --- # dblclick Double-click a DOM element. It is [unsafe](/llm/markdown/app/core-concepts/retry-ability.md#Only-queries-are-retried) to chain further commands that rely on the subject after `.dblclick()`. ## Syntax ``` .dblclick() .dblclick(options) .dblclick(position) .dblclick(position, options) .dblclick(x, y) .dblclick(x, y, options) ``` ### Usage **Correct Usage** ``` cy.get('button').dblclick() // Double-click on button cy.focused().dblclick() // Double-click on element with focus cy.contains('Welcome').dblclick() // Double-click on first element containing 'Welcome' ``` **Incorrect Usage** ``` cy.dblclick('button') // Errors, cannot be chained off 'cy' cy.window().dblclick() // Errors, 'window' does not yield DOM element ``` ### Arguments **position _(String)_** The position where Cypress issues the double-click. The `center` position is the default position. Valid positions are `topLeft`, `top`, `topRight`, `left`, `center`, `right`, `bottomLeft`, `bottom`, and `bottomRight`. **x _(Number)_** The distance in pixels from the element's left to issue the double-click. **y _(Number)_** The distance in pixels from the element's top to issue the double-click. **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`](/llm/markdown/app/references/configuration.md#Actionability) | The distance in pixels an element must exceed over time to be [considered animating](/llm/markdown/app/core-concepts/interacting-with-elements.md#Animations). | | `ctrlKey` | `false` | Activates the control key. Aliases: `controlKey`. | | `log` | `true` | Displays the command in the [Command Log](/llm/markdown/app/core-concepts/open-mode.md#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 double-click multiple elements | | `scrollBehavior` | [`scrollBehavior`](/llm/markdown/app/references/configuration.md#Actionability) | Viewport position to where an element [should be scrolled](/llm/markdown/app/core-concepts/interacting-with-elements.md#Scrolling) before executing the command. Accepts a single alignment, a per-axis `{ block, inline }` object, or `false`. | | `shiftKey` | `false` | Activates the shift key. | | `timeout` | [`defaultCommandTimeout`](/llm/markdown/app/references/configuration.md#Timeouts) | Time to wait for `.dblclick()` to resolve before [timing out](#Timeouts) | | `waitForAnimations` | [`waitForAnimations`](/llm/markdown/app/references/configuration.md#Actionability) | Whether to wait for elements to [finish animating](/llm/markdown/app/core-concepts/interacting-with-elements.md#Animations) before executing the command. | ### Yields * `.dblclick()` yields the same subject it was given. * It is [unsafe](/llm/markdown/app/core-concepts/retry-ability.md#Only-queries-are-retried) to chain further commands that rely on the subject after `.dblclick()`. ## Examples ### No Args #### Double-click an anchor link in the navigation ``` cy.get('a#nav1').dblclick() // yields the ``` #### Double-click a label to edit an item inline Many apps turn a label, table cell, or file name into an input when you double-click it. The double-click usually replaces the element, so start a new chain from `cy` to reach the input instead of chaining off `.dblclick()`. ``` cy.get('[data-cy=todo-label]').first().dblclick() cy.get('[data-cy=todo-edit]').clear().type('Buy oat milk{enter}') cy.get('[data-cy=todo-label]').first().should('have.text', 'Buy oat milk') ``` #### Double-click one element out of several matches `.dblclick()` double-clicks [every element in its subject](#Double-click-every-element-that-matches-a-selector) by default, so a selector that matches several rows puts all of them into edit mode without an error. Narrow the query to the element you want with [`.eq()`](/llm/markdown/api/commands/eq.md), [`.first()`](/llm/markdown/api/commands/first.md), or [`cy.contains()`](/llm/markdown/api/commands/contains.md) with a selector and text. ``` cy.get('[data-cy=row]').eq(2).dblclick() cy.contains('[data-cy=file]', 'report.pdf').dblclick() ``` #### Wait for the request a double-click sends Register a [`cy.intercept()`](/llm/markdown/api/commands/intercept.md) before the double-click, then [`cy.wait()`](/llm/markdown/api/commands/wait.md) on its alias so the test continues only after the request completes. ``` cy.intercept('GET', '/api/files/*').as('openFile') cy.contains('[data-cy=file]', 'report.pdf').dblclick() cy.wait('@openFile') cy.get('[data-cy=preview]').should('be.visible') ``` #### Test an element that handles both click and double-click Cypress sends two `click` events before the `dblclick` event (see [Events](#Events)), so a click handler runs twice. Apps that respond to both often wait briefly after a click to see whether a second one follows. If yours uses a timer like that, freeze it with [`cy.clock()`](/llm/markdown/api/commands/clock.md), then advance it past your app's delay with [`cy.tick()`](/llm/markdown/api/commands/tick.md). The example below assumes a delay under 300 milliseconds. Without the tick, the `not.have.class` assertion passes before the timer fires, so it can't catch a single-click action that runs by mistake. ``` cy.clock() cy.get('[data-cy=photo]').dblclick() cy.tick(300) cy.get('[data-cy=lightbox]').should('be.visible') cy.get('[data-cy=photo]').should('not.have.class', 'selected') ``` ### Position #### Specify a position of the element to double-click Double-click the bottom center of the button. ``` cy.get('button').dblclick('bottom') ``` ### Coordinates #### Specify coordinates relative to the top-left corner Cypress issues the double-click below inside of the element (30px from the left and 10px from the top). ``` cy.get('button').dblclick(30, 10) ``` #### Double-click a precise spot on a map or canvas Coordinates matter when the double-click position changes the result, such as zooming a map in on the point under the cursor. ``` cy.get('[data-cy=map]').dblclick(200, 150) cy.get('[data-cy=zoom-level]').should('have.text', '4') ``` ### Options #### Force a double-click regardless of its actionable state Forcing a double-click overrides the [actionable checks](/llm/markdown/app/core-concepts/interacting-with-elements.md#Forcing) Cypress applies and fires the events. On a disabled element, a forced double-click fires both click sequences but not the `dblclick` event, so a `dblclick` handler on a disabled element never runs. ``` cy.get('button').dblclick({ force: true }) ``` #### Force a double-click with a position argument ``` cy.get('button').dblclick('topRight', { force: true }) ``` #### Force a double-click with relative coordinates ``` cy.get('button').dblclick(60, 60, { force: true }) ``` #### Double-click every element that matches a selector Unlike [`.click()`](/llm/markdown/api/commands/click.md), `.dblclick()` defaults to `{ multiple: true }`. When the subject contains several elements, Cypress double-clicks each one in turn, gives each double-click its own full timeout, and logs each one to the [Command Log](/llm/markdown/app/core-concepts/open-mode.md#Command-Log). ``` cy.get('[data-cy=todo-label]').dblclick() // double-clicks every label ``` Pass `{ multiple: false }` as a guard when a selector should match exactly one element. If it ever matches more, `.dblclick()` fails the test instead of double-clicking all of them. ``` cy.get('[data-cy=current-todo]').dblclick({ multiple: false }) ``` #### Double-click with key combinations Pass key modifiers to `.dblclick()` to hold down keys while it double-clicks, such as `ALT + double-click`. You can also use key combinations during [`.type()`](/llm/markdown/api/commands/type.md), which can hold keys down across multiple commands. See [Key Combinations](/llm/markdown/api/commands/type.md#Key-Combinations). The following keys can be combined with `.dblclick()` 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. | ##### Alt + double-click the first list item ``` // execute ALT + dblclick on the first
  • 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](/llm/markdown/app/core-concepts/interacting-with-elements.md). ### Events #### A double-click fires two clicks, then a dblclick Cypress fires the full [`.click()`](/llm/markdown/api/commands/click.md) event sequence twice, then a `dblclick` event, matching what a browser sends for a real double-click. The mouse events in the first click have a `detail` of `1`. The mouse events in the second click, and the `dblclick` event, have a `detail` of `2`. The `pointerdown` and `pointerup` events have a `detail` of `0`. Because each click follows the `.click()` rules, the [focus](/llm/markdown/api/commands/click.md#Focus) and [cancellation](/llm/markdown/api/commands/click.md#Cancellation) behavior of `.click()` applies to both clicks. ### Text selection #### A double-click does not select the word you double-click In a browser, double-clicking a word selects it. Cypress fires the double-click as simulated events, which don't trigger the browser's native text selection. `.dblclick()` doesn't select the word you double-click, in page text or in an input, and it leaves any text that was already selected in place. To select the text in an input or textarea, use [`.type('{selectall}')`](/llm/markdown/api/commands/type.md). ``` cy.get('[data-cy=title]').type('{selectall}') ``` ## Rules ### Requirements * `.dblclick()` requires being chained off a command that yields DOM element(s). * `.dblclick()` cannot be called on a `