> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.airtop.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.airtop.ai/_mcp/server.

# Page Interactions

You can use Airtop's interaction methods to naturally control browser actions like clicking, typing, and hovering. These methods use AI to understand natural language descriptions of elements, eliminating the need for complex selectors or XPaths.

## Usage Examples

First, you'll need to create a session and window as shown in previous guides.

**`NodeJS`**

```typescript NodeJS
const session = await client.sessions.create();
const window = await client.windows.create(session.data.id, { url: "https://google.com/finance/" });
```

**`Python`**

```python Python
session = client.sessions.create()
window = client.windows.create(session.data.id, url="https://google.com/finance/")
```

### Clicking Elements

Use the `click` method to interact with clickable elements on the page:

**`NodeJS`**

```typescript NodeJS
const result = await client.windows.click(sessionId, windowId, {
  elementDescription: "The 'Compare Markets' button near the top left of the page"
});
```

**`Python`**

```python Python
result = client.windows.click(session_id, window_id, 
  element_description="The 'Compare Markets' button near the top left of the page"
)
```

Example descriptions you could use:

* "The blue Submit button at the bottom of the form"
* "The 'Read more' link in the article"
* "The shopping cart icon in the navigation bar"

> **Note**
>
> Many websites have dynamic pages that update their layout when some events are performed.
> It's a good practice to add a delay after interactions that trigger animations or loading states.
> Check [Handling Dynamic Content](#handling-dynamic-content) for more details.

#### Right Click + Double Click

If you want to perform a right click or a double click, you can do so by adding the `rightClick` or `doubleClick` parameter to the request.

**`NodeJS`**

```typescript NodeJS
const result = await client.windows.click(sessionId, windowId, {
  elementDescription: "The 'Compare Markets' button near the top left of the page",
  configuration: {
    clickType: "rightClick"
  }
});
```

**`Python`**

```python Python
result = client.windows.click(session_id, window_id, 
  element_description="The 'Compare Markets' button near the top left of the page", 
  configuration={
    "click_type": "rightClick"
  }
)
```

### Typing Text

Use the `type` method to input text into form fields:

**`NodeJS`**

```typescript NodeJS
const result = await client.windows.type(sessionId, windowId, {
  elementDescription: "The search input field at the top of the page",
  text: "What to search for",
  pressEnterKey: true // Optional: press Enter after typing
});
```

**`Python`**

```python Python
result = client.windows.type(session_id, window_id,
  element_description="The search input field at the top of the page",
  text="What to search for",
  press_enter_key=True  # Optional: press Enter after typing
)
```

### Hovering Over Elements

Use the `hover` method to trigger hover states on elements:

**`NodeJS`**

```typescript NodeJS
const result = await client.windows.hover(sessionId, windowId, {
  elementDescription: "The dropdown menu in the navigation bar"
});
```

**`Python`**

```python Python
result = client.windows.hover(session_id, window_id,
  element_description="The dropdown menu in the navigation bar"
)
```

## Best Practices

### Element Descriptions

When describing elements, be as specific as possible:

✅ Good descriptions:

* "The blue 'Submit' button at the bottom of the contact form"
* "The search input field in the top navigation bar"
* "The 'Products' dropdown menu in the main navigation"

❌ Avoid vague descriptions:

* "The button"
* "The input"
* "The menu"

### Handling Dynamic Content

It's common for interactions to trigger a page reload or navigation, in which case subsequent interactions might occur while the page is still loading. You can use the `waitForNavigation` parameter to wait for the page to load before performing further interactions.

Add a delay after interactions that trigger animations or loading states:

**`NodeJS`**

```typescript NodeJS
const result = await client.windows.click(sessionId, windowId, {
  elementDescription: "The 'Compare Markets' button near the top left of the page",
  waitForNavigation: true
});
```

**`Python`**

```python Python
result = client.windows.click(session_id, window_id, 
  element_description="The 'Compare Markets' button near the top left of the page",
  wait_for_navigation=True
)
```

If the interaction doesn't trigger a navigation, you can use a delay to wait for the page to change.

**`NodeJS`**

```typescript NodeJS
// Wait a few seconds
await new Promise((resolve) => setTimeout(resolve, 3000));
```

**`Python`**

```python Python
# Wait a few seconds
import time
time.sleep(3)
```

This could prevent errors in which the agent clicks on the wrong element due to dynamic content.

## Current Limitations

* Interactions must be performed sequentially
* Elements must be visible in the current viewport
* Complex multi-step interactions require separate commands
* Accuracy can decrease for larger viewport sizes. Keep your browser windows below 1080p (1920x1080) for best results.

## Common Use Cases

* Form automation
* Navigation testing
* UI interaction validation
* Interactive web scraping
* End-to-end testing
* Workflow automation

These interaction methods can be chained together to create complex user flows while maintaining readable and maintainable code.