{ "doc": { "id": "api/commands/first", "title": "cy.first()", "description": "Get the first DOM element within a set of DOM elements in Cypress.", "section": "api", "source_path": "/llm/markdown/api/commands/first.md", "version": "f60251bf707b0077a9535579c9f90d615440cc35", "updated_at": "2026-10-16T10:56:58.670Z", "headings": [ { "id": "api/commands/first#first", "text": "first", "level": 1 }, { "id": "api/commands/first#syntax", "text": "Syntax", "level": 2 }, { "id": "api/commands/first#usage", "text": "Usage", "level": 3 }, { "id": "api/commands/first#arguments", "text": "Arguments", "level": 3 }, { "id": "api/commands/first#yields", "text": "Yields", "level": 3 }, { "id": "api/commands/first#examples", "text": "Examples", "level": 2 }, { "id": "api/commands/first#no-args", "text": "No Args", "level": 3 }, { "id": "api/commands/first#get-the-first-list-item-in-a-list", "text": "Get the first list item in a list", "level": 4 }, { "id": "api/commands/first#get-the-first-element-across-several-lists", "text": "Get the first element across several lists", "level": 4 }, { "id": "api/commands/first#common-workflows-with-first", "text": "Common workflows with .first()", "level": 3 }, { "id": "api/commands/first#scope-within-to-the-first-matching-element", "text": "Scope .within() to the first matching element", "level": 4 }, { "id": "api/commands/first#click-the-first-result-after-the-list-finishes-loading", "text": "Click the first result after the list finishes loading", "level": 4 }, { "id": "api/commands/first#assert-on-the-first-element-while-the-list-re-renders", "text": "Assert on the first element while the list re-renders", "level": 4 }, { "id": "api/commands/first#notes", "text": "Notes", "level": 2 }, { "id": "api/commands/first#how-first-compares-to-eq-0", "text": "How .first() compares to .eq(0)", "level": 3 }, { "id": "api/commands/first#selecting-the-first-element-that-matches-a-selector", "text": "Selecting the first element that matches a selector", "level": 3 }, { "id": "api/commands/first#rules", "text": "Rules", "level": 2 }, { "id": "api/commands/first#requirements", "text": "Requirements", "level": 3 }, { "id": "api/commands/first#assertions", "text": "Assertions", "level": 3 }, { "id": "api/commands/first#timeouts", "text": "Timeouts", "level": 3 }, { "id": "api/commands/first#command-log", "text": "Command Log", "level": 2 }, { "id": "api/commands/first#history", "text": "History", "level": 2 }, { "id": "api/commands/first#see-also", "text": "See also", "level": 2 } ] }, "chunks": [ { "id": "api/commands/first#syntax", "doc_id": "api/commands/first", "heading": "Syntax", "heading_level": 2, "content_markdown": "## Syntax\n\n```\n.first()\n.first(options)\n```\n\n### Usage\n\n**Correct Usage**\n\n```\ncy.get('nav a').first() // Yield first link in nav\n```\n\n**Incorrect Usage**\n\n```\ncy.first() // Errors, cannot be chained off 'cy'\ncy.getCookies().first() // Errors, 'getCookies' does not yield DOM element\n```\n\n### Arguments\n\n**options _(Object)_**\n\nPass in an options object to change the default behavior of `.first()`.\n\n| Option | Default | Description |\n| --- | --- | --- |\n| `log` | `true` | Displays the command in the [Command log](/llm/markdown/app/core-concepts/open-mode.md#Command-Log) |\n| `timeout` | [`defaultCommandTimeout`](/llm/markdown/app/references/configuration.md#Timeouts) | Time to wait for `.first()` to resolve before [timing out](#Timeouts) |\n\n### Yields\n\n* `.first()` yields the first DOM element within the set it was given.\n* `.first()` is a query, and it is _safe_ to chain further commands.\n", "section": "api", "anchors": [ "syntax" ], "path": "/llm/json/chunked/api/commands/first.json", "token_estimate": 171 }, { "id": "api/commands/first#usage", "doc_id": "api/commands/first", "heading": "Usage", "heading_level": 3, "content_markdown": "### Usage\n\n**Correct Usage**\n\n```\ncy.get('nav a').first() // Yield first link in nav\n```\n\n**Incorrect Usage**\n\n```\ncy.first() // Errors, cannot be chained off 'cy'\ncy.getCookies().first() // Errors, 'getCookies' does not yield DOM element\n```\n", "section": "api", "anchors": [ "usage" ], "path": "/llm/json/chunked/api/commands/first.json", "token_estimate": 47 }, { "id": "api/commands/first#arguments", "doc_id": "api/commands/first", "heading": "Arguments", "heading_level": 3, "content_markdown": "### Arguments\n\n**options _(Object)_**\n\nPass in an options object to change the default behavior of `.first()`.\n\n| Option | Default | Description |\n| --- | --- | --- |\n| `log` | `true` | Displays the command in the [Command log](/llm/markdown/app/core-concepts/open-mode.md#Command-Log) |\n| `timeout` | [`defaultCommandTimeout`](/llm/markdown/app/references/configuration.md#Timeouts) | Time to wait for `.first()` to resolve before [timing out](#Timeouts) |\n", "section": "api", "anchors": [ "arguments" ], "path": "/llm/json/chunked/api/commands/first.json", "token_estimate": 79 }, { "id": "api/commands/first#examples", "doc_id": "api/commands/first", "heading": "Examples", "heading_level": 2, "content_markdown": "## Examples\n\n### No Args\n\n#### Get the first list item in a list\n\n```\n\n```\n\n```\n// yields
  • Knick knack on my thumb
    • \ncy.get('li').first()\n```\n\n#### Get the first element across several lists\n\n`.first()` yields one element for the whole set, even when the elements sit in different parents. The `:first-child` selector yields the first child of every parent instead.\n\n```\n\n\n```\n\n```\n// yields
  • Apple
    • \ncy.get('ul li').first()\n\n// yields [
  • Apple
    • ,
  • Carrot
    • ]\ncy.get('ul li:first-child')\n```\n\n### Common workflows with `.first()`\n\n#### Scope `.within()` to the first matching element\n\n[`.within()`](/llm/markdown/api/commands/within.md) throws an error when its subject contains more than one element. Narrow the set with `.first()` before calling it.\n\n```\ncy.get('tr')\n .first()\n .within(() => {\n cy.contains('Edit').click()\n })\n```\n\n#### Click the first result after the list finishes loading\n\nAn action such as [`.click()`](/llm/markdown/api/commands/click.md) is not an assertion, so `cy.get('[data-cy=result]').first().click()` acts on the first element that exists at that moment. If the list renders placeholder rows before the real results, the element it clicks can be a placeholder. Assert on the finished list before calling `.first()`, and Cypress retries the query until the assertion passes.\n\n```\ncy.get('[data-cy=result]').should('have.length', 10).first().click()\n```\n\n#### Assert on the first element while the list re-renders\n\n`cy.get()` and `.first()` are both queries, so Cypress re-runs them together until the chained assertion passes. If the list re-renders and a new element takes the first position, the assertion checks the new element rather than the one that was first when the query started.\n\n```\ncy.get('[data-cy=todo]').first().should('have.text', 'Buy milk')\n```\n", "section": "api", "anchors": [ "examples" ], "path": "/llm/json/chunked/api/commands/first.json", "token_estimate": 380 }, { "id": "api/commands/first#no-args", "doc_id": "api/commands/first", "heading": "No Args", "heading_level": 3, "content_markdown": "### No Args\n\n#### Get the first list item in a list\n\n```\n\n```\n\n```\n// yields
  • Knick knack on my thumb
    • \ncy.get('li').first()\n```\n\n#### Get the first element across several lists\n\n`.first()` yields one element for the whole set, even when the elements sit in different parents. The `:first-child` selector yields the first child of every parent instead.\n\n```\n\n\n```\n\n```\n// yields
  • Apple
    • \ncy.get('ul li').first()\n\n// yields [
  • Apple
    • ,
  • Carrot
    • ]\ncy.get('ul li:first-child')\n```\n", "section": "api", "anchors": [ "no-args" ], "path": "/llm/json/chunked/api/commands/first.json", "token_estimate": 148 }, { "id": "api/commands/first#get-the-first-list-item-in-a-list", "doc_id": "api/commands/first", "heading": "Get the first list item in a list", "heading_level": 4, "content_markdown": "#### Get the first list item in a list\n\n```\n\n```\n\n```\n// yields
  • Knick knack on my thumb
    • \ncy.get('li').first()\n```\n", "section": "api", "anchors": [ "get-the-first-list-item-in-a-list" ], "path": "/llm/json/chunked/api/commands/first.json", "token_estimate": 64 }, { "id": "api/commands/first#get-the-first-element-across-several-lists", "doc_id": "api/commands/first", "heading": "Get the first element across several lists", "heading_level": 4, "content_markdown": "#### Get the first element across several lists\n\n`.first()` yields one element for the whole set, even when the elements sit in different parents. The `:first-child` selector yields the first child of every parent instead.\n\n```\n\n\n```\n\n```\n// yields
  • Apple
    • \ncy.get('ul li').first()\n\n// yields [
  • Apple
    • ,
  • Carrot
    • ]\ncy.get('ul li:first-child')\n```\n", "section": "api", "anchors": [ "get-the-first-element-across-several-lists" ], "path": "/llm/json/chunked/api/commands/first.json", "token_estimate": 80 }, { "id": "api/commands/first#common-workflows-with-first", "doc_id": "api/commands/first", "heading": "Common workflows with .first()", "heading_level": 3, "content_markdown": "### Common workflows with `.first()`\n\n#### Scope `.within()` to the first matching element\n\n[`.within()`](/llm/markdown/api/commands/within.md) throws an error when its subject contains more than one element. Narrow the set with `.first()` before calling it.\n\n```\ncy.get('tr')\n .first()\n .within(() => {\n cy.contains('Edit').click()\n })\n```\n\n#### Click the first result after the list finishes loading\n\nAn action such as [`.click()`](/llm/markdown/api/commands/click.md) is not an assertion, so `cy.get('[data-cy=result]').first().click()` acts on the first element that exists at that moment. If the list renders placeholder rows before the real results, the element it clicks can be a placeholder. Assert on the finished list before calling `.first()`, and Cypress retries the query until the assertion passes.\n\n```\ncy.get('[data-cy=result]').should('have.length', 10).first().click()\n```\n\n#### Assert on the first element while the list re-renders\n\n`cy.get()` and `.first()` are both queries, so Cypress re-runs them together until the chained assertion passes. If the list re-renders and a new element takes the first position, the assertion checks the new element rather than the one that was first when the query started.\n\n```\ncy.get('[data-cy=todo]').first().should('have.text', 'Buy milk')\n```\n", "section": "api", "anchors": [ "common-workflows-with-first" ], "path": "/llm/json/chunked/api/commands/first.json", "token_estimate": 229 }, { "id": "api/commands/first#scope-within-to-the-first-matching-element", "doc_id": "api/commands/first", "heading": "Scope .within() to the first matching element", "heading_level": 4, "content_markdown": "#### Scope `.within()` to the first matching element\n\n[`.within()`](/llm/markdown/api/commands/within.md) throws an error when its subject contains more than one element. Narrow the set with `.first()` before calling it.\n\n```\ncy.get('tr')\n .first()\n .within(() => {\n cy.contains('Edit').click()\n })\n```\n", "section": "api", "anchors": [ "scope-within-to-the-first-matching-element" ], "path": "/llm/json/chunked/api/commands/first.json", "token_estimate": 49 }, { "id": "api/commands/first#click-the-first-result-after-the-list-finishes-loading", "doc_id": "api/commands/first", "heading": "Click the first result after the list finishes loading", "heading_level": 4, "content_markdown": "#### Click the first result after the list finishes loading\n\nAn action such as [`.click()`](/llm/markdown/api/commands/click.md) is not an assertion, so `cy.get('[data-cy=result]').first().click()` acts on the first element that exists at that moment. If the list renders placeholder rows before the real results, the element it clicks can be a placeholder. Assert on the finished list before calling `.first()`, and Cypress retries the query until the assertion passes.\n\n```\ncy.get('[data-cy=result]').should('have.length', 10).first().click()\n```\n", "section": "api", "anchors": [ "click-the-first-result-after-the-list-finishes-loading" ], "path": "/llm/json/chunked/api/commands/first.json", "token_estimate": 93 }, { "id": "api/commands/first#assert-on-the-first-element-while-the-list-re-renders", "doc_id": "api/commands/first", "heading": "Assert on the first element while the list re-renders", "heading_level": 4, "content_markdown": "#### Assert on the first element while the list re-renders\n\n`cy.get()` and `.first()` are both queries, so Cypress re-runs them together until the chained assertion passes. If the list re-renders and a new element takes the first position, the assertion checks the new element rather than the one that was first when the query started.\n\n```\ncy.get('[data-cy=todo]').first().should('have.text', 'Buy milk')\n```\n", "section": "api", "anchors": [ "assert-on-the-first-element-while-the-list-re-renders" ], "path": "/llm/json/chunked/api/commands/first.json", "token_estimate": 80 }, { "id": "api/commands/first#notes", "doc_id": "api/commands/first", "heading": "Notes", "heading_level": 2, "content_markdown": "## Notes\n\n### How `.first()` compares to `.eq(0)`\n\n`.first()` yields the same element as [`.eq(0)`](/llm/markdown/api/commands/eq.md). Use `.eq()` to get an element at any other index, including negative indexes counted back from the end of the set.\n\n### Selecting the first element that matches a selector\n\n`.first()` takes no selector. `cy.get('li').first('.active')` yields the first `
  • ` whether or not it has the class `active`. The Command Log still shows `.active` as the command's message, which can make it look as though the selector was applied. TypeScript flags the call as an error. To get the first element that matches a selector, narrow the set with [`.filter()`](/llm/markdown/api/commands/filter.md) before calling `.first()`.\n\n```\ncy.get('li').filter('.active').first()\n```\n", "section": "api", "anchors": [ "notes" ], "path": "/llm/json/chunked/api/commands/first.json", "token_estimate": 147 }, { "id": "api/commands/first#how-first-compares-to-eq-0", "doc_id": "api/commands/first", "heading": "How .first() compares to .eq(0)", "heading_level": 3, "content_markdown": "### How `.first()` compares to `.eq(0)`\n\n`.first()` yields the same element as [`.eq(0)`](/llm/markdown/api/commands/eq.md). Use `.eq()` to get an element at any other index, including negative indexes counted back from the end of the set.\n", "section": "api", "anchors": [ "how-first-compares-to-eq-0" ], "path": "/llm/json/chunked/api/commands/first.json", "token_estimate": 45 }, { "id": "api/commands/first#selecting-the-first-element-that-matches-a-selector", "doc_id": "api/commands/first", "heading": "Selecting the first element that matches a selector", "heading_level": 3, "content_markdown": "### Selecting the first element that matches a selector\n\n`.first()` takes no selector. `cy.get('li').first('.active')` yields the first `
  • ` whether or not it has the class `active`. The Command Log still shows `.active` as the command's message, which can make it look as though the selector was applied. TypeScript flags the call as an error. To get the first element that matches a selector, narrow the set with [`.filter()`](/llm/markdown/api/commands/filter.md) before calling `.first()`.\n\n```\ncy.get('li').filter('.active').first()\n```\n", "section": "api", "anchors": [ "selecting-the-first-element-that-matches-a-selector" ], "path": "/llm/json/chunked/api/commands/first.json", "token_estimate": 99 }, { "id": "api/commands/first#rules", "doc_id": "api/commands/first", "heading": "Rules", "heading_level": 2, "content_markdown": "## Rules\n\n### Requirements\n\n* `.first()` requires being chained off a command that yields DOM element(s) or a document.\n\n### Assertions\n\n* `.first()` will automatically [retry](/llm/markdown/app/core-concepts/retry-ability.md) until the element(s) [exist in the DOM](/llm/markdown/app/core-concepts/introduction-to-cypress.md#Implicit-Assertions).\n* `.first()` will automatically [retry](/llm/markdown/app/core-concepts/retry-ability.md) until all chained assertions have passed.\n\n### Timeouts\n\n* `.first()` can time out waiting for the element(s) to [exist in the DOM](/llm/markdown/app/core-concepts/introduction-to-cypress.md#Implicit-Assertions).\n* `.first()` can time out waiting for assertions you've added to pass.\n", "section": "api", "anchors": [ "rules" ], "path": "/llm/json/chunked/api/commands/first.json", "token_estimate": 96 }, { "id": "api/commands/first#command-log", "doc_id": "api/commands/first", "heading": "Command Log", "heading_level": 2, "content_markdown": "## Command Log\n\n**_Find the first input in the form_**\n\n```\ncy.get('form').find('input').first()\n```\n\nThe commands above display in the Command Log as:\n\nClick the `first` command in the Command Log to print the following to the console:\n", "section": "api", "anchors": [ "command-log" ], "path": "/llm/json/chunked/api/commands/first.json", "token_estimate": 49 }, { "id": "api/commands/first#history", "doc_id": "api/commands/first", "heading": "History", "heading_level": 2, "content_markdown": "## History\n\n| Version | Changes |\n| --- | --- |\n| [12.6.0](/llm/markdown/app/references/changelog.md#12-6-0) | Overwrite `.first()` with [`Cypress.Commands.overwriteQuery()`](/llm/markdown/api/cypress-api/custom-queries.md#Overwriting-Existing-Queries) rather than `Cypress.Commands.overwrite()`. |\n| [12.0.0](/llm/markdown/app/references/changelog.md#12-0-0) | `.first()` is now a query. |\n", "section": "api", "anchors": [ "history" ], "path": "/llm/json/chunked/api/commands/first.json", "token_estimate": 43 } ] }