{
  "doc": {
    "id": "api/commands/focus",
    "title": "cy.focus()",
    "description": "Focus on a DOM element in Cypress.",
    "section": "api",
    "source_path": "/llm/markdown/api/commands/focus.md",
    "version": "29f95bf8bb06f320986f3749f5bf09a35a409eab",
    "updated_at": "2026-09-04T10:49:54.630Z",
    "headings": [
      {
        "id": "api/commands/focus#focus",
        "text": "focus",
        "level": 1
      },
      {
        "id": "api/commands/focus#syntax",
        "text": "Syntax",
        "level": 2
      },
      {
        "id": "api/commands/focus#usage",
        "text": "Usage",
        "level": 3
      },
      {
        "id": "api/commands/focus#arguments",
        "text": "Arguments",
        "level": 3
      },
      {
        "id": "api/commands/focus#yields",
        "text": "Yields",
        "level": 3
      },
      {
        "id": "api/commands/focus#examples",
        "text": "Examples",
        "level": 2
      },
      {
        "id": "api/commands/focus#no-args",
        "text": "No Args",
        "level": 3
      },
      {
        "id": "api/commands/focus#focus-on-an-input",
        "text": "Focus on an input",
        "level": 4
      },
      {
        "id": "api/commands/focus#focus-type-and-blur-a-textarea",
        "text": "Focus, type, and blur a textarea",
        "level": 4
      },
      {
        "id": "api/commands/focus#notes",
        "text": "Notes",
        "level": 2
      },
      {
        "id": "api/commands/focus#actionability",
        "text": "Actionability",
        "level": 3
      },
      {
        "id": "api/commands/focus#focus-is-not-an-action-command",
        "text": "Focus is not an action command",
        "level": 4
      },
      {
        "id": "api/commands/focus#blur-events",
        "text": "Blur Events",
        "level": 3
      },
      {
        "id": "api/commands/focus#cypress-blurs-other-focused-elements-first",
        "text": "Cypress blurs other focused elements first",
        "level": 4
      },
      {
        "id": "api/commands/focus#focusable",
        "text": "Focusable",
        "level": 3
      },
      {
        "id": "api/commands/focus#can-only-be-called-on-a-valid-focusable-element",
        "text": "Can only be called on a valid focusable element",
        "level": 4
      },
      {
        "id": "api/commands/focus#timeouts",
        "text": "Timeouts",
        "level": 3
      },
      {
        "id": "api/commands/focus#can-time-out-because-your-browser-did-not-receive-any-focus-events",
        "text": "Can time out because your browser did not receive any focus events",
        "level": 4
      },
      {
        "id": "api/commands/focus#rules",
        "text": "Rules",
        "level": 2
      },
      {
        "id": "api/commands/focus#requirements",
        "text": "Requirements",
        "level": 3
      },
      {
        "id": "api/commands/focus#assertions",
        "text": "Assertions",
        "level": 3
      },
      {
        "id": "api/commands/focus#timeouts",
        "text": "Timeouts",
        "level": 3
      },
      {
        "id": "api/commands/focus#command-log",
        "text": "Command Log",
        "level": 2
      },
      {
        "id": "api/commands/focus#see-also",
        "text": "See also",
        "level": 2
      }
    ]
  },
  "content": {
    "type": "root",
    "children": [
      {
        "type": "heading",
        "depth": 1,
        "children": [
          {
            "type": "text",
            "value": "focus"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Focus on a DOM element."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "It is "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/app/core-concepts/retry-ability.md#Only-queries-are-retried",
            "children": [
              {
                "type": "text",
                "value": "unsafe"
              }
            ]
          },
          {
            "type": "text",
            "value": " to chain further commands that rely on the subject after `.focus()`."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Syntax"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": ".focus()\n.focus(options)"
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Usage"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Correct Usage"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cy.get('input').first().focus() // Focus on the first input"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Incorrect Usage"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cy.focus('#search') // Errors, cannot be chained off 'cy'\ncy.window().focus() // Errors, 'window' does not yield DOM element"
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Arguments"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "options (Object)"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Pass in an options object to change the default behavior of `.focus()`."
          }
        ]
      },
      {
        "type": "table",
        "align": [
          null,
          null,
          null
        ],
        "children": [
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Option"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Default"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Description"
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`log`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`true`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Displays the command in the "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/core-concepts/open-mode.md#Command-Log",
                    "children": [
                      {
                        "type": "text",
                        "value": "Command log"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`timeout`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/references/configuration.md#Timeouts",
                    "children": [
                      {
                        "type": "text",
                        "value": "`defaultCommandTimeout`"
                      }
                    ]
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Time to wait for `.focus()` to resolve before "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "#Timeouts",
                    "children": [
                      {
                        "type": "text",
                        "value": "timing out"
                      }
                    ]
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Yields"
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "`.focus()` yields the same subject it was given."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "It is "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/core-concepts/retry-ability.md#Only-queries-are-retried",
                    "children": [
                      {
                        "type": "text",
                        "value": "unsafe"
                      }
                    ]
                  },
                  {
                    "type": "text",
                    "value": " to chain further commands that rely on the subject after `.focus()`."
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Examples"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "No Args"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Focus on an input"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cy.get('[type=\"input\"]').focus()"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Focus, type, and blur a textarea"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cy.get('textarea').focus()\ncy.get('textarea').type('Nice Product!')\ncy.get('textarea').blur()"
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Notes"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Actionability"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Focus is not an action command"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "`.focus()` is not implemented like other action commands, and does not follow the same rules of "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/app/core-concepts/interacting-with-elements.md",
            "children": [
              {
                "type": "text",
                "value": "waiting for actionability"
              }
            ]
          },
          {
            "type": "text",
            "value": "."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "`.focus()` is a helpful command used as a shortcut. Normally there's no way for a user to \"focus\" an element without causing another action or side effect. Typically the user would have to click or tab to this element."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Oftentimes using `.focus()` directly is more concise and conveys what you're trying to test."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "If you want the other guarantees of waiting for an element to become actionable, you should use a different command like "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/api/commands/click.md",
            "children": [
              {
                "type": "text",
                "value": "`.click()`"
              }
            ]
          },
          {
            "type": "text",
            "value": "."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Blur Events"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Cypress blurs other focused elements first"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "If there is currently a different DOM element with focus, Cypress issues a `blur` event to that element before running the `.focus()` command."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Focusable"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Can only be called on a valid focusable element"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Ensure the element you are trying to call `.focus()` on is a "
          },
          {
            "type": "link",
            "title": null,
            "url": "https://www.w3.org/TR/html5/editing.html#focusable",
            "children": [
              {
                "type": "text",
                "value": "focusable element"
              }
            ]
          },
          {
            "type": "text",
            "value": "."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Timeouts"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Can time out because your browser did not receive any focus events"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "If you see this error, you may want to ensure that the main browser window is currently focused. This means not being focused in debugger or any other window when the command is run."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Internally Cypress does account for this, and will polyfill the blur events when necessary to replicate what the browser does. Unfortunately the browser will still behave differently when not in focus - for instance it may throttle async events. Your best bet here is to keep Cypress focused when working on a test."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Rules"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Requirements"
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "`.focus()` requires being chained off a command that yields DOM element(s)."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "`.focus()` requires the element to be able to receive focus."
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Assertions"
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "`.focus()` will automatically wait for assertions you have chained to pass."
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Timeouts"
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "`.focus()` can time out waiting for assertions you've added to pass."
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Command Log"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Focus the textarea"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cy.get('[name=\"comment\"]').focus()"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "The commands above will display in the Command Log as:"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "When clicking on the `focus` command within the command log, the console outputs the following:"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "See also"
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/api/commands/blur.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "`.blur()`"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/api/commands/click.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "`.click()`"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/api/commands/focused.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "`cy.focused()`"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/api/commands/press.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "`cy.press()`"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/api/commands/type.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "`.type()`"
                      }
                    ]
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  },
  "token_estimate": 720
}