Element

Interact with HTML elements on the page

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

tag · str

The HTML tag name in lowercase (e.g., ‘div’, ‘button’, ‘a’).

tag_name · str

Alias for tag.

node_id · int

Unique node identifier.

node_name · str

Node name (uppercase tag name).

node_type · int

Node type number (1 = element, 3 = text, etc.).

node_value · str

Value of the node (for text nodes).

local_name · str

Local name of the element.

Element Relationships

parent · Element | None

Parent element. Requires calling await element.update() first.

children · List[Element]

List of child elements. Requires calling await element.update() first.

parent_id · int

Node ID of the parent element.

child_node_count · int

Number of child nodes.

Attributes

attrs · ContraDict

Dictionary-like object containing all HTML attributes (href, src, class, id, etc.).

attributes · List[str]

Raw list of attribute names and values.

Special Properties

tab · Tab

Reference to the Tab this element belongs to.

tree · cdp.dom.Node

The DOM tree structure.

shadow_roots · List

Shadow root nodes attached to this element.

shadow_children · List[Element]

Children within shadow DOM.

frame_id · str

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.

async def click(self)

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
)

js_function · str · required

JavaScript function that receives the element as a parameter. Can be an arrow function or function declaration.

return_by_value · bool · default: "True"

Return the value directly instead of a remote object reference.

Example:

input_field = await tab.select('input[name="email"]')

# Set value
await input_field.apply('(elem) => elem.value = "[e-mail]"')

# Get value
value = await input_field.apply('(elem) => elem.value')
print(value)  # "[e-mail]"

# 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

Example:

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

abs · bool · default: "False"

Get absolute position on page instead of viewport-relative.

Returns: Position object with x, y, width, height coordinates.

Example:

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 · float · default: "0.5"

Duration in seconds to flash.

Example:

element = await tab.find('Important')
await element.flash()  # Highlight for debugging

scroll_into_view()

Scroll the element into view.

async def scroll_into_view(self)

Example:

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)

steps · int · default: "10"

Number of steps for smooth movement.

Example:

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.

relative · bool · default: "False"

Whether coordinates are relative to current position.

Example:

# 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)

Example:

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)

Example:

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

Example:

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

Example:

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

Example:

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

Fill and submit a form

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 = "[e-mail]"')
    
    # 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())

Extract data from elements

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

• Tab class - Methods for finding elements
• CDP Usage - Advanced element manipulation