{
  "doc": {
    "id": "api/commands/focus",
    "title": "focus | Cypress Documentation",
    "description": "Focus on a DOM element in Cypress.",
    "section": "api",
    "source_path": "/llm/markdown/api/commands/focus.md",
    "version": "ce02913654e2655ee63448bdc92bb92c7b46a619",
    "updated_at": "2026-04-22T19:37:51.587Z",
    "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-learn-about-subject-management",
        "text": "Yields Learn about subject management",
        "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-learn-about-chaining-commands",
        "text": "Requirements Learn about chaining commands",
        "level": 3
      },
      {
        "id": "api/commands/focus#assertions-learn-about-assertions",
        "text": "Assertions Learn about assertions",
        "level": 3
      },
      {
        "id": "api/commands/focus#timeouts-learn-about-timeouts",
        "text": "Timeouts Learn about 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\nchain further commands that rely on the subject after `.focus()`."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Syntax"
          }
        ]
      },
      {
        "type": "code",
        "lang": "javascript",
        "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": "javascript",
        "meta": null,
        "value": "cy.get('input').first().focus() // Focus on the first input"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Incorrect Usage"
          }
        ]
      },
      {
        "type": "code",
        "lang": "javascript",
        "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": "link",
            "title": null,
            "url": "/llm/markdown/app/core-concepts/introduction-to-cypress.md#Subject-Management",
            "children": [
              {
                "type": "text",
                "value": "Learn about subject management"
              }
            ]
          }
        ]
      },
      {
        "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": "\nto 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": "javascript",
        "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": "javascript",
        "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\nthe same rules of\n"
          },
          {
            "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\na user to \"focus\" an element without causing another action or side effect.\nTypically 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\ntrying to test."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "If you want the other guarantees of waiting for an element to become actionable,\nyou 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\n`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\n"
          },
          {
            "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\ncurrently focused. This means not being focused in debugger or any other window\nwhen the command is run."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Internally Cypress does account for this, and will polyfill the blur events when\nnecessary to replicate what the browser does. Unfortunately the browser will\nstill behave differently when not in focus - for instance it may throttle async\nevents. 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": "link",
            "title": null,
            "url": "/llm/markdown/app/core-concepts/introduction-to-cypress.md#Chains-of-Commands",
            "children": [
              {
                "type": "text",
                "value": "Learn about chaining commands"
              }
            ]
          }
        ]
      },
      {
        "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": "link",
            "title": null,
            "url": "/llm/markdown/app/core-concepts/introduction-to-cypress.md#Assertions",
            "children": [
              {
                "type": "text",
                "value": "Learn about 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": "link",
            "title": null,
            "url": "/llm/markdown/app/core-concepts/introduction-to-cypress.md#Timeouts",
            "children": [
              {
                "type": "text",
                "value": "Learn about 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": "javascript",
        "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\nthe 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": 739
}