{
  "doc": {
    "id": "api/commands/closest",
    "title": "cy.closest()",
    "description": "Get the first DOM element that matches the selector in Cypress (whether it be itself or one of its ancestors).",
    "section": "api",
    "source_path": "/llm/markdown/api/commands/closest.md",
    "version": "f60251bf707b0077a9535579c9f90d615440cc35",
    "updated_at": "2026-10-16T10:56:58.670Z",
    "headings": [
      {
        "id": "api/commands/closest#closest",
        "text": "closest",
        "level": 1
      },
      {
        "id": "api/commands/closest#syntax",
        "text": "Syntax",
        "level": 2
      },
      {
        "id": "api/commands/closest#usage",
        "text": "Usage",
        "level": 3
      },
      {
        "id": "api/commands/closest#arguments",
        "text": "Arguments",
        "level": 3
      },
      {
        "id": "api/commands/closest#yields",
        "text": "Yields",
        "level": 3
      },
      {
        "id": "api/commands/closest#examples",
        "text": "Examples",
        "level": 2
      },
      {
        "id": "api/commands/closest#selector",
        "text": "Selector",
        "level": 3
      },
      {
        "id": "api/commands/closest#find-the-closest-ancestor-of-p-error-with-class-banner",
        "text": "Find the closest ancestor of p.error with class banner",
        "level": 4
      },
      {
        "id": "api/commands/closest#yield-the-subject-itself-when-it-matches",
        "text": "Yield the subject itself when it matches",
        "level": 4
      },
      {
        "id": "api/commands/closest#act-on-one-card-in-a-repeated-list",
        "text": "Act on one card in a repeated list",
        "level": 4
      },
      {
        "id": "api/commands/closest#assert-on-a-form-fields-wrapper",
        "text": "Assert on a form field's wrapper",
        "level": 4
      },
      {
        "id": "api/commands/closest#compare-closest-with-parents",
        "text": "Compare .closest() with .parents()",
        "level": 4
      },
      {
        "id": "api/commands/closest#assert-that-an-element-is-not-inside-a-container",
        "text": "Assert that an element is not inside a container",
        "level": 4
      },
      {
        "id": "api/commands/closest#notes",
        "text": "Notes",
        "level": 2
      },
      {
        "id": "api/commands/closest#shadow-dom-boundaries-and-closest",
        "text": "Shadow DOM boundaries and .closest()",
        "level": 3
      },
      {
        "id": "api/commands/closest#rules",
        "text": "Rules",
        "level": 2
      },
      {
        "id": "api/commands/closest#requirements",
        "text": "Requirements",
        "level": 3
      },
      {
        "id": "api/commands/closest#assertions",
        "text": "Assertions",
        "level": 3
      },
      {
        "id": "api/commands/closest#timeouts",
        "text": "Timeouts",
        "level": 3
      },
      {
        "id": "api/commands/closest#command-log",
        "text": "Command Log",
        "level": 2
      },
      {
        "id": "api/commands/closest#history",
        "text": "History",
        "level": 2
      },
      {
        "id": "api/commands/closest#see-also",
        "text": "See also",
        "level": 2
      }
    ]
  },
  "chunks": [
    {
      "id": "api/commands/closest#syntax",
      "doc_id": "api/commands/closest",
      "heading": "Syntax",
      "heading_level": 2,
      "content_markdown": "## Syntax\n\n```\n.closest(selector)\n.closest(selector, options)\n```\n\n### Usage\n\n**Correct Usage**\n\n```\ncy.get('td').closest('.filled') // Yield closest el with class 'filled'\n```\n\n**Incorrect Usage**\n\n```\ncy.closest('.active') // Errors, cannot be chained off 'cy'\ncy.clock().closest() // Errors, 'clock' does not yield DOM elements\n```\n\n### Arguments\n\n**selector _(String selector)_**\n\nA selector the element itself or one of its ancestors must match.\n\n**options _(Object)_**\n\nPass in an options object to change the default behavior of `.closest()`.\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 `.closest()` to resolve before [timing out](#Timeouts) |\n\n### Yields\n\n*   `.closest()` yields the new DOM element(s) it found. When the subject holds more than one element, it yields the closest match for each one, with duplicates removed.\n*   `.closest()` is a query, and it is _safe_ to chain further commands.\n",
      "section": "api",
      "anchors": [
        "syntax"
      ],
      "path": "/llm/json/chunked/api/commands/closest.json",
      "token_estimate": 212
    },
    {
      "id": "api/commands/closest#usage",
      "doc_id": "api/commands/closest",
      "heading": "Usage",
      "heading_level": 3,
      "content_markdown": "### Usage\n\n**Correct Usage**\n\n```\ncy.get('td').closest('.filled') // Yield closest el with class 'filled'\n```\n\n**Incorrect Usage**\n\n```\ncy.closest('.active') // Errors, cannot be chained off 'cy'\ncy.clock().closest() // Errors, 'clock' does not yield DOM elements\n```\n",
      "section": "api",
      "anchors": [
        "usage"
      ],
      "path": "/llm/json/chunked/api/commands/closest.json",
      "token_estimate": 47
    },
    {
      "id": "api/commands/closest#arguments",
      "doc_id": "api/commands/closest",
      "heading": "Arguments",
      "heading_level": 3,
      "content_markdown": "### Arguments\n\n**selector _(String selector)_**\n\nA selector the element itself or one of its ancestors must match.\n\n**options _(Object)_**\n\nPass in an options object to change the default behavior of `.closest()`.\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 `.closest()` to resolve before [timing out](#Timeouts) |\n",
      "section": "api",
      "anchors": [
        "arguments"
      ],
      "path": "/llm/json/chunked/api/commands/closest.json",
      "token_estimate": 99
    },
    {
      "id": "api/commands/closest#yields",
      "doc_id": "api/commands/closest",
      "heading": "Yields",
      "heading_level": 3,
      "content_markdown": "### Yields\n\n*   `.closest()` yields the new DOM element(s) it found. When the subject holds more than one element, it yields the closest match for each one, with duplicates removed.\n*   `.closest()` is a query, and it is _safe_ to chain further commands.\n",
      "section": "api",
      "anchors": [
        "yields"
      ],
      "path": "/llm/json/chunked/api/commands/closest.json",
      "token_estimate": 57
    },
    {
      "id": "api/commands/closest#examples",
      "doc_id": "api/commands/closest",
      "heading": "Examples",
      "heading_level": 2,
      "content_markdown": "## Examples\n\n### Selector\n\n#### Find the closest ancestor of `p.error` with class `banner`\n\n```\n<div class=\"banner\">\n  <div class=\"content\">\n    <p class=\"error\">Payment failed</p>\n  </div>\n</div>\n```\n\n```\n// yields <div class=\"banner\">…</div>\ncy.get('p.error').closest('.banner')\n```\n\n#### Yield the subject itself when it matches\n\n```\n<ul class=\"nav\">\n  <li class=\"active\">Home</li>\n</ul>\n```\n\n```\n// yields <li class=\"active\">Home</li>, since the subject\n// matches the selector before any ancestor is tested\ncy.get('li.active').closest('li')\n```\n\n#### Act on one card in a repeated list\n\nFind something unique inside a repeated component, climb to the component with `.closest()`, then query inside it.\n\n```\n<div data-cy=\"product-card\">\n  <h3>Trail Runner</h3>\n  <button>Add to cart</button>\n</div>\n<div data-cy=\"product-card\">\n  <h3>Road Racer</h3>\n  <button>Add to cart</button>\n</div>\n```\n\n```\n// clicks the \"Add to cart\" button in the Road Racer card only\ncy.contains('h3', 'Road Racer')\n  .closest('[data-cy=\"product-card\"]')\n  .find('button')\n  .click()\n```\n\n#### Assert on a form field's wrapper\n\nValidation state often lives on a wrapper element rather than on the input.\n\n```\n<div class=\"form-group has-error\">\n  <label for=\"email\">Email</label>\n  <input id=\"email\" type=\"email\" />\n</div>\n```\n\n```\ncy.get('#email').closest('.form-group').should('have.class', 'has-error')\n```\n\n#### Compare `.closest()` with `.parents()`\n\n`.closest()` stops at the first match. [`.parents()`](/llm/markdown/api/commands/parents.md) collects every matching ancestor.\n\n```\n<section class=\"panel outer\">\n  <section class=\"panel inner\">\n    <button>Save</button>\n  </section>\n</section>\n```\n\n```\n// yields <section class=\"panel inner\">\ncy.get('button').closest('.panel')\n\n// yields <section class=\"panel inner\"> and <section class=\"panel outer\">\ncy.get('button').parents('.panel')\n```\n\n#### Assert that an element is not inside a container\n\nWhen no ancestor matches, `.closest()` yields an empty result, so `.should('not.exist')` passes.\n\n```\n// passes when the checkout button is not inside a modal\ncy.get('[data-cy=\"checkout\"]').closest('.modal').should('not.exist')\n```\n",
      "section": "api",
      "anchors": [
        "examples"
      ],
      "path": "/llm/json/chunked/api/commands/closest.json",
      "token_estimate": 331
    },
    {
      "id": "api/commands/closest#selector",
      "doc_id": "api/commands/closest",
      "heading": "Selector",
      "heading_level": 3,
      "content_markdown": "### Selector\n\n#### Find the closest ancestor of `p.error` with class `banner`\n\n```\n<div class=\"banner\">\n  <div class=\"content\">\n    <p class=\"error\">Payment failed</p>\n  </div>\n</div>\n```\n\n```\n// yields <div class=\"banner\">…</div>\ncy.get('p.error').closest('.banner')\n```\n\n#### Yield the subject itself when it matches\n\n```\n<ul class=\"nav\">\n  <li class=\"active\">Home</li>\n</ul>\n```\n\n```\n// yields <li class=\"active\">Home</li>, since the subject\n// matches the selector before any ancestor is tested\ncy.get('li.active').closest('li')\n```\n\n#### Act on one card in a repeated list\n\nFind something unique inside a repeated component, climb to the component with `.closest()`, then query inside it.\n\n```\n<div data-cy=\"product-card\">\n  <h3>Trail Runner</h3>\n  <button>Add to cart</button>\n</div>\n<div data-cy=\"product-card\">\n  <h3>Road Racer</h3>\n  <button>Add to cart</button>\n</div>\n```\n\n```\n// clicks the \"Add to cart\" button in the Road Racer card only\ncy.contains('h3', 'Road Racer')\n  .closest('[data-cy=\"product-card\"]')\n  .find('button')\n  .click()\n```\n\n#### Assert on a form field's wrapper\n\nValidation state often lives on a wrapper element rather than on the input.\n\n```\n<div class=\"form-group has-error\">\n  <label for=\"email\">Email</label>\n  <input id=\"email\" type=\"email\" />\n</div>\n```\n\n```\ncy.get('#email').closest('.form-group').should('have.class', 'has-error')\n```\n\n#### Compare `.closest()` with `.parents()`\n\n`.closest()` stops at the first match. [`.parents()`](/llm/markdown/api/commands/parents.md) collects every matching ancestor.\n\n```\n<section class=\"panel outer\">\n  <section class=\"panel inner\">\n    <button>Save</button>\n  </section>\n</section>\n```\n\n```\n// yields <section class=\"panel inner\">\ncy.get('button').closest('.panel')\n\n// yields <section class=\"panel inner\"> and <section class=\"panel outer\">\ncy.get('button').parents('.panel')\n```\n\n#### Assert that an element is not inside a container\n\nWhen no ancestor matches, `.closest()` yields an empty result, so `.should('not.exist')` passes.\n\n```\n// passes when the checkout button is not inside a modal\ncy.get('[data-cy=\"checkout\"]').closest('.modal').should('not.exist')\n```\n",
      "section": "api",
      "anchors": [
        "selector"
      ],
      "path": "/llm/json/chunked/api/commands/closest.json",
      "token_estimate": 328
    },
    {
      "id": "api/commands/closest#yield-the-subject-itself-when-it-matches",
      "doc_id": "api/commands/closest",
      "heading": "Yield the subject itself when it matches",
      "heading_level": 4,
      "content_markdown": "#### Yield the subject itself when it matches\n\n```\n<ul class=\"nav\">\n  <li class=\"active\">Home</li>\n</ul>\n```\n\n```\n// yields <li class=\"active\">Home</li>, since the subject\n// matches the selector before any ancestor is tested\ncy.get('li.active').closest('li')\n```\n",
      "section": "api",
      "anchors": [
        "yield-the-subject-itself-when-it-matches"
      ],
      "path": "/llm/json/chunked/api/commands/closest.json",
      "token_estimate": 45
    },
    {
      "id": "api/commands/closest#act-on-one-card-in-a-repeated-list",
      "doc_id": "api/commands/closest",
      "heading": "Act on one card in a repeated list",
      "heading_level": 4,
      "content_markdown": "#### Act on one card in a repeated list\n\nFind something unique inside a repeated component, climb to the component with `.closest()`, then query inside it.\n\n```\n<div data-cy=\"product-card\">\n  <h3>Trail Runner</h3>\n  <button>Add to cart</button>\n</div>\n<div data-cy=\"product-card\">\n  <h3>Road Racer</h3>\n  <button>Add to cart</button>\n</div>\n```\n\n```\n// clicks the \"Add to cart\" button in the Road Racer card only\ncy.contains('h3', 'Road Racer')\n  .closest('[data-cy=\"product-card\"]')\n  .find('button')\n  .click()\n```\n",
      "section": "api",
      "anchors": [
        "act-on-one-card-in-a-repeated-list"
      ],
      "path": "/llm/json/chunked/api/commands/closest.json",
      "token_estimate": 87
    },
    {
      "id": "api/commands/closest#assert-on-a-form-fields-wrapper",
      "doc_id": "api/commands/closest",
      "heading": "Assert on a form field's wrapper",
      "heading_level": 4,
      "content_markdown": "#### Assert on a form field's wrapper\n\nValidation state often lives on a wrapper element rather than on the input.\n\n```\n<div class=\"form-group has-error\">\n  <label for=\"email\">Email</label>\n  <input id=\"email\" type=\"email\" />\n</div>\n```\n\n```\ncy.get('#email').closest('.form-group').should('have.class', 'has-error')\n```\n",
      "section": "api",
      "anchors": [
        "assert-on-a-form-fields-wrapper"
      ],
      "path": "/llm/json/chunked/api/commands/closest.json",
      "token_estimate": 48
    },
    {
      "id": "api/commands/closest#compare-closest-with-parents",
      "doc_id": "api/commands/closest",
      "heading": "Compare .closest() with .parents()",
      "heading_level": 4,
      "content_markdown": "#### Compare `.closest()` with `.parents()`\n\n`.closest()` stops at the first match. [`.parents()`](/llm/markdown/api/commands/parents.md) collects every matching ancestor.\n\n```\n<section class=\"panel outer\">\n  <section class=\"panel inner\">\n    <button>Save</button>\n  </section>\n</section>\n```\n\n```\n// yields <section class=\"panel inner\">\ncy.get('button').closest('.panel')\n\n// yields <section class=\"panel inner\"> and <section class=\"panel outer\">\ncy.get('button').parents('.panel')\n```\n",
      "section": "api",
      "anchors": [
        "compare-closest-with-parents"
      ],
      "path": "/llm/json/chunked/api/commands/closest.json",
      "token_estimate": 60
    },
    {
      "id": "api/commands/closest#assert-that-an-element-is-not-inside-a-container",
      "doc_id": "api/commands/closest",
      "heading": "Assert that an element is not inside a container",
      "heading_level": 4,
      "content_markdown": "#### Assert that an element is not inside a container\n\nWhen no ancestor matches, `.closest()` yields an empty result, so `.should('not.exist')` passes.\n\n```\n// passes when the checkout button is not inside a modal\ncy.get('[data-cy=\"checkout\"]').closest('.modal').should('not.exist')\n```\n",
      "section": "api",
      "anchors": [
        "assert-that-an-element-is-not-inside-a-container"
      ],
      "path": "/llm/json/chunked/api/commands/closest.json",
      "token_estimate": 48
    },
    {
      "id": "api/commands/closest#notes",
      "doc_id": "api/commands/closest",
      "heading": "Notes",
      "heading_level": 2,
      "content_markdown": "## Notes\n\n### Shadow DOM boundaries and `.closest()`\n\nWhen the subject is inside a shadow root, `.closest()` crosses the shadow boundary. If nothing inside the shadow root matches, it continues from the shadow host, testing the host itself and then the host's ancestors, until it finds a match or reaches the document. This happens whether or not [`includeShadowDom`](/llm/markdown/app/references/configuration.md#Global) is enabled. The option controls whether queries like [`.find()`](/llm/markdown/api/commands/find.md) reach into a shadow root, not whether `.closest()` climbs back out of one.\n\n```\n<form id=\"checkout\">\n  <payment-panel>\n    <template shadowrootmode=\"open\">\n      <button>Pay now</button>\n    </template>\n  </payment-panel>\n</form>\n```\n\n```\n// .find() needs includeShadowDom to reach the button;\n// .closest() crosses back out of the shadow root on its own\n// yields <form id=\"checkout\">\ncy.get('payment-panel')\n  .find('button', { includeShadowDom: true })\n  .closest('form')\n```\n",
      "section": "api",
      "anchors": [
        "notes"
      ],
      "path": "/llm/json/chunked/api/commands/closest.json",
      "token_estimate": 167
    },
    {
      "id": "api/commands/closest#shadow-dom-boundaries-and-closest",
      "doc_id": "api/commands/closest",
      "heading": "Shadow DOM boundaries and .closest()",
      "heading_level": 3,
      "content_markdown": "### Shadow DOM boundaries and `.closest()`\n\nWhen the subject is inside a shadow root, `.closest()` crosses the shadow boundary. If nothing inside the shadow root matches, it continues from the shadow host, testing the host itself and then the host's ancestors, until it finds a match or reaches the document. This happens whether or not [`includeShadowDom`](/llm/markdown/app/references/configuration.md#Global) is enabled. The option controls whether queries like [`.find()`](/llm/markdown/api/commands/find.md) reach into a shadow root, not whether `.closest()` climbs back out of one.\n\n```\n<form id=\"checkout\">\n  <payment-panel>\n    <template shadowrootmode=\"open\">\n      <button>Pay now</button>\n    </template>\n  </payment-panel>\n</form>\n```\n\n```\n// .find() needs includeShadowDom to reach the button;\n// .closest() crosses back out of the shadow root on its own\n// yields <form id=\"checkout\">\ncy.get('payment-panel')\n  .find('button', { includeShadowDom: true })\n  .closest('form')\n```\n",
      "section": "api",
      "anchors": [
        "shadow-dom-boundaries-and-closest"
      ],
      "path": "/llm/json/chunked/api/commands/closest.json",
      "token_estimate": 164
    },
    {
      "id": "api/commands/closest#rules",
      "doc_id": "api/commands/closest",
      "heading": "Rules",
      "heading_level": 2,
      "content_markdown": "## Rules\n\n### Requirements\n\n*   `.closest()` requires being chained off a command that yields DOM element(s) or a document.\n\n### Assertions\n\n*   `.closest()` 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*   `.closest()` will automatically [retry](/llm/markdown/app/core-concepts/retry-ability.md) until all chained assertions have passed.\n\n### Timeouts\n\n*   `.closest()` 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*   `.closest()` can time out waiting for assertions you've added to pass.\n",
      "section": "api",
      "anchors": [
        "rules"
      ],
      "path": "/llm/json/chunked/api/commands/closest.json",
      "token_estimate": 96
    },
    {
      "id": "api/commands/closest#command-log",
      "doc_id": "api/commands/closest",
      "heading": "Command Log",
      "heading_level": 2,
      "content_markdown": "## Command Log\n\n**_Find the closest element of `li.active` with the class 'nav'_**\n\n```\ncy.get('li.active').closest('.nav')\n```\n\nThe commands above will display in the Command Log as:\n\nWhen clicking on the `closest` command within the command log, the console outputs the following:\n",
      "section": "api",
      "anchors": [
        "command-log"
      ],
      "path": "/llm/json/chunked/api/commands/closest.json",
      "token_estimate": 55
    },
    {
      "id": "api/commands/closest#history",
      "doc_id": "api/commands/closest",
      "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 `.closest()` 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) | `.closest()` is now a query. |\n",
      "section": "api",
      "anchors": [
        "history"
      ],
      "path": "/llm/json/chunked/api/commands/closest.json",
      "token_estimate": 43
    }
  ]
}