Skip to content

Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.

Init

Magnus Müller1086a5634c5d
diff --git a/browser_use/browser/profile.py b/browser_use/browser/profile.py
index 4d76e8cce..1aa3652a8 100644
--- a/browser_use/browser/profile.py
+++ b/browser_use/browser/profile.py
@@ -631,6 +631,11 @@ class BrowserProfile(BrowserConnectArgs, BrowserLaunchPersistentContextArgs, Bro
default=True, description='Only show element IDs in highlights if llm_representation is less than 10 characters.'
)
paint_order_filtering: bool = Field(default=True, description='Enable paint order filtering. Slightly experimental.')
+ interaction_highlight_color: str = Field(
+ default='rgba(255, 165, 0, 0.7)',
+ description='Color to use for highlighting elements during interactions (CSS color string).',
+ )
+ interaction_highlight_duration: float = Field(default=2.0, description='Duration in seconds to show interaction highlights.')
# --- Downloads ---
auto_download_pdfs: bool = Field(default=True, description='Automatically download PDFs when navigating to PDF viewer pages.')
diff --git a/browser_use/browser/session.py b/browser_use/browser/session.py
index cf7187cae..f1bf6f717 100644
--- a/browser_use/browser/session.py
+++ b/browser_use/browser/session.py
@@ -1860,6 +1860,75 @@ class BrowserSession(BaseModel):
except Exception as e:
self.logger.warning(f'Failed to remove highlights: {e}')
+ async def highlight_interaction_element(self, node: 'EnhancedDOMTreeNode') -> None:
+ """Temporarily highlight an element during interaction for user visibility.
+
+ This creates a visual highlight on the browser that shows the user which element
+ is being interacted with. The highlight automatically fades after the configured duration.
+
+ Args:
+ node: The DOM node to highlight with absolute_position coordinates
+ """
+ if not self.browser_profile.highlight_elements or not node.absolute_position:
+ return
+
+ try:
+ import asyncio
+ import json
+
+ cdp_session = await self.get_or_create_cdp_session()
+
+ rect = node.absolute_position
+ color = self.browser_profile.interaction_highlight_color
+ duration_ms = int(self.browser_profile.interaction_highlight_duration * 1000)
+
+ # Create a temporary highlight overlay using fixed positioning
+ script = f"""
+ (function() {{
+ const rect = {json.dumps({'x': rect.x, 'y': rect.y, 'width': rect.width, 'height': rect.height})};
+ const color = {json.dumps(color)};
+ const duration = {duration_ms};
+
+ // Create highlight element
+ const highlight = document.createElement('div');
+ highlight.setAttribute('data-browser-use-interaction-highlight', 'true');
+ highlight.style.cssText = `
+ position: fixed;
+ left: ${{rect.x}}px;
+ top: ${{rect.y}}px;
+ width: ${{rect.width}}px;
+ height: ${{rect.height}}px;
+ border: 3px solid ${{color}};
+ box-shadow: 0 0 10px ${{color}};
+ pointer-events: none;
+ z-index: 2147483647;
+ box-sizing: border-box;
+ transition: opacity 0.3s ease-out;
+ `;
+
+ document.body.appendChild(highlight);
+
+ // Auto-remove after duration
+ setTimeout(() => {{
+ highlight.style.opacity = '0';
+ setTimeout(() => highlight.remove(), 300);
+ }}, duration);
+
+ return {{ created: true }};
+ }})();
+ """
+
+ # Fire and forget - don't wait for completion
+ asyncio.create_task(
+ cdp_session.cdp_client.send.Runtime.evaluate(
+ params={'expression': script, 'returnByValue': True}, session_id=cdp_session.session_id
+ )
+ )
+
+ except Exception as e:
+ # Don't fail the action if highlighting fails
+ self.logger.debug(f'Failed to highlight interaction element: {e}')
+
async def add_highlights(self, selector_map: dict[int, 'EnhancedDOMTreeNode']) -> None:
"""Add visual highlights to the browser DOM for user visibility."""
if not self.browser_profile.dom_highlight_elements or not selector_map:
diff --git a/browser_use/tools/service.py b/browser_use/tools/service.py
index ee50764fb..ffaf38936 100644
--- a/browser_use/tools/service.py
+++ b/browser_use/tools/service.py
@@ -249,6 +249,9 @@ class Tools(Generic[Context]):
if node is None:
raise ValueError(f'Element index {params.index} not found in browser state')
+ # Highlight the element being clicked (async, non-blocking)
+ await browser_session.highlight_interaction_element(node)
+
event = browser_session.event_bus.dispatch(ClickElementEvent(node=node, while_holding_ctrl=params.ctrl or False))
await event
# Wait for handler to complete and get any exception or metadata
@@ -302,6 +305,9 @@ class Tools(Generic[Context]):
if node is None:
raise ValueError(f'Element index {params.index} not found in browser state')
+ # Highlight the element being typed into (async, non-blocking)
+ await browser_session.highlight_interaction_element(node)
+
# Dispatch type text event with node
try:
# Detect which sensitive key is being used
@@ -445,6 +451,10 @@ class Tools(Generic[Context]):
# Try to find a file input element near the selected element
file_input_node = find_file_input_near_element(node)
+ # Highlight the file input element if found
+ if file_input_node:
+ await browser_session.highlight_interaction_element(file_input_node)
+
# If not found near the selected element, fallback to finding the closest file input to current scroll position
if file_input_node is None:
logger.info(
@@ -478,6 +488,8 @@ class Tools(Generic[Context]):
if closest_file_input:
file_input_node = closest_file_input
logger.info(f'Found file input closest to scroll position (distance: {min_distance}px)')
+ # Highlight the fallback file input element
+ await browser_session.highlight_interaction_element(file_input_node)
else:
msg = 'No file upload element found on the page'
logger.error(msg)