Playwright: How to Wait Until Element Is Visible (Best Practices + Examples)

When automating UI interactions using Playwright, waiting for an element to become visible is a critical step to avoid flaky tests or runtime errors.

In this guide, you’ll learn how to wait until an element is visible in Playwright using reliable methods, with code examples, a comparison table, and best practices.

✅ Quick Answer

await page.locator('#my-element').waitFor({ state: 'visible' });

This waits until the element:

• Exists in the DOM
• Is not hidden (display: none, visibility: hidden, etc.)
• Has non-zero dimensions

📦 Method 1: locator.waitFor({ state: 'visible' }) (Recommended)

await page.locator('.loader').waitFor({ state: 'visible' });

• ✅ Clean, readable
• ✅ Retries automatically
• ✅ Respects timeouts

🧪 Method 2: expect(locator).toBeVisible() (Built-in Assertion)

If you're using Playwright's test runner:

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

await expect(page.locator('#login-button')).toBeVisible();

• ✅ Assertion-style
• ✅ Waits automatically
• ✅ Great for test suites

🧪 Method 3: Manual Loop (Advanced)

await page.waitForFunction(() => {
  const el = document.querySelector('#my-element');
  return el && el.offsetParent !== null;
});

• 🔧 For complex visibility checks
• ⚠️ More verbose and brittle

⏱ Optional: Set Timeout

await page.locator('.modal').waitFor({ state: 'visible', timeout: 10000 });

• 🕐 Waits up to 10 seconds
• Throws error if not visible in time

🧰 Comparison Table

🧩 Use Cases

🧠 Pro Tips

• Use state: 'attached' if element may exist but be hidden
• Chain with actions:

await page.locator('#menu').waitFor({ state: 'visible' });
await page.click('#menu');

• Use Playwright Test’s auto-waiting: it waits for visibility before click(), fill(), etc.

❌ Common Mistakes

🏁 Conclusion

To wait for an element to become visible in Playwright:

• Use locator.waitFor({ state: 'visible' }) for reliability
• Use expect(...).toBeVisible() in test assertions
• Use custom logic with waitForFunction() when needed

These strategies will make your tests more stable and your scripts more accurate.