How to Fix Playwright Elements Outside the Viewport

Direct answer: Playwright usually scrolls a locator into view before actions such as click(). If you need to make the step explicit, call locator.scrollIntoViewIfNeeded(), then verify visibility with expect(locator).toBeInViewport(). If the action still fails, inspect locator accuracy, overlays, visibility, stability, and enabled state: being outside the viewport is only one actionability condition.

Playwright’s normal locator actions wait for actionability checks and scroll the target into view automatically. The official documentation summarizes this behavior: “Most of the time, Playwright will automatically scroll for you before doing any actions.” Actions documentation

1. Let the locator scroll automatically

For a normal user interaction, start with a user-facing locator and the intended action:

import { test, expect } from '@playwright/test';

test('continues from a long page', async ({ page }) => {
  await page.goto('https://example.com/checkout');

  const continueButton = page.getByRole('button', { name: 'Continue' });
  await continueButton.click();
});

click() waits for the locator to resolve, checks that the element is visible, stable, enabled, and able to receive the pointer event, and scrolls it into view when needed. Prefer semantic locators such as getByRole, getByLabel, or getByText where they identify the intended control. See the locators guide.

2. Scroll an element explicitly

Use an explicit scroll when position is part of the test, when you want a separate viewport assertion, or before taking a focused screenshot.

import { test, expect } from '@playwright/test';

test('scrolls and verifies a target', async ({ page }) => {
  await page.goto('https://example.com/checkout');

  const target = page.getByRole('button', { name: 'Continue' });
  await target.scrollIntoViewIfNeeded();
  await expect(target).toBeInViewport();
  await target.click();
});

scrollIntoViewIfNeeded() performs actionability checks and scrolls only when the element is not completely visible according to the browser’s IntersectionObserver ratio. It is not a blind “scroll again” command. The Locator API documents this behavior.

Require more than a one-pixel intersection

toBeInViewport() accepts a ratio. The default ratio is zero, so any positive intersection passes. Require at least half the element when that is what the test needs:

await expect(target).toBeInViewport({ ratio: 0.5 });
await expect(target).not.toBeInViewport();

The assertion checks intersection with the viewport through the Intersection Observer API. It does not prove that the element is unobstructed or that a click will succeed. See the Locator assertions API.

3. Control whether actions may scroll

The Locator API has a scroll action option. auto is the default and allows Playwright to scroll, including nested scrollable containers. none disables scrolling and makes the action fail if the element is not already in the viewport. The documentation marks this option as added in Playwright v1.62, so check the version installed in your project before using it.

// Playwright v1.62+
await target.click({ scroll: 'auto' });
await target.click({ scroll: 'none' });

Use scroll: 'none' when the test specifically verifies that a control is already reachable without scrolling. It is usually the wrong setting for a normal end-to-end interaction because it changes the user flow.

4. Scroll with finer control

The Actions guide recommends finding the element that should become visible and scrolling it into view. For custom behavior, use the mouse wheel or browser-side scrolling.

// Scroll a known amount with the mouse
await page.mouse.wheel(0, 700);

// Scroll a nested or custom container to reveal an element
await target.evaluate((element) => {
  element.scrollIntoView({ block: 'center', inline: 'nearest', behavior: 'instant' });
});

Prefer locator-based scrolling when possible. Browser-side scrolling is useful when you need a particular alignment, a nested container, or a deterministic amount of movement. The official examples are in Playwright Actions.

5. Diagnose failures after scrolling

If scrolling succeeds but the action still fails, check every actionability condition rather than continuing to adjust scroll offsets.

Confirm the locator resolves to the intended element

await expect(target).toHaveCount(1);
console.log(await target.evaluate((element) => element.outerHTML));

A broad text locator can match a hidden template, a duplicate mobile menu, or an element in a different card. Narrow it with a role, accessible name, label, or a stable test id.

Check visibility and geometry

const state = await target.evaluate((element) => {
  const rect = element.getBoundingClientRect();
  const style = getComputedStyle(element);
  return {
    rect: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
    display: style.display,
    visibility: style.visibility,
    opacity: style.opacity,
    disabled: (element as HTMLButtonElement).disabled ?? false
  };
});
console.log(state);

An element with display: none, visibility: hidden, zero dimensions, or an unexpected disabled state cannot be used like a visible control.

Look for an overlay or interception

A sticky header, cookie dialog, modal, loading mask, or chat widget can cover the target after it is scrolled into view. Inspect the trace or screenshot at the failure point, then close the overlay through the same user-facing interaction a user would use.

const consent = page.getByRole('button', { name: /accept|agree/i });
if (await consent.isVisible().catch(() => false)) {
  await consent.click();
}
await target.click();

Do not make force: true the default fix. It bypasses actionability checks; it does not make a covered or unusable element genuinely clickable.

Wait for layout and content to settle

Virtualized lists, images without dimensions, transitions, and late-loading fonts can move an element between the scroll and the action. Prefer a locator assertion that represents the real ready state:

await expect(page.getByRole('heading', { name: 'Checkout' })).toBeVisible();
await expect(target).toBeEnabled();
await target.scrollIntoViewIfNeeded();
await target.click();

Avoid arbitrary delays unless the site has no observable readiness signal. If a transition is unavoidable, wait for the relevant class, attribute, network response, or application state.

6. Nested scroll containers and sticky layouts

An element can be inside a scrollable panel while the page itself is already at the correct position. Playwright’s automatic scrolling can handle nested containers, but custom CSS may prevent the expected movement. Identify the scrollable ancestor and inspect its dimensions:

const details = await target.evaluate((element) => {
  const ancestors = [];
  let node: HTMLElement | null = element.parentElement;
  while (node) {
    const style = getComputedStyle(node);
    if (/(auto|scroll)/.test(style.overflowY) && node.scrollHeight > node.clientHeight) {
      ancestors.push({
        tag: node.tagName,
        className: node.className,
        scrollTop: node.scrollTop,
        scrollHeight: node.scrollHeight,
        clientHeight: node.clientHeight
      });
    }
    node = node.parentElement;
  }
  return ancestors;
});
console.log(details);

For sticky headers, center the target or add test-only layout rules rather than relying on a top-aligned scroll position that leaves the control underneath the header.

7. Screenshots: locator versus full page

These two screenshot APIs solve different problems:

Goal	API	Behavior
Capture one element	`locator.screenshot()`	Runs actionability checks and scrolls the element into view before capturing it.
Capture the entire document	`page.screenshot({ fullPage: true })`	Captures the full scrollable page rather than only the current viewport.

await target.screenshot({ path: 'continue-button.png' });
await page.screenshot({ path: 'whole-page.png', fullPage: true });

A locator screenshot positions an element for its own image. It does not guarantee that another fixed element is not covering it. A full-page screenshot is about page length, not interactive viewport visibility. See the Page API.

8. A complete diagnostic test

import { test, expect } from '@playwright/test';

test('diagnoses an off-screen control', async ({ page }) => {
  await page.goto('https://example.com/checkout', { waitUntil: 'domcontentloaded' });

  const target = page.getByRole('button', { name: 'Continue' });
  await expect(target).toHaveCount(1);
  await expect(target).toBeVisible();
  await target.scrollIntoViewIfNeeded();
  await expect(target).toBeInViewport({ ratio: 0.5 });
  await expect(target).toBeEnabled();

  await target.screenshot({ path: 'target.png' });
  await target.click();
});

If this test fails, retain the trace and inspect the last successful assertion. That tells you whether the problem is locator resolution, visibility, scrolling, intersection, enabled state, or the click itself.

9. Troubleshooting checklist

Symptom	Likely cause	Fix
“Element is outside of the viewport”	Action was configured not to scroll, or a custom scroll container blocked movement.	Remove `scroll: 'none'`, call `scrollIntoViewIfNeeded()`, and inspect scrollable ancestors.
Locator times out before scrolling	Wrong selector, delayed rendering, or frame boundary.	Use a semantic locator, wait for the real ready state, or target the correct frame.
Element is visible but click is intercepted	Modal, sticky header, consent banner, or another overlay covers it.	Dismiss the overlay and capture a trace or screenshot to confirm the stacking order.
Element moves during the click	Layout shift from images, fonts, animation, or virtualized content.	Wait for a stable application state and avoid arbitrary coordinate clicks.
`toBeInViewport()` passes but click fails	Intersection does not prove unobstructed pointer access.	Check overlays, enabled state, stability, and the locator’s matched node.
Full-page screenshot misses lazy images	Images load only after their region is visited or after interaction.	Scroll through the page or wait for image completion before capturing.

10. Performance, reliability, and cost

Performance: A locator action is usually cheaper and more stable than manually scrolling in several increments. Use semantic locators and one explicit scrollIntoViewIfNeeded() only when the test needs a separate position step.
Reliability: Assertions should describe user-visible readiness. Traces, screenshots, and locator counts make failures diagnosable. Avoid coordinate clicks and blanket force options.
Viewport consistency: Set a deliberate viewport and device scale in the Playwright project when geometry matters. Keep responsive breakpoints in separate projects if the expected layout differs.
Test cost: Full-page screenshots and long pages require more rendering and image memory than a locator screenshot. Capture only the region needed for an assertion or artifact.

11. Or skip the browser setup

If the goal is a clean page image rather than an interaction inside a test, ScreenshotNeo provides a single screenshot request. Its capture flow accepts cookie and consent banners before the shot and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers.

See the ScreenshotNeo API documentation for all options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot failed: ${res.status}`);
const data = Buffer.from(await res.arrayBuffer());
require('fs').writeFileSync('shot.webp', data);

ScreenshotNeo also supports full-page and element captures, custom CSS and JavaScript, waits, device presets, dark mode, PDF output, blocking rules, headers and cookies, caching, signed links, asynchronous jobs, bulk capture, and an MCP server with take_screenshot, get_page_info, and capture_pdf tools for AI agents. One thousand screenshots a month are free with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.

12. FAQ

Does Playwright always scroll before clicking?

Locator actions generally scroll automatically as part of actionability checks. Explicit scrolling is useful when the position itself is under test or when you need a separate viewport assertion.

What does “in the viewport” mean?

It means the element intersects the viewport according to Intersection Observer. Use a ratio when a small visible sliver is not sufficient.

Should I use `force: true`?

Only when you intentionally want to bypass actionability checks and understand the consequence. It does not fix an overlay, incorrect locator, or unstable layout.

When should I use `fullPage`?

Use it when you need the entire scrollable document. Use locator.screenshot() when you need an image of one element after it has been brought into view.

Which Playwright versions support the scroll action option?

The Locator API marks the scroll option as added in v1.62. Check your installed version before relying on it.