Page Interactions

Fresh Source: docs.airtop.ai

Interact with web pages using natural language element descriptions instead of CSS selectors or XPath. Airtop's AI identifies the correct element visually and structurally.

click

Click any element by describing it.

TypeScript

// Click a button
await client.windows.click(sessionId, windowId, {
  elementDescription: 'the blue Sign In button',
});

// Click a link
await client.windows.click(sessionId, windowId, {
  elementDescription: 'the "Pricing" link in the navigation bar',
});

// Click a checkbox
await client.windows.click(sessionId, windowId, {
  elementDescription: 'the checkbox next to "I agree to the terms"',
});

Python

# Click a button
client.windows.click(session_id, window_id,
    element_description="the blue Sign In button"
)

# Click a link
client.windows.click(session_id, window_id,
    element_description='the "Pricing" link in the navigation bar'
)

# Click a checkbox
client.windows.click(session_id, window_id,
    element_description='the checkbox next to "I agree to the terms"'
)

type

Type text into any input field by describing it.

TypeScript

// Type in a search box
await client.windows.type(sessionId, windowId, {
  elementDescription: 'the search input field',
  text: 'cloud browser automation',
});

// Type in a specific form field
await client.windows.type(sessionId, windowId, {
  elementDescription: 'the email address input in the registration form',
  text: 'user@example.com',
});

Python

# Type in a search box
client.windows.type(session_id, window_id,
    element_description="the search input field",
    text="cloud browser automation"
)

# Type in a specific form field
client.windows.type(session_id, window_id,
    element_description="the email address input in the registration form",
    text="user@example.com"
)

hover

Hover over an element to reveal tooltips, dropdowns, or hidden content.

TypeScript

await client.windows.hover(sessionId, windowId, {
  elementDescription: 'the "Products" dropdown menu in the header',
});

Python

client.windows.hover(session_id, window_id,
    element_description='the "Products" dropdown menu in the header'
)

scroll

Scroll the page in a specific direction.

TypeScript

// Scroll down
await client.windows.scroll(sessionId, windowId, {
  direction: 'down',
  amount: 500,
});

// Scroll up
await client.windows.scroll(sessionId, windowId, {
  direction: 'up',
  amount: 300,
});

Python

# Scroll down
client.windows.scroll(session_id, window_id,
    direction="down", amount=500
)

# Scroll up
client.windows.scroll(session_id, window_id,
    direction="up", amount=300
)

Writing Good Element Descriptions

Effective Descriptions

Description	Why It Works
"the blue Submit button at the bottom of the form"	Color + text + location
"the email input field labeled 'Work Email'"	Field type + label text
"the third item in the product list"	Position reference
"the dropdown menu with 'Select Country' placeholder"	Element type + placeholder

Avoid

Description	Problem
"the button"	Which button? Too vague
"#submit-btn"	CSS selector, not natural language
"input[type=email]"	CSS selector, not natural language

Chaining Interactions

Combine interactions for multi-step workflows.

TypeScript

// Login flow
await client.windows.type(sessionId, windowId, {
  elementDescription: 'username or email input',
  text: 'user@example.com',
});
await client.windows.type(sessionId, windowId, {
  elementDescription: 'password input',
  text: 'my-password',
});
await client.windows.click(sessionId, windowId, {
  elementDescription: 'the Log In or Sign In button',
});

Python

# Login flow
client.windows.type(session_id, window_id,
    element_description="username or email input",
    text="user@example.com"
)
client.windows.type(session_id, window_id,
    element_description="password input",
    text="my-password"
)
client.windows.click(session_id, window_id,
    element_description="the Log In or Sign In button"
)

Best Practices

1. Be specific but natural — describe elements as you'd tell a human
2. Include context — "the search button next to the search input" vs "the button"
3. Use visible text — reference button labels, placeholder text, nearby labels
4. Add position cues — "at the top of the page", "in the sidebar", "below the header"
5. Wait between interactions — pages may need time to respond to clicks