# `Playwright.JSHandle`
[🔗](https://github.com/ftes/playwright_ex/blob/v1.65.0-rc.3/lib/playwright/api/js_handle.ex#L7)

JSHandle represents an in-page JavaScript object. JSHandles can be created with the `Playwright.Page.evaluate_handle/4`
method.

```elixir
window_handle = Page.evaluate_handle!(page, "() => window")
# ...
```

JSHandle prevents the referenced JavaScript object being garbage collected unless the handle is exposed with
`Playwright.JSHandle.dispose/1`. JSHandles are auto-disposed when their origin frame gets navigated or the parent context
gets destroyed.

JSHandle instances can be used as an argument in `Playwright.Page.eval_on_selector/4`, `Playwright.Page.evaluate/4` and
`Playwright.Page.evaluate_handle/4` methods.

*Since Playwright 1.8.*

The examples alias the modules they use (`alias Playwright.{Locator, Page}`).

# `evaluate_handle_options`

```elixir
@type evaluate_handle_options() ::
  [{:expose_functions, boolean()}] | %{optional(:expose_functions) =&gt; boolean()}
```

Options of `evaluate_handle/4`, see its docs.

# `evaluate_options`

```elixir
@type evaluate_options() ::
  [{:expose_functions, boolean()}] | %{optional(:expose_functions) =&gt; boolean()}
```

Options of `evaluate/4`, see its docs.

# `t`

```elixir
@type t() ::
  %Playwright.JSHandle{
    conn: term(),
    guid: term(),
    initializer: term(),
    table: term(),
    type: term()
  }
  | %Playwright.ElementHandle{
      conn: term(),
      guid: term(),
      initializer: term(),
      table: term(),
      type: term()
    }
```

A `JSHandle` handle. Compare handles with `==`, their fields are internal.

# `as_element`

```elixir
@spec as_element(t()) :: nil | Playwright.ElementHandle.t()
```

Returns either `nil` or the object handle itself, if the object handle is an instance of [`ElementHandle`](`Playwright.ElementHandle`).

*Since Playwright 1.8.*

# `dispose`

```elixir
@spec dispose(t()) :: :ok | {:error, Playwright.error()}
```

The `Playwright.JSHandle.dispose/1` method stops referencing the element handle.

*Since Playwright 1.8.*

# `dispose!`

```elixir
@spec dispose!(t()) :: :ok
```

Like `dispose/1`, but returns the value and raises on error.

# `evaluate`

```elixir
@spec evaluate(t(), String.t(), term() | nil, evaluate_options()) ::
  {:ok, term()} | {:error, Playwright.error()}
```

Returns the return value of `expression`.

This method passes this handle as the first argument to `expression`.

If `expression` returns a `Promise`, then `Playwright.JSHandle.evaluate/4` would wait for the promise to resolve and return
its value.

**Usage**

```elixir
tweet_handle = Page.query_selector!(page, ".tweet .retweets")
assert JSHandle.evaluate!(tweet_handle, "node => node.innerText") == "10 retweets"
```

*Since Playwright 1.8.*

## Arguments

* `expression` - Function to be evaluated in the page context.
* `arg` - Optional argument to pass to `expression`.

## Options

* `:expose_functions` (`t:boolean/0`) - *Since Playwright 1.62.* When set to `true`, functions passed inside `arg` are exposed in the page and can be called from the page function. Calling one returns a `Promise` of its result. Under the hood, each function is exposed via `Playwright.Page.expose_function/3`, so it is technically accessible from all frames of the page. Exposed functions are cleared upon the top-level navigation. Defaults to `false`, in which case functions are not serializable and passing one fails.

# `evaluate!`

```elixir
@spec evaluate!(t(), String.t(), term() | nil, evaluate_options()) :: term()
```

Like `evaluate/4`, but returns the value and raises on error.

# `evaluate_handle`

```elixir
@spec evaluate_handle(t(), String.t(), term() | nil, evaluate_handle_options()) ::
  {:ok, t()} | {:error, Playwright.error()}
```

Returns the return value of `expression` as a [`JSHandle`](`Playwright.JSHandle`).

This method passes this handle as the first argument to `expression`.

The only difference between `Playwright.JSHandle.evaluate/4` and `Playwright.JSHandle.evaluate_handle/4` is that `Playwright.JSHandle.evaluate_handle/4` returns [`JSHandle`](`Playwright.JSHandle`).

If the function passed to the `Playwright.JSHandle.evaluate_handle/4` returns a `Promise`, then `Playwright.JSHandle.evaluate_handle/4` would wait
for the promise to resolve and return its value.

See `Playwright.Page.evaluate_handle/4` for more details.

*Since Playwright 1.8.*

## Arguments

* `expression` - Function to be evaluated in the page context.
* `arg` - Optional argument to pass to `expression`.

## Options

* `:expose_functions` (`t:boolean/0`) - *Since Playwright 1.62.* When set to `true`, functions passed inside `arg` are exposed in the page and can be called from the page function. Calling one returns a `Promise` of its result. Under the hood, each function is exposed via `Playwright.Page.expose_function/3`, so it is technically accessible from all frames of the page. Exposed functions are cleared upon the top-level navigation. Defaults to `false`, in which case functions are not serializable and passing one fails.

# `evaluate_handle!`

```elixir
@spec evaluate_handle!(t(), String.t(), term() | nil, evaluate_handle_options()) ::
  t()
```

Like `evaluate_handle/4`, but returns the value and raises on error.

# `get_properties`

```elixir
@spec get_properties(t()) :: {:ok, term()} | {:error, Playwright.error()}
```

The method returns a map with **own property names** as keys and JSHandle instances for the property values.

**Usage**

```elixir
handle = Page.evaluate_handle!(page, "() => ({ window, document })")
properties = JSHandle.get_properties!(handle)
window_handle = properties["window"]
document_handle = properties["document"]
JSHandle.dispose!(handle)
```

In Elixir, the result is a map of property name to handle; unlike JS's `Map`, it does not keep the property order.

*Since Playwright 1.8.*

# `get_properties!`

```elixir
@spec get_properties!(t()) :: term()
```

Like `get_properties/1`, but returns the value and raises on error.

# `get_property`

```elixir
@spec get_property(t(), String.t()) :: {:ok, t()} | {:error, Playwright.error()}
```

Fetches a single property from the referenced object.

*Since Playwright 1.8.*

## Arguments

* `property_name` - property to get

# `get_property!`

```elixir
@spec get_property!(t(), String.t()) :: t()
```

Like `get_property/2`, but returns the value and raises on error.

# `json_value`

```elixir
@spec json_value(t()) :: {:ok, term()} | {:error, Playwright.error()}
```

Returns a JSON representation of the object. If the object has a `toJSON` function, it **will not be called**.

> #### Note {: .info}
>
> The method will return an empty JSON object if the referenced object is not stringifiable. It will fail if the
> object has circular references.

*Since Playwright 1.8.*

# `json_value!`

```elixir
@spec json_value!(t()) :: term()
```

Like `json_value/1`, but returns the value and raises on error.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
