Selenium 4 relative locators find a candidate element by its position in relation to another element you can already locate—for example, a button below an email field. Use them when a spatial relationship is easier to express than a direct locator, and remember that the relationship depends on the elements’ rendered positions.
What Selenium 4 relative locators do
Relative locators combine two things: a locator for the elements you want to consider and a spatial relationship to a known reference element. Selenium calls these Relative Locators; they were previously called “Friendly Locators.” The Selenium locator guide explains that Selenium uses JavaScript getBoundingClientRect() to determine element size and position, then uses that geometry to find neighboring elements.
This makes a relative locator useful when the target is hard to identify directly but its position beside a known element is clear. It does not make a target intrinsically unique: if several elements satisfy the relationship, you may need to narrow the candidate locator or add another spatial filter.
Which spatial relationships are available?
| Relationship | Meaning |
|---|---|
above |
Find a candidate above the reference element. |
below |
Find a candidate below the reference element. |
toLeftOf |
Find a candidate to the left of the reference element. |
toRightOf |
Find a candidate to the right of the reference element. |
near |
Find a candidate close to the reference element. |
The reference point can be an ordinary locator or an element you have already found. The exact method spelling and syntax differ across Selenium bindings; the example below uses Python.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
#1 Best Overall
Find an element with a relative locator in Python
In the example, the email field is located by its ID, and the target button is identified as a button below it. The code assumes you have already created a Selenium WebDriver instance named driver and opened the page under test.
from selenium.webdriver.common.by import By
from selenium.webdriver.support.relative_locator import locate_with
email_field = driver.find_element(By.ID, "email")
submit_button = driver.find_element(
locate_with(By.TAG_NAME, "button").below(email_field)
)
submit_button.click()The candidate locator here is By.TAG_NAME, "button"; the reference element is email_field; and below(email_field) supplies the spatial condition. Selenium’s Python API reference for version 4.50.0 documents the same general form, including locate_with(By.CSS_SELECTOR, "p").above(element).
Use a locator as the reference
You can also pass a locator as the reference instead of finding the reference element first. For example, the Python pattern is locate_with(By.TAG_NAME, "button").below({By.ID: "email"}). Passing a previously found element is useful when you already need that element for another part of the test; passing a locator can keep a short lookup in one expression.
Chain relationships to narrow the result
When one relationship matches too many candidates, chain another filter. Selenium documents combining relationships—for example, constraining a button to be below an email field and to the right of a cancel button. This expresses both conditions instead of relying on whichever matching button happens to be returned.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchRank #3
email_field = driver.find_element(By.ID, "email")
cancel_button = driver.find_element(By.ID, "cancel")
submit_button = driver.find_element(
locate_with(By.TAG_NAME, "button")
.below(email_field)
.to_right_of(cancel_button)
)Set the distance for near
In Selenium’s Python binding, near defaults to 50 pixels. You can supply a distance in pixels when the default is not appropriate; the Python API reference says the distance must be positive, so zero or a negative value is invalid.
help_icon = driver.find_element(
locate_with(By.CSS_SELECTOR, "button").near(email_field, 80)
)Use a distance that matches the layout you intend to test. A larger radius can include more nearby candidates, so combine near with a more specific candidate locator or another relationship if needed.
When relative locators are a good fit
- Use one when: a stable reference element is easy to locate, while the target is naturally described as above, below, left, right, or nearby.
- Prefer a direct CSS or XPath locator when: the target has a clear, stable attribute or structural path. A direct locator states what the element is; a relative locator states where it appears in the rendered layout.
- Be cautious when: responsive layouts, viewport changes, or page content changes can move elements. Relative locators reason from rendered geometry, so check that the relationship remains meaningful at the viewport used by the test.
These are practical trade-offs, not a claim that relative locators are faster or more reliable. Selenium’s documentation describes their purpose and geometry, but does not establish comparative performance or reliability measurements.
Troubleshoot relative-locator failures
No element matches
- Confirm that the reference element is present and that your ordinary locator finds it.
- Check the page at the test’s current viewport: the target may not actually be on the expected side after responsive reflow.
- Check that the candidate locator describes the target’s element type or attributes, and that the intended spatial relationship is accurate.
The wrong candidate is found
- Narrow the candidate locator instead of searching every element of a broad type such as
button. - Chain another relationship when multiple candidates satisfy the first one.
- Reconsider whether layout position uniquely identifies the target. If it does not, use a direct locator based on a stable attribute or structure.
near raises an error or matches too broadly
- For Python, provide a positive distance; zero and negative distances are invalid.
- If the default 50-pixel distance includes unintended elements, use a smaller positive distance or a more specific candidate locator.
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server, not a Selenium relative-locator replacement. If you need a screenshot of a page rather than an automated element lookup, one GET request can return an image or PDF. Its capture can accept cookie or consent banners and remove more than 60 known consent platforms, newsletter popups, and chat widgets before the shot; those steps can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing status. AI agents can use its MCP server tools, including take_screenshot, get_page_info, and capture_pdf.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request options. The free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000. Sign up for ScreenshotNeo’s free plan.
Frequently Asked Questions
Does a relative locator replace Selenium’s ordinary locators?
No. It uses an ordinary candidate locator together with a spatial relationship to a reference element.
Can I use a relative locator with an already located element?
Yes. In Python, the reference can be a WebElement, as in locate_with(By.CSS_SELECTOR, "p").above(element).
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.
