--- id: api/commands/contains title: cy.contains() description: Get the DOM element containing the text in Cypress. section: api source_path: docs/api/commands/contains.mdx version: e092ccffd0e66fc446aea20f1c7cab20a2534c4c updated_at: '2026-08-20T01:04:15.237Z' --- # contains Get the DOM element containing the text. DOM elements can contain _more_ than the desired text and still match. Additionally, Cypress [prefers some DOM elements](#Notes) over the deepest element found. ## Syntax ``` .contains(content) .contains(content, options) .contains(selector, content) .contains(selector, content, options) // ---or--- cy.contains(content) cy.contains(content, options) cy.contains(selector, content) cy.contains(selector, content, options) ``` ### Usage **Correct Usage** ``` cy.contains('.nav a', 'About') // Yield anchor in .nav containing 'About' cy.contains('Hello') // Yield first el in document containing 'Hello' ``` **Incorrect Usage** ``` cy.title().contains('My App') // Errors, 'title' does not yield DOM element cy.getCookies().contains('_key') // Errors, 'getCookies' does not yield DOM element ``` ### Arguments **content _(String, Number, RegExp)_** Get the DOM element containing the content. **selector _(String selector)_** Specify a selector to filter DOM elements containing the text. Cypress will _ignore_ its [default preference order](#Notes) for the specified selector. Using a selector allows you to return more _shallow_ elements (higher in the tree) that contain the specific text. **options _(Object)_** Pass in an options object to change the default behavior of `.contains()`. | Option | Default | Description | | --- | --- | --- | | `matchCase` | `true` | Check case sensitivity | | `log` | `true` | Displays the command in the [Command log](/llm/markdown/app/core-concepts/open-mode.md#Command-Log) | | `timeout` | [`defaultCommandTimeout`](/llm/markdown/app/references/configuration.md#Timeouts) | Time to wait for `.contains()` to resolve before [timing out](#Timeouts) | | `includeShadowDom` | [`includeShadowDom` config option value](/llm/markdown/app/references/configuration.md#Global) | Whether to traverse shadow DOM boundaries and include elements within the shadow DOM in the yielded results. | ### Yields * `.contains()` yields the new DOM element it found. * `.contains()` is a query, and it is _safe_ to chain further commands. ## Examples ### Content #### Find the first element containing some text ``` ``` ``` // yields
  • apples
    • cy.contains('apples') ``` #### Find the `input[type='submit']` by value Get the form element and search in its descendants for the content "submit the form!" ```
    ``` ``` // yields input[type='submit'] element then clicks it cy.get('form').contains('submit the form!').click() ``` ### Number #### Find the first element containing a number Even though the `` is the deepest element that contains a "4", Cypress automatically yields ` ``` ``` // yields ``` ``` cy.get('form') // yields
    ...
    .contains('form', 'Proceed') // yields
    ...
    .submit() // yields
    ...
    ``` Without the explicit selector the subject would change to be the ` ``` ``` // yields