Use locator.setVisibility(value) to configure whether a Puppeteer locator waits for an element to be visible or hidden before an action. For example, setVisibility(null) disables that visibility check. It changes the locator’s action behavior—not the element’s CSS or actual visibility.
Set visibility on a locator
In Puppeteer 25.12.0, Locator.setVisibility(visibility) returns a new locator cloned from the original with its visibility setting changed. Configure the returned locator and use it for the action:
await page
.locator('button')
.setVisibility(null)
.click();Here, null disables the locator’s visibility check. It does not reveal a hidden button, change its styles, or guarantee that the click will succeed. Other action conditions may still apply. Puppeteer’s page interactions guide describes locators as the recommended way to select and interact with elements.
What the visibility setting changes
A locator action can wait for the selected element to meet action preconditions. For clicks, Puppeteer’s guide identifies conditions including visibility, being in the viewport, being enabled, and having a stable bounding box. setVisibility() configures the visibility part of that behavior; it is not a page-style setter.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitches#1 Best Overall
- Use a visibility setting when configuring how a locator action should wait.
- Use
nullwhen you specifically need to disable visibility checks. - Do not treat disabling the check as a fix for an element that is missing, covered, disabled, or otherwise unsuitable for the action.
See the Locator.setVisibility() API reference and the Locator class reference for the documented signature and method inventory.
Choose between setVisibility() and waitForSelector()
These APIs address related but different tasks. Use setVisibility() to configure a locator used for an action; use waitForSelector() when you need an explicit wait for a selector’s DOM or visibility state.
Rank #2
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
| Need | Use | Result |
|---|---|---|
| Configure visibility checking for a locator action | locator.setVisibility(value) |
A cloned locator with the changed visibility setting |
| Wait explicitly for a selector to become visible or hidden | page.waitForSelector(selector, options) |
An element handle, or null when waiting for the hidden state and no matching element remains |
For waitForSelector(), visible: true waits for the element to be in the DOM and not have display: none or visibility: hidden. hidden: true waits until it is absent or hidden by those CSS properties. The documented default timeout is 30,000 ms; change it with Page.setDefaultTimeout(). See the Page.waitForSelector() reference.
Wait for visibility before working with an element
Use this pattern when the task is to wait explicitly for a visible selector and then use its returned handle:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Rank #3
- Brand: Wiley
- Set of 2 Volumes
- A handy two-book set that uniquely combines related technologies Highly visual format and accessible language makes these books highly effective learning tools Perfect for beginning web designers and front-end developers
const button = await page.waitForSelector('button', {
visible: true,
timeout: 30_000,
});
if (!button) {
throw new Error('Button was not found or did not become visible');
}
await button.click();The explicit if handles the possibility of a null result in cases where a wait resolves without a matching element, such as waiting for a hidden selector. For visibility waits, the timeout can be set in the call as above or changed globally with Page.setDefaultTimeout(). For locator-based interaction, see the Page.locator() reference.
Troubleshoot visibility-related failures
- The element remains hidden:
setVisibility(null)skips the locator visibility check; it does not change CSS. Change the page state or use an explicit wait for visibility if you need to confirm it has become visible. - The action still fails after disabling visibility checks: Visibility is only one click precondition. Check that the element exists and that other conditions—such as viewport position, enabled state, or a stable bounding box—are satisfied.
waitForSelector()times out: Confirm the selector matches the intended element and that the page reaches the requested visible or hidden state before the timeout. The documented default is 30,000 ms; adjust the call’s timeout orPage.setDefaultTimeout()if the page legitimately takes longer.- You need an element handle, not locator action configuration: Use
waitForSelector();setVisibility()returns a locator.
Or skip the browser setup
If your goal is to capture a page rather than interact with it in Puppeteer, ScreenshotNeo can return a screenshot through one GET request. See the ScreenshotNeo API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo accepts cookie and consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; those steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and each response identifies the page verdict and billing status in headers. Its MCP server offers take_screenshot, get_page_info, and capture_pdf for AI agents. The free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots. Learn about ScreenshotNeo or sign up for 1,000 free screenshots a month with no card.
Version scope
The linked Puppeteer API references and guide identify version 25.12.0. If you use a later version, check its current documentation for signatures and defaults.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
