Element - Zendriver

Overview

The Element class represents an HTML DOM element. You typically obtain Element instances through Tab methods like select(), find(), or query_selector().

Creating elements

Elements are not created directly. Instead, they’re returned from Tab methods:

import zendriver as zd

browser = await zd.start()
tab = await browser.get("https://example.com")

# Get an element
element = await tab.select("button.submit")

Properties

tag

The HTML tag name in lowercase.

@property
def tag(self) -> str

tag_name

Alias for tag.

@property
def tag_name(self) -> str

node_id

The CDP node ID.

@property
def node_id(self) -> cdp.dom.NodeId

backend_node_id

The CDP backend node ID.

@property
def backend_node_id(self) -> cdp.dom.BackendNodeId

node_type

The node type (1 = element, 3 = text, etc.).

@property
def node_type(self) -> int

node_name

The node name in uppercase.

@property
def node_name(self) -> str

text

The text content of this element.

@property
def text(self) -> str

text_all

All text content including children.

@property
def text_all(self) -> str

attrs

Element attributes as a ContraDict.

@property
def attrs(self) -> ContraDict

parent

The parent element.

@property
def parent(self) -> Element | None

children

List of child elements.

@property
def children(self) -> list[Element]

tab

The parent Tab instance.

@property
def tab(self) -> Tab

Interaction methods

click()

Click the element.

async def click(self) -> None

mouse_click()

Native mouse click on the element.

async def mouse_click(
    self,
    button: str = "left",
    buttons: Optional[int] = 1,
    modifiers: Optional[int] = 0,
    hold: bool = False,
    _until_event: Optional[type] = None,
) -> None

button

str

default:"left"

Mouse button: "left", "right", or "middle".

buttons

int

default:"1"

Which button (1 = left, 2 = right, 4 = middle).

modifiers

int

default:"0"

Modifier keys (Alt=1, Ctrl=2, Meta=4, Shift=8).

hold

bool

default:"False"

Hold the mouse button down.

mouse_move()

Move the mouse to the element position.

async def mouse_move(self) -> None

mouse_drag()

Drag the element to a destination.

async def mouse_drag(
    self,
    destination: Union[Element, Tuple[int, int]],
    relative: bool = False,
    steps: int = 1,
) -> None

destination

Element | Tuple[int, int]

Target element or coordinates (x, y).

relative

bool

default:"False"

Treat coordinates as relative offsets.

steps

int

default:"1"

Number of intermediate points (higher = smoother).

send_keys()

Send text or key events to the element.

async def send_keys(
    self,
    text: Union[str, SpecialKeys, List[KeyEvents.Payload]]
) -> None

text

str | SpecialKeys | List

Text string, special key, or list of key events.

send_file()

Send file(s) to a file input element.

async def send_file(
    self,
    *file_paths: PathLike
) -> None

file_paths

PathLike

One or more file paths to upload.

focus()

Focus the element.

async def focus(self) -> None

clear_input()

Clear an input field by setting its value to empty string.

async def clear_input(self) -> None

clear_input_by_deleting()

Clear input by simulating delete key presses.

async def clear_input_by_deleting(self) -> None

select_option()

Select this option element (for <option> tags in <select>).

async def select_option(self) -> None

scroll_into_view()

Scroll the element into view.

async def scroll_into_view(self) -> None

Query methods

query_selector()

Find a descendant element by CSS selector.

async def query_selector(
    self,
    selector: str
) -> Element | None

selector

str

CSS selector.

element

Element | None

The found element, or None.

query_selector_all()

Find all descendant elements by CSS selector.

async def query_selector_all(
    self,
    selector: str
) -> list[Element]

selector

str

CSS selector.

elements

list[Element]

List of matching elements.

JavaScript methods

apply()

Apply a JavaScript function to the element.

async def apply(
    self,
    js_function: str,
    return_by_value: bool = True,
    *,
    await_promise: bool = False,
) -> Any

js_function

str

JavaScript function that accepts the element as a parameter.Examples:

"(elem) => elem.value = 'text'"
"elem => elem.play()"
"function myFunc(elem) { alert(elem) }"

return_by_value

bool

default:"True"

Return the value directly.

await_promise

bool

default:"False"

Wait for promises to resolve.

result

Any

The result of the JavaScript function.

get_js_attributes()

Get all JavaScript properties of the element.

async def get_js_attributes(self) -> ContraDict

attributes

ContraDict

Dictionary of element properties.

Attribute methods

get()

Get an attribute value by name.

def get(self, name: str) -> str | None

name

str

Attribute name (e.g., "href", "src", "class").

value

str | None

The attribute value, or None if not found.

set_value()

Set the node value.

async def set_value(self, value: str) -> None

value

str

The value to set.

set_text()

Set the text content.

async def set_text(self, value: str) -> None

value

str

The text to set.

get_html()

Get the outer HTML of the element.

async def get_html(self) -> str

html

str

The element’s HTML.

DOM manipulation

update()

Update the element to retrieve latest properties.

async def update(
    self,
    _node: cdp.dom.Node | None = None
) -> Element

element

Element

The updated element.

save_to_dom()

Save element changes to the DOM.

async def save_to_dom(self) -> None

remove_from_dom()

Remove the element from the DOM.

async def remove_from_dom(self) -> None

Position and visualization

get_position()

Get the element’s position on the page.

async def get_position(
    self,
    abs: bool = False
) -> Position | None

abs

bool

default:"False"

Return absolute position including scroll offset.

position

Position | None

Position object with x, y, width, height, center, or None if not visible.

flash()

Briefly display a red dot on the element.

async def flash(
    self,
    duration: Union[float, int] = 0.5
) -> None

duration

float

default:"0.5"

Duration in seconds.

highlight_overlay()

Highlight the element DevTools-style.

async def highlight_overlay(self) -> None

Call again to remove the highlight.

Screenshots

screenshot_b64()

Capture a screenshot of this element as base64.

async def screenshot_b64(
    self,
    format: str = "jpeg",
    scale: Optional[Union[int, float]] = 1,
) -> str

format

str

default:"jpeg"

Image format: "jpeg" or "png".

scale

float

default:"1"

Scale factor (1 = original size, 2 = double, 0.5 = half).

data

str

Base64-encoded image data.

save_screenshot()

Save a screenshot of this element to a file.

async def save_screenshot(
    self,
    filename: Optional[PathLike] = "auto",
    format: str = "jpeg",
    scale: Optional[Union[int, float]] = 1,
) -> str

filename

PathLike

default:"auto"

Save path. If “auto”, generates from URL.

format

str

default:"jpeg"

Image format: "jpeg" or "png".

scale

float

default:"1"

Scale factor.

path

str

Path to saved screenshot.

Special features

record_video()

Record video from an HTML5 <video> element.

async def record_video(
    self,
    filename: Optional[str] = None,
    folder: Optional[str] = None,
    duration: Optional[Union[int, float]] = None,
) -> None

filename

str

Desired filename.

folder

str

Download folder path.

duration

float

Record for this many seconds then download.

Only works on HTML5 <video> elements. Recording stops and downloads when the video ends, pauses, or stops.

is_recording()

Check if a video element is currently recording.

async def is_recording(self) -> bool

recording

bool

True if recording.

Examples

Basic interaction

import zendriver as zd

browser = await zd.start()
tab = await browser.get("https://example.com")

# Find and click
button = await tab.select("button.submit")
await button.click()

# Get text
title = await tab.select("h1")
print(title.text)

# Get attribute
link = await tab.select("a.external")
href = link.get("href")
print(f"Link URL: {href}")

Form filling

# Fill text input
input_field = await tab.select("input[name='email']")
await input_field.clear_input()
await input_field.send_keys("[email protected]")

# Select dropdown option
select = await tab.select("select[name='country']")
options = await select.query_selector_all("option")
for option in options:
    if option.text == "United States":
        await option.select_option()
        break

# Upload file
file_input = await tab.select("input[type='file']")
await file_input.send_file("/path/to/document.pdf")

JavaScript execution

# Apply JavaScript to element
element = await tab.select("#my-element")
result = await element.apply("(elem) => elem.innerHTML")
print(result)

# Set property
await element.apply("(elem) => elem.style.backgroundColor = 'red'")

# Get all properties
props = await element.get_js_attributes()
print(props)

Position and visibility

element = await tab.select(".content")

# Get position
position = await element.get_position()
if position:
    print(f"Element at: {position.left}, {position.top}")
    print(f"Size: {position.width} x {position.height}")

# Scroll into view
await element.scroll_into_view()

# Flash element
await element.flash(duration=1.0)

Screenshots

element = await tab.select(".card")

# Save element screenshot
await element.save_screenshot("card.png", format="png")

# Get base64 screenshot at 2x scale
data = await element.screenshot_b64(scale=2.0)

Drag and drop

# Drag one element to another
draggable = await tab.select(".draggable")
target = await tab.select(".drop-zone")
await draggable.mouse_drag(target, steps=50)

# Drag relative position
await draggable.mouse_drag((100, 200), relative=True)

Working with children

parent = await tab.select("ul.menu")

# Get all children
for child in parent.children:
    print(f"Child: {child.tag} - {child.text}")

# Query within element
links = await parent.query_selector_all("a")
for link in links:
    print(link.get("href"))

Notes

Always use await with Element methods
Call await element.update() to refresh the element if the DOM changed
For text nodes (node_type == 3), access .parent to get the containing element
Screenshots only work for visible elements
Use get() method to access attributes safely

Tab - Parent Tab class
Browser - Browser instance
start() - Start a browser session

Core API

Input & Interaction

Advanced

​Overview

​Creating elements

​Properties

​tag

​tag_name

​node_id

​backend_node_id

​node_type

​node_name

​text

​text_all

​attrs

​parent

​children

​tab

​Interaction methods

​click()

​mouse_click()

​mouse_move()

​mouse_drag()

​send_keys()

​send_file()

​focus()

​clear_input()

​clear_input_by_deleting()

​select_option()

​scroll_into_view()

​Query methods

​query_selector()

​query_selector_all()

​JavaScript methods

​apply()

​get_js_attributes()

​Attribute methods

​get()

​set_value()

​set_text()

​get_html()

​DOM manipulation

​update()

​save_to_dom()

​remove_from_dom()

​Position and visualization

​get_position()

​flash()

​highlight_overlay()

​Screenshots

​screenshot_b64()

​save_screenshot()

​Special features

​record_video()

​is_recording()

​Examples

​Basic interaction

​Form filling

​JavaScript execution

​Position and visibility

​Screenshots

​Drag and drop

​Working with children

​Notes

​Related

Build docs developers (and LLMs) love

Overview

Creating elements

Properties

tag

tag_name

node_id

backend_node_id

node_type

node_name

text

text_all

attrs

parent

children

tab

Interaction methods

click()

mouse_click()

mouse_move()

mouse_drag()

send_keys()

send_file()

focus()

clear_input()

clear_input_by_deleting()

select_option()

scroll_into_view()

Query methods

query_selector()

query_selector_all()

JavaScript methods

apply()

get_js_attributes()

Attribute methods

get()

set_value()

set_text()

get_html()

DOM manipulation

update()

save_to_dom()

remove_from_dom()

Position and visualization

get_position()

flash()

highlight_overlay()

Screenshots

screenshot_b64()

save_screenshot()

Special features

record_video()

is_recording()

Examples

Basic interaction

Form filling

JavaScript execution

Position and visibility

Screenshots

Drag and drop

Working with children

Notes

Related