Overview
The Element class represents an HTML DOM element and provides methods for interaction, property access, and traversal. Elements are returned by Tab methods like find(), select(), and query_selector_all().
Elements are created by Tab methods. Don’t instantiate Element directly.
Creation
# Find element by text
button = await tab.find('Login')
# Find by CSS selector
input_field = await tab.select('input[name="email"]')
# Find all elements
links = await tab.select_all('a')
Properties
Node Properties
The HTML tag name in lowercase (e.g., ‘div’, ‘button’, ‘a’).
Node name (uppercase tag name).
Node type number (1 = element, 3 = text, etc.).
Value of the node (for text nodes).
Local name of the element.
Element Relationships
Parent element. Requires calling await element.update() first.
List of child elements. Requires calling await element.update() first.
Node ID of the parent element.
Attributes
Dictionary-like object containing all HTML attributes (href, src, class, id, etc.).
Raw list of attribute names and values.
Special Properties
Reference to the Tab this element belongs to.
Shadow root nodes attached to this element.
Children within shadow DOM.
Frame identifier if element is in an iframe.
Attribute Access
Access HTML attributes directly on the element:
# Get attributes
link = await tab.select('a')
url = link.href # Get href attribute
link_class = link.class_ # Get class attribute
link_id = link.id # Get id attribute
# Using attrs dictionary
url = link.attrs.href
link_class = link.attrs['class']
# Set attributes (will be applied when saving)
link.href = 'https://newurl.com'
link['data-value'] = '123'
Methods
click()
Click the element.
Example:
button = await tab.find('Submit')
await button.click()
apply()
Apply JavaScript function to this element.
async def apply(
self,
js_function: str,
return_by_value: bool = True
)
JavaScript function that receives the element as a parameter. Can be an arrow function or function declaration.
Return the value directly instead of a remote object reference.
input_field = await tab.select('input[name="email"]')
# Set value
await input_field.apply('(elem) => elem.value = "[email protected]"')
# Get value
value = await input_field.apply('(elem) => elem.value')
print(value) # "[email protected]"
# Call method
await video.apply('elem => elem.play()')
# Multiple operations
result = await input_field.apply('''
(elem) => {
elem.value = "hello";
elem.focus();
return elem.value;
}
''')
update()
Update element to retrieve latest properties and enable parent/children access.
async def update(self, _node=None) -> Element
element = await tab.select('div')
await element.update()
# Now you can access parent and children
parent = element.parent
children = element.children
get_position()
Get the position and size of the element.
async def get_position(self, abs: bool = False) -> Position
Get absolute position on page instead of viewport-relative.
element = await tab.select('button')
pos = await element.get_position()
print(f"Position: ({pos.x}, {pos.y}), Size: {pos.width}x{pos.height}")
flash()
Flash the element to highlight it visually.
async def flash(self, duration: float = 0.5)
Duration in seconds to flash.
element = await tab.find('Important')
await element.flash() # Highlight for debugging
async def scroll_into_view(self)
footer = await tab.select('footer')
await footer.scroll_into_view()
mouse_move()
Move mouse to this element.
async def mouse_move(self, steps: int = 10)
Number of steps for smooth movement.
button = await tab.select('button')
await button.mouse_move()
mouse_click()
Click on this element using mouse coordinates.
async def mouse_click(
self,
button: str = 'left',
buttons: int = 1,
modifiers: int = 0
)
mouse_drag()
Drag this element to a new position.
async def mouse_drag(
self,
to_pos: Tuple[float, float],
relative: bool = False
)
to_pos
Tuple[float, float]
required
Target position as (x, y) coordinates.
Whether coordinates are relative to current position.
# Drag element to absolute position
element = await tab.select('.draggable')
await element.mouse_drag((500, 300))
# Drag relative to current position
await element.mouse_drag((100, 50), relative=True)
save_to_dom()
Save element changes back to the DOM.
async def save_to_dom(self)
link = await tab.select('a')
link.href = 'https://newurl.com'
await link.save_to_dom() # Apply changes
remove_from_dom()
Remove this element from the DOM.
async def remove_from_dom(self)
ad = await tab.select('.advertisement')
await ad.remove_from_dom() # Remove from page
get_html()
Get the HTML content of the element.
async def get_html(self) -> str
div = await tab.select('div.content')
html = await div.get_html()
print(html)
get_js_attributes()
Get JavaScript properties of the element.
async def get_js_attributes(self) -> ContraDict
input_field = await tab.select('input')
js_attrs = await input_field.get_js_attributes()
print(js_attrs.value, js_attrs.checked)
text_all
Get all text content recursively.
async def text_all(self) -> str
text
Get immediate text content.
async def text(self) -> str
paragraph = await tab.select('p')
text = await paragraph.text()
print(text)
Querying Within Elements
Find child elements within an element:
# Find children using CSS selectors
container = await tab.select('div.container')
buttons = await container.query_selector_all('button')
# Using Tab methods with parent element
for button in buttons:
await button.click()
Traversing the DOM
element = await tab.select('div')
await element.update() # Required for parent/children access
# Access parent
parent = element.parent
print(parent.tag)
# Access children
for child in element.children:
print(child.tag)
# Access shadow DOM children
if element.shadow_children:
for shadow_child in element.shadow_children:
print(shadow_child.tag)
Shadow DOM
Work with shadow DOM elements:
# Check if element has shadow root
element = await tab.select('custom-element')
if element.shadow_roots:
print("Has shadow DOM")
# Access shadow children
if element.shadow_children:
for child in element.shadow_children:
print(child.tag)
Examples
import nodriver as uc
async def main():
browser = await uc.start()
tab = await browser.get('https://example.com/login')
# Find and fill email field
email = await tab.select('input[name="email"]')
await email.apply('(e) => e.value = "[email protected]"')
# Find and fill password field
password = await tab.select('input[type="password"]')
await password.apply('(e) => e.value = "secretpass"')
# Submit form
submit = await tab.find('Login')
await submit.click()
await tab.wait(3)
browser.stop()
uc.loop().run_until_complete(main())
import nodriver as uc
async def main():
browser = await uc.start()
tab = await browser.get('https://example.com')
# Get all article titles
articles = await tab.select_all('article')
for article in articles:
# Get title
title_elem = await article.query_selector('h2')
title = await title_elem.text() if title_elem else 'No title'
# Get link
link_elem = await article.query_selector('a')
link = link_elem.attrs.href if link_elem else 'No link'
print(f"Title: {title}")
print(f"Link: {link}")
print('---')
browser.stop()
uc.loop().run_until_complete(main())
Interact with dynamic elements
import nodriver as uc
async def main():
browser = await uc.start()
tab = await browser.get('https://example.com')
# Find button and scroll into view
button = await tab.find('Load More')
await button.scroll_into_view()
# Flash to highlight (useful for debugging)
await button.flash()
# Click the button
await button.click()
# Wait for new content
await tab.wait(2)
browser.stop()
uc.loop().run_until_complete(main())
See also