View Source Playwright.ElementHandle (playwright v1.44.0-alpha.4)

ElementHandle represents an in-page DOM element.

ElementHandles can be created with the Playwright.Page.query_selector/3 function, and similar.

⚠️ DISCOURAGED
The use of Playwright.ElementHandle is discouraged; use Playwright.Locator instances and web-first assertions instead.

Example

handle = Page.q(page, "a")
:ok = ElementHandle.click(handle)

ElementHandle prevents DOM elements from garbage collection unless the handle is disposed with Playwright.JSHandle.dispose/1. ElementHandles are auto-disposed when their origin frame is navigated.

An ElementHandle instance can be used as an argument in Playwright.Page.eval_on_selector/5 and Playwright.Page.evaluate/3.

NOTE

In most cases, you would want to use Playwright.Locator instead. You should only use ElementHandle if you want to retain a handle to a particular DOM node that you intend to pass into Playwright.Page.evaluate/3 as an argument.

The difference between Playwright.Locator and ElementHandle is that ElementHandle points to a particular element, while Playwright.Locator captures the logic of how to retrieve an element.

In the example below, handle points to a particular DOM element on the page. If that element changes text or is used by JavaScript to render an entirely different component, handle still points to that very DOM element. This can lead to unexpected behaviors.

handle = Page.q("text=Submit")
ElementHandle.hover(handle)
ElementHandle.click(handle)

With the Playwright.Locator, every time the locator is used, an up-to-date DOM element is located in the page using the selector. So, in the snippet below, the underlying DOM element is going to be located twice.

locator = Page.locator("text=Submit")
Locator.hover(locator)
Locator.click(locator)

Summary

Types

options()

A map/struct providing call options

t()

%Playwright.ElementHandle{}

Functions

bounding_box(handle)

click(handle, options \\ %{})

Clicks on the element, performing the following steps

content_frame(handle)

Returns the Playwright.Frame for element handles referencing iframe nodes, or nil otherwise.

evaluate(handle, expression, arg \\ nil)

See Playwright.JSHandle.evaluate/3.

evaluate_handle(handle, expression, arg \\ nil)

See Playwright.JSHandle.evaluate_handle/3.

get_attribute(handle, name)

Returns the value of an element's attribute.

init(owner, initializer)

Optional callback implementation for Playwright.SDK.ChannelOwner.init/2.

is_visible(handle)

q(handle, selector)

See Playwright.ElementHandle.query_selector/2.

query_selector(handle, selector)

Searches within an element for a DOM element matching the given selector.

screenshot(handle, options \\ %{})

scroll_into_view(handle, options \\ %{})

select_text(handle, options \\ %{})

string(handle)

See Playwright.JSHandle.string/1.

text_content(handle)

Returns the node.textContent (all text within the element).

Types

options()

@type options() :: map()

A map/struct providing call options

t()

@type t() :: %Playwright.ElementHandle{
  guid: term(),
  initializer: term(),
  listeners: term(),
  parent: term(),
  preview: term(),
  session: term(),
  type: term()
}

%Playwright.ElementHandle{}

Functions

bounding_box(handle)

@spec bounding_box(t()) :: map() | nil

click(handle, options \\ %{})

@spec click(t(), options()) :: :ok

Clicks on the element, performing the following steps:

Wait for "actionability (guide)" checks on the element, unless force: true option is set.
Scroll the element into view, if needed.
Use Playwright.Page.Mouse to click the center of the element, or the specified option: position.
Wait for initiated navigations to either succeed or fail, unless no_wait_after: true option is set.

If the element is detached from the DOM at any moment during the action, this function raises.

When all steps combined have not finished during the specified :timeout, this function raises a TimeoutError. Passing zero (0) for timeout disables this.

content_frame(handle)

@spec content_frame(t()) :: Playwright.Frame.t() | nil

Returns the Playwright.Frame for element handles referencing iframe nodes, or nil otherwise.

evaluate(handle, expression, arg \\ nil)

See Playwright.JSHandle.evaluate/3.

evaluate_handle(handle, expression, arg \\ nil)

See Playwright.JSHandle.evaluate_handle/3.

get_attribute(handle, name)

@spec get_attribute(t(), binary()) :: binary() | nil

Returns the value of an element's attribute.

init(owner, initializer)

@spec init(
  struct(),
  map()
) :: {atom(), struct()}

Optional callback implementation for Playwright.SDK.ChannelOwner.init/2.

If implemented, the callback will receive:

The newly created "channel owner" struct.
The :initializer received from the Playwright browser server.

The implementation has the option of "patching" the struct as stored in the catalog, and/or binding event handlers.

Example

def init(%{session: session} = owner, _initializer) do
  Channel.bind(session, {:guid, owner.guid}, :close, fn event ->
    Logger.warning("Closing #{inspect(event.target)}")
  end)

  {:ok, %{owner | version: "1.2.3"}}
end

Returns

{:ok, struct()}

Arguments

key/name	type		description
`owner`	param	`struct()`	The newly created channel owner (resource).
`initializer`	param	`struct()`	The initializer received from with the channel owner instance was derived.

is_visible(handle)

@spec is_visible(t()) :: boolean()

q(handle, selector)

See Playwright.ElementHandle.query_selector/2.

query_selector(handle, selector)

@spec query_selector(t(), binary()) :: t() | nil

Searches within an element for a DOM element matching the given selector.

Finds an element matching the specified selector within the subtree of the ElementHandle. See "working with selectors (guide)" for more details.

If no elements match the selector, returns nil.

screenshot(handle, options \\ %{})

@spec screenshot(t(), options()) :: binary()

scroll_into_view(handle, options \\ %{})

@spec scroll_into_view(t(), options()) :: :ok

select_text(handle, options \\ %{})

@spec select_text(t(), options()) :: :ok

string(handle)

See Playwright.JSHandle.string/1.

text_content(handle)

@spec text_content(t()) :: binary() | nil

Returns the node.textContent (all text within the element).