Hide a Navbar in WebdriverIO Screenshot Tests

To hide a navbar in a WebdriverIO visual screenshot, pass its resolved element in the hideElements option. This applies visibility: hidden, so the navbar’s layout space remains. To remove the navbar and let the page content move into its space, use removeElements, which applies display: none. Choose based on the layout your baseline screenshot is meant to represent.

The examples below use the WebdriverIO visual service’s checkScreen method. Confirm that your installed @wdio/visual-service version and selected visual assertion method support these options. The selector header nav is only an example; replace it with a selector that uniquely identifies your navbar.

Hide the navbar while preserving its space

Use this when you want the navbar invisible but want the content below it to stay in the same position:

await browser.checkScreen('page-without-navbar', {
  hideElements: [await $('header nav')],
})

hideElements makes the selected element invisible with visibility: hidden. Its box still participates in layout, so the page below it should not shift just because the navbar is hidden. This is usually the closer match when the purpose is to exclude changing navigation text, icons, or account state from a visual comparison while preserving the page geometry.

Remove the navbar and reclaim its space

If the screenshot should show the page as though the navbar is absent, use removeElements:

await browser.checkScreen('page-without-navbar', {
  removeElements: [await $('header nav')],
})

This applies display: none. The navbar no longer takes up layout space, and content may move upward. Use the same behavior when creating and updating baselines; switching between hiding and removing changes the expected geometry.

Choose a stable selector and capture scope

1. Find a unique navbar locator. Prefer a stable application attribute or a selector scoped to a known page region. WebdriverIO uses CSS selector patterns by default when no other selector strategy is specified.
2. Resolve the element. Pass the WebdriverIO element returned by $() in the option array, as shown above.
3. Select the assertion scope. WebdriverIO visual testing supports screen, element, and full-page comparisons. Make sure the chosen visual method and its options match the portion of the page you intend to compare.
4. Keep the choice consistent. Use the same selector and hide/remove behavior for baseline creation and later comparisons.

For example, if the application has a stable test attribute, use that in place of the sample selector:

await browser.checkScreen('account-dashboard', {
  hideElements: [await $('[data-testid="primary-navigation"]')],
})

Do not use a selector that can match unrelated navigation elements. If the locator resolves to the wrong element or no element, first inspect the page structure and the selector result in the same test state used for capture.

Reduce unrelated visual differences

Hiding the navbar controls only that element. Fonts, scrollbars, animation, browser rendering, and page state can still affect a comparison. The visual service documents these options and defaults:

Option	Documented default	When to consider it
waitForFontsLoaded	true	Keep font loading in mind when text spacing or line wrapping differs.
hideScrollBars	true	Check this if the captured viewport edge or available content width differs.
disableCSSAnimation	false	Enable the documented option when CSS motion creates changing pixels during capture.

These settings can make captures more consistent, but they do not guarantee identical rendering across browsers, operating systems, or devices. Use the options supported by the service version installed in your project.

Troubleshooting

Symptom	Likely cause	What to do
The content below the navbar shifts.	removeElements removes the element from layout.	Use hideElements if the navbar should remain an invisible placeholder.
A blank gap remains at the top.	hideElements preserves the navbar’s layout space.	Use removeElements if content should move into that space.
The navbar is still visible.	The selector may not match the rendered navbar, may match a different node, or the selected method/version may not apply the option as expected.	Inspect the DOM in the test state, use a unique locator, and confirm the method options for the installed visual-service version.
The visual assertion still fails after hiding it.	Other pixels may differ because of font loading, animation, scrollbars, dynamic content, or a different capture scope.	Check the service stability options, compare the same scope, and inspect the diff outside the navbar.
The option appears unsupported.	The example may not match the installed service version or assertion method.	Consult the documentation for the exact version and method used by the project before changing the test.

Or skip the browser setup

If you need a clean page screenshot rather than a WebdriverIO visual assertion, ScreenshotNeo captures a URL with one API request. Its options also include CSS selectors for hiding elements. See the API documentation for the supported request parameters.

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,
)
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 request failed: ${res.status}`);
await Bun.write('shot.webp', res);

Cookie banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. An MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.

Sign up for 1,000 free screenshots a month, with no card.

FAQ

Does hiding the navbar change the page layout?

No. hideElements uses visibility: hidden, which preserves the element’s layout space.

When should I use removeElements?

Use it when the navbar should take up no space in the captured layout. The resulting content may shift.

Can I use this with a full-page comparison?

WebdriverIO visual testing supports full-page comparisons. Check the selected method’s options and the page’s behavior, since sticky navigation and page length can affect what the capture shows.

Which test runners work with WebdriverIO visual testing?

The documentation lists Mocha, Jasmine, and CucumberJS as supported visual-test runner frameworks.