This functionality brings a new way to locate elements to help you find the ones that are nearby other elements. The available locators are:
above
below
toLeftOf
toRightOf
near
The concept behind this method is to allow you to find elements based on how one would describe them on a page. It is more natural to say: “find the element that is below the image”, rather than “find the INPUT inside the DIV with the ‘id’ of ‘main’”. In general, you could think about them as a way to locate elements based on the visual placement on the page.
For additional examples, including chaining relative locators in these languages, look at our Selenium 4 Documentation.
We will use the following login form to understand how Relative Locators work:
We would like to find the email address field, which is above the password field. To do that, we find the password field through its id, and then we use the above relative locator.
1Java23import static org.openqa.selenium.support.locators.RelativeLocator.with;4WebElement password = driver.findElement(By.id("password"));5WebElement email = driver.findElement(with(By.tagName("input")).above(passwordField));67Python89from selenium.webdriver.common.by import By10from selenium.webdriver.support.relative_locator import locate_with11passwordField = driver.find_element(By.ID, "password")12emailAddressField = driver.find_element(locate_with(By.TAG_NAME, "input").above(passwordField))1314C#1516using static OpenQA.Selenium.RelativeBy;17IWebElement passwordField = driver.FindElement(By.Id("password"));18IWebElement emailAddressField = driver.FindElement(RelativeBy(By.TagName("input")).Above(passwordField));1920Ruby2122password_field= driver.find_element(:id, "password")23email_address_field = driver.find_element(relative: {tag_name: "input", above:password_field})2425JavaScript2627let passwordField = driver.findElement(By.id('password'));28let emailAddressField = await driver.findElement(locateWith(By.tagName('input')).above(passwordField));29
Going the other way around, let's find the password field, which is below the email address field.
1Java2import static org.openqa.selenium.support.locators.RelativeLocator.with;3WebElement emailAddressField = driver.findElement(By.id("email"));4WebElement passwordField = driver.findElement(with(By.tagName("input"))5.below(emailAddressField));67Python89from selenium.webdriver.common.by import By10from selenium.webdriver.support.relative_locator import locate_with11emailAddressField = driver.find_element(By.ID, "email")12passwordField = driver.find_element(locate_with(By.TAG_NAME, "input").below(emailAddressField))1314C#1516using static OpenQA.Selenium.RelativeBy;17IWebElement emailAddressField = driver.FindElement(By.Id("email"));18IWebElement passwordField =19driver.FindElement(RelativeBy(By.TagName("input")).Below(emailAddressField));2021Ruby2223email_address_field = driver.find_element(:id, "email")24password_field = driver.find_element(relative: {tag_name: "input", below: email_address_field})2526JavaScript2728let emailAddressField = driver.findElement(By.id('email'));29let passwordField = await driver.findElement(locateWith(By.tagName('input')).below(emailAddressField));30
Let’s consider the case where we want to find the element on the left side of the “Submit” button.
1Java23import static org.openqa.selenium.support.locators.RelativeLocator.with;4WebElement submitButton = driver.findElement(By.id("submit"));5WebElement cancelButton = driver.findElement(with(By.tagName("button"))6.toLeftOf(submitButton));78Python910from selenium.webdriver.common.by import By11from selenium.webdriver.support.relative_locator import locate_with12submitButton = driver.find_element(By.ID, "submit")13cancelButton = driver.find_element(locate_with(By.TAG_NAME, "button").14to_left_of(submitButton))1516C#1718using static OpenQA.Selenium.RelativeBy;19IWebElement emailAddressField = driver.FindElement(By.Id("email"));20IWebElement passwordField =21driver.FindElement(RelativeBy(By.TagName("input")).Below(emailAddressField));2223Ruby2425submit_button= driver.find_element(:id, "submit")26cancel_button = driver.find_element(relative: {tag_name: 'button', left:submit_button})2728JavaScript2930let submitButton = driver.findElement(By.id('submit'));31let cancelButton = await driver.findElement(locateWith(By.tagName('button')).toLeftOf(submitButton));32
Now we'll consider the opposite case, where we want to find the element on the right side of the “Cancel” button.
1Java23import static org.openqa.selenium.support.locators.RelativeLocator.with;4WebElement cancelButton = driver.findElement(By.id("cancel"));5WebElement submitButton = driver.findElement(with(By.tagName("button")).toRightOf(cancelButton));67Python89from selenium.webdriver.common.by import By10from selenium.webdriver.support.relative_locator import locate_with11cancelButton = driver.find_element(By.ID, "cancel")12submitButton = driver.find_element(locate_with(By.TAG_NAME, "button").13to_right_of(cancelButton))1415C#1617using static OpenQA.Selenium.RelativeBy;18IWebElement cancelButton = driver.FindElement(By.Id("cancel"));19IWebElement submitButton = driver.FindElement(RelativeBy(By.TagName("button")).RightOf(cancelButton));2021Ruby2223cancel_button = driver.find_element(:id, "cancel")24submit_button = driver.find_element(relative: {tag_name: 'button', right:cancel_button})2526JavaScript2728let cancelButton = driver.findElement(By.id('cancel'));29let submitButton = await driver.findElement(locateWith(By.tagName('button')).toRightOf(cancelButton));30
near
is helpful when we need to find an element that is at most 50px away from the specified element. In this case, we would like to find the email address field by first finding the label of that field.
1Java23import static org.openqa.selenium.support.locators.RelativeLocator.with;4WebElement emailAddressLabel = driver.findElement(By.id("lbl-email"));5WebElement emailAddressField = driver.findElement(with(By.tagName("input")).near(emailAddressLabel));67Python89from selenium.webdriver.common.by import By10from selenium.webdriver.support.relative_locator import locate_with11emailAddressLabel = driver.find_element(By.ID, "lbl-email")12emailAddressField = driver.find_element(locate_with(By.TAG_NAME, "input").13near(emailAddressLabel))1415C#1617using static OpenQA.Selenium.RelativeBy;18IWebElement emailAddressLabel = driver.FindElement(By.Id("lbl-email"));19IWebElement emailAddressField = driver.FindElement(RelativeBy(By.TagName("input")).Near(emailAddressLabel));2021Ruby2223email_address_label = driver.find_element(:id, "lbl-email")24email_address_field = driver.find_element(relative: {tag_name: 'input', near: email_address_label})2526JavaScript2728let emailAddressLabel = driver.findElement(By.id("lbl-email"));29let emailAddressField = await driver.findElement(with(By.tagName("input")).near(emailAddressLabel));30
An updated set of methods, utilities and examples can be found at the official documentation.
Check out our comprehensive guide to Selenium 4 for more information.