{
  "doc": {
    "id": "api/commands/blur",
    "title": "cy.blur()",
    "description": "Blur a focused element in Cypress.",
    "section": "api",
    "source_path": "/llm/markdown/api/commands/blur.md",
    "version": "8d4bb7c9d1af182786c46b47bac667515b9e5d39",
    "updated_at": "2026-08-07T13:17:53.464Z",
    "headings": [
      {
        "id": "api/commands/blur#blur",
        "text": "blur",
        "level": 1
      },
      {
        "id": "api/commands/blur#syntax",
        "text": "Syntax",
        "level": 2
      },
      {
        "id": "api/commands/blur#usage",
        "text": "Usage",
        "level": 3
      },
      {
        "id": "api/commands/blur#arguments",
        "text": "Arguments",
        "level": 3
      },
      {
        "id": "api/commands/blur#yields",
        "text": "Yields",
        "level": 3
      },
      {
        "id": "api/commands/blur#examples",
        "text": "Examples",
        "level": 2
      },
      {
        "id": "api/commands/blur#no-args",
        "text": "No Args",
        "level": 3
      },
      {
        "id": "api/commands/blur#blur-the-comment-input",
        "text": "Blur the comment input",
        "level": 4
      },
      {
        "id": "api/commands/blur#options",
        "text": "Options",
        "level": 3
      },
      {
        "id": "api/commands/blur#blur-the-first-input",
        "text": "Blur the first input",
        "level": 4
      },
      {
        "id": "api/commands/blur#notes",
        "text": "Notes",
        "level": 2
      },
      {
        "id": "api/commands/blur#actionability",
        "text": "Actionability",
        "level": 3
      },
      {
        "id": "api/commands/blur#blur-is-not-an-action-command",
        "text": "Blur is not an action command",
        "level": 4
      },
      {
        "id": "api/commands/blur#timeouts",
        "text": "Timeouts",
        "level": 3
      },
      {
        "id": "api/commands/blur#blur-can-time-out-because-your-browser-did-not-receive-any-blur-events",
        "text": ".blur() can time out because your browser did not receive any blur events",
        "level": 4
      },
      {
        "id": "api/commands/blur#rules",
        "text": "Rules",
        "level": 2
      },
      {
        "id": "api/commands/blur#requirements",
        "text": "Requirements",
        "level": 3
      },
      {
        "id": "api/commands/blur#assertions",
        "text": "Assertions",
        "level": 3
      },
      {
        "id": "api/commands/blur#timeouts",
        "text": "Timeouts",
        "level": 3
      },
      {
        "id": "api/commands/blur#command-log",
        "text": "Command Log",
        "level": 2
      },
      {
        "id": "api/commands/blur#see-also",
        "text": "See also",
        "level": 2
      }
    ]
  },
  "content": {
    "type": "root",
    "children": [
      {
        "type": "heading",
        "depth": 1,
        "children": [
          {
            "type": "text",
            "value": "blur"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Blur a focused 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 `.blur()`."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "This element must currently be in focus. If you want to ensure an element is focused before blurring, try using "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/api/commands/focus.md",
            "children": [
              {
                "type": "text",
                "value": "`.focus()`"
              }
            ]
          },
          {
            "type": "text",
            "value": " before `.blur()`."
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cy.get('button').as('btn').focus()cy.get('@btn').blur()"
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Syntax"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": ".blur().blur(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('[type=\"email\"]').blur() // Blur email inputcy.get('[tabindex=\"1\"]').blur() // Blur el with tabindex"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Incorrect Usage"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cy.blur('input') // Errors, cannot be chained off 'cy'cy.window().blur() // 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 `.blur`."
          }
        ]
      },
      {
        "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": "`force`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`false`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Forces the action, disables checking if "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "#Requirements",
                    "children": [
                      {
                        "type": "text",
                        "value": "element is focused"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "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 `.blur()` 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": "`.blur()` 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 `.blur()`."
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "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": "Blur the comment input"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cy.get('[name=\"comment\"]').type('Nice Product!')cy.get('[name=\"comment\"]').blur()"
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Options"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Blur the first input"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Setting `force` to `true` in the options disables checking whether the input is focusable or currently has focus."
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cy.get('input:first').blur({ force: true })"
      },
      {
        "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": "Blur is not an action command"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "`.blur()` 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": "`.blur()` is a helpful command used as a shortcut. Normally there's no way for a user to \"blur\" an element. Typically the user would have to perform another action like clicking or tabbing to a different element. Needing to perform a separate action like this is very indirect."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Therefore it's often much more efficient to test the blur behavior directly with `.blur()`."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Timeouts"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "`.blur()` can time out because your browser did not receive any blur 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": "`.blur()` requires being chained off a command that yields DOMelement(s)."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "`.blur()` requires the element to currently have focus."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "`.blur()` 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": "`.blur()` 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": "`.blur()` 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": "Blur a textarea after typing."
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cy.get('[name=\"comment\"]').focus()cy.get('[name=\"comment\"]').type('Nice Product!')cy.get('[name=\"comment\"]').blur()"
      },
      {
        "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 `blur` 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/focus.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "`.focus()`"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "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()`"
                      }
                    ]
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  },
  "token_estimate": 712
}