UiPath Documentation
activities
latest
false
UI Automation activities

Navigation tag

The nav selector tag, used to target an element by navigating from the element matched by the rest of the selector.

About the nav tag​

A navigation tag, <nav />, navigates in the UI tree from the element matched by the preceding tags to a related element (its parent, one of its siblings, or one of its children), using one of its attributes. Navigation tags work best when the element you want has no stable attributes of its own, but a nearby element does.

For example, a list item might have no reliable name, while the list that contains it does. You can target the list by its attributes, then use a navigation tag to reach the item by its position.

Attributes​

Each attribute takes a whole number that sets how far to move.

AttributeMoves toAccepted values
upAn ancestor of the current element. up='1' is the parent, up='2' the parent of the parent, and so on.1 or greater
nextA following sibling. next='1' is the next sibling.1 or greater
prevA preceding sibling. prev='1' is the previous sibling.1 or greater
childA child of the current element, by position. Positive values count from the first child (child='1' is the first child). Negative values count from the last child (child='-1' is the last child, child='-2' the second to last).Any whole number except 0

The child attribute is available starting with UiPath.UIAutomation.Activities 26.10.8.

How navigation tags work​

A navigation tag starts from the element that the tags before it have reached. Then:

  • A navigation tag can be the last tag in a selector. The selector then targets the element the tag lands on.
  • If another tag follows a navigation tag, that tag searches the descendants of the element the navigation tag landed on.
  • You can chain several navigation tags. Each one starts from where the previous one landed.

Each navigation tag should use one attribute. If a tag has more than one attribute, the moves are applied in this order: up, next, prev, child.

Which elements count as children and siblings​

The children of an element are the same elements shown under that element in the UI Tree: elements of a single UI technology, in tree order, including hidden elements. Siblings are the other children of the same parent.

When the current element is a window (<wnd>), its children come from the first UI technology that has children for that window.

When a navigation fails​

The selector returns a navigation error in these cases:

  • The value is 0, for example child='0' or up='0'.
  • The value points past the available elements, for example child='5' on an element with three children, or next='2' on the last sibling but one.
  • The value is not a number. In this case the selector fails when it is parsed.

Versions earlier than UI Automation v26.10.8 also return a navigation error for selectors that use the child attribute.

In activities that look for all matching elements, a navigation tag returns the single element it lands on.

Examples​

Target the last item of a list whose length changes​

The selector always targets the last message, however many messages the list contains. When a new message is added, the selector moves to it.

<wnd app='app.exe' /><uia name='Messages' role='list' /><nav child='-1' />
<wnd app='app.exe' /><uia name='Messages' role='list' /><nav child='-1' />

Target the second to last item​

<wnd app='app.exe' /><uia name='Messages' role='list' /><nav child='-2' />
<wnd app='app.exe' /><uia name='Messages' role='list' /><nav child='-2' />

Target the first child of an element​

<wnd app='app.exe' /><uia name='Messages' role='list' /><nav child='1' />
<wnd app='app.exe' /><uia name='Messages' role='list' /><nav child='1' />

Target the parent of an element with a stable label​

<html app='chrome.exe' title='Orders' />
<webctrl tag='SPAN' innertext='Order total' />
<nav up='1' />
<html app='chrome.exe' title='Orders' />
<webctrl tag='SPAN' innertext='Order total' />
<nav up='1' />

Target the element next to a label​

The selector finds a label, then moves to the sibling that follows it, such as the value field shown next to the label.

<html app='chrome.exe' title='Orders' />
<webctrl tag='SPAN' innertext='Order total' />
<nav next='1' />
<html app='chrome.exe' title='Orders' />
<webctrl tag='SPAN' innertext='Order total' />
<nav next='1' />

Chain navigation tags​

The selector moves up to the row that contains the label, then to the third child of that row.

<html app='chrome.exe' title='Orders' />
<webctrl tag='SPAN' innertext='Order total' />
<nav up='1' />
<nav child='3' />
<html app='chrome.exe' title='Orders' />
<webctrl tag='SPAN' innertext='Order total' />
<nav up='1' />
<nav child='3' />

Search inside the element a navigation tag lands on​

The tag after the navigation tag searches only within the last row of the table.

<html app='chrome.exe' title='Orders' />
<webctrl tag='TABLE' id='orders' />
<nav child='-1' />
<webctrl tag='BUTTON' innertext='Edit' />
<html app='chrome.exe' title='Orders' />
<webctrl tag='TABLE' id='orders' />
<nav child='-1' />
<webctrl tag='BUTTON' innertext='Edit' />

The idx attribute counts all matching elements among the descendants of the current element. When content is added or removed, the same idx value can point to a different element.

A navigation tag with child counts only the direct children of a known element, and negative values count from the end. Use child when the position you care about is fixed relative to the start or the end of a list, such as the first or the last item.

Platform support​

AttributeWindowsCross-platform
upSupportedSupported
nextSupportedSupported starting with 26.10.8
prevSupportedSupported starting with 26.10.8
childSupported starting with 26.10.8Supported starting with 26.10.8
Navigation tags in searches that return multiple elementsSupportedSupported starting with 26.10.8

Before 26.10.8, selectors that used next, prev, or navigation tags in searches that return multiple elements worked in Windows projects but failed in cross-platform projects.

Was this page helpful?

Connect

Need help? Support(opens in new window)

Want to learn? UiPath Academy(opens in new window)

Have questions? UiPath Forum(opens in new window)

Stay updated