> Markdown version of [Calling JavaScript](https://vaadin.com/docs/latest/flow/component-internals/element-api/calling-javascript). Section index: [llms.txt](https://vaadin.com/docs/latest/flow/llms.txt)

# Calling JavaScript from the Server

The Element API contains methods for executing JavaScript in the browser from the server side.

## <a id="calljsfunction-method"></a>`callJsFunction` Method

The `Element.callJsFunction()` method allows you to run a client-side component function from the server side. The method accepts two parameters: the name of the function to call; and the arguments to pass to the function.

The arguments passed to the function must be a type supported by the communication mechanism. The supported types are `String`, `Boolean`, `Integer`, `Double`, `JsonNode`, `Element`, `Component`, and `JsFunction` (see [Passing JavaScript Functions](#js-function)).

Example 1. Calling the `clearSelection()` JavaScript function on the root element from the server side

```java
public void clearSelection() {
    getElement().callJsFunction("clearSelection");
}
```

Example 2. Calling the `expand(otherComponentElement)` JavaScript function on the root element from the server side

```java
public void setExpanded(Component otherComponent) {
    getElement().callJsFunction("expand",
            otherComponent.getElement());
}
```

Example 3. Passing a JSON object to a JavaScript function

```java
public void configure(String label, int count) {
    ObjectNode config = JacksonUtils.createObjectNode();
    config.put("label", label);
    config.put("count", count);
    config.put("enabled", true);
    getElement().callJsFunction("configure", config);
}
```

## <a id="executejs-method"></a>`executeJs` Method

You can also use the generic `Element.executeJs()` method to run JavaScript asynchronously from the server side. This method can be used in addition to the `Element.callJsFunction()` method when calling any JavaScript.

The `executeJs()` method accepts two parameters: the JavaScript expression to invoke; and the parameters to pass to the expression. The given parameters are available as variables named `$0`, `$1`, and so on.

The arguments passed to the expression must be a type supported by the communication mechanism. The supported types are `String`, `Integer`, `Double`, `Boolean`, `JsonNode`, `Element`, `Component`, and `JsFunction` (see [Passing JavaScript Functions](#js-function)).

Example 4. Calling `MyModule.complete(true)` on the client side

```java
public void complete() {
    getElement().executeJs("MyModule.complete($0)", true);
}
```

Example 5. Passing a JSON array to a JavaScript expression

```java
public void setItems(List<String> items) {
    getElement().executeJs("this.items = $0", items);
}
```

> **Warning: Avoid Script Injection Vulnerabilities**
>
> Always pass arguments using the `$0`, `$1`, …​ notation to avoid script injection vulnerabilities. Never concatenate or interpolate strings to build JavaScript code to be executed.

If you need to run JavaScript without having access to an element, use the `UI.getCurrentOrThrow().getPage().executeJs()` method.

## <a id="return-values"></a>Return Values

The return value from the JavaScript function called using `callJsFunction()`, or the value from a `return` statement in an `executeJs()` expression can be accessed by adding a listener to the `PendingJavaScriptResult` instance returned from either method.

Example 6. Checking for support of Constructable Stylesheets in the browser

```java
public void checkConstructableStylesheets() {
    getElement().executeJs(
            "return 'adoptedStyleSheets' in document")
            .then(Boolean.class, supported -> {
                if (supported) {
                    System.out.println(
                            "Feature is supported");
                } else {
                    System.out.println(
                            "Feature isn't supported");
                }
            });
}
```

If the return value is a JavaScript `Promise`, the client only sends the return value to the server when the `Promise` is resolved.

### <a id="deserializing-generic-types-with-typereference"></a>Deserializing Generic Types with TypeReference

The `then()` method accepts a `Class` parameter for simple types, but this doesn’t work for generic types like `List<Person>` due to Java type erasure. For these cases, use the Jackson `TypeReference` overloads.

Example 7. Deserializing a JavaScript array into a `List<Person>`

```java
getElement().executeJs("return this.getItems()")
        .then(new TypeReference<List<Person>>() {},
                items -> {
                    // items is List<Person>
                    items.forEach(person ->
                            System.out.println(person.getName()));
                });
```

An error handler can be provided as a second callback. The handler receives the error message from the failed JavaScript execution as a `String`:

```java
getElement().executeJs("return this.getItems()")
        .then(new TypeReference<List<Person>>() {},
                items -> processItems(items),
                errorMessage -> handleError(errorMessage));
```

You can also use `toCompletableFuture(TypeReference)` to get the result as a `CompletableFuture`:

```java
CompletableFuture<Map<String, Person>> future = getElement()
        .executeJs("return this.getPersonMap()")
        .toCompletableFuture(
                new TypeReference<Map<String, Person>>() {});
```

## <a id="js-function"></a>Passing JavaScript Functions (since V25.2)

A `JsFunction` lets you build a reusable JavaScript function on the server and pass it as a parameter to `executeJs()` or `callJsFunction()`. The function arrives on the client as a real callable function with its captured values pre-bound, so you don’t need to concatenate JavaScript fragments to embed server-side values.

The first argument to `JsFunction.of()` is a JavaScript function body. The remaining arguments are captured values, referenced inside the body as `$0`, `$1`, … using the same naming convention as `executeJs()` parameters.

Example 8. Defining a function and invoking it

```java
JsFunction greet = JsFunction.of(
        "return $0 + ' ' + $1;", "Hello", "World");
getElement().executeJs(
        "this.textContent = $0();", greet);
```

Captures may be any value supported as an `executeJs()` parameter. An attached `Element` arrives as the corresponding DOM node; a detached `Element` arrives as `null`.

Example 9. Capturing an element

```java
Div target = new Div();
add(target);

JsFunction mutate = JsFunction.of(
        "$0.textContent = 'updated';",
        target.getElement());
getElement().executeJs("$0();", mutate);
```

### <a id="declaring-runtime-arguments"></a>Declaring Runtime Arguments

Use `withArguments()` to declare named parameters that the function accepts at call time. The body references them by name, and the JavaScript that invokes the function passes them positionally:

Example 10. A function with runtime arguments

```java
JsFunction format = JsFunction
        .of("return prefix + ':' + suffix;")
        .withArguments("prefix", "suffix");
getElement().executeJs(
        "this.textContent = $0('alpha', 'beta');", format);
```

### <a id="controlling-this"></a>Controlling `this`

In JavaScript, the value of `this` inside a function depends on how the function is invoked, not where it is defined. The body of a `JsFunction` follows this convention – `this` is not bound to the host element automatically.

When the function is invoked as `$0(…​)` from inside an `executeJs()` expression, the body’s `this` is the global object (or `undefined` in strict mode), not the element on which `executeJs()` was called. To set `this` explicitly, invoke the function with `Function.prototype.call()`: its first argument becomes `this` inside the body.

Example 11. Calling the function with a specific `this`

```java
JsFunction setOwnText = JsFunction
        .of("this.textContent = msg;")
        .withArguments("msg");
getElement().executeJs(
        "$0.call(this, 'host element text');", setOwnText);
```

If the body always needs to reference the same element regardless of how the function is called, pass it as a capture instead of relying on `this`.

## <a id="add-js-initializer"></a>Client-Side Lifecycle With `addJsInitializer` (since V25.2)

The `Element.addJsInitializer()` method registers a JavaScript expression that runs each time a client-side DOM node is created for the element, and whose returned cleanup callback runs when that DOM node is discarded or the returned `Registration` is removed.

Use this when you need to install something on the client-side DOM – an event listener, a third-party widget, an observer – and reliably tear it down. A one-shot `executeJs()` call doesn’t cover two cases: a real re-attach gives the element a brand-new DOM node that no longer has your listener, and cleanup from a server-side detach listener cannot be delivered because the element is leaving the tree.

The expression syntax is the same as `executeJs()`: `this` is the host element on the client, and parameters are referenced as `$0`, `$1`, …. If the expression returns a function, that function is invoked at teardown.

Example 12. Installing a listener with cleanup

```java
Registration registration = getElement().addJsInitializer("""
        const handler = (event) => console.log($1, event.target);
        this.addEventListener($0, handler);
        return () => this.removeEventListener($0, handler);
        """, "click", "clicked");
```

Here `$0` is `"click"` and `$1` is `"clicked"`, so the event type and the log label come from the server rather than being hard-coded in the expression.

Remove the registration on the server when the listener is no longer needed; the cleanup callback then runs on the client.

### <a id="re-attach-semantics"></a>Re-Attach Semantics

The initializer is re-run after a real re-attach – when the element is removed from the DOM in one round trip and re-added in a later one, and so the browser receives a fresh DOM node. It is **not** re-run when the element is detached and re-attached on the server inside a single round trip, because the client never discarded its DOM in that case.

### <a id="cleanup-constraints"></a>Cleanup Constraints

The return value of the expression is read synchronously. A function is treated as the cleanup callback; returning `null`, `undefined`, or nothing at all (no `return`) means there’s no cleanup. Returning any other value – including a `Promise` resolving to a function – is logged as an error on the client.

If setup is asynchronous, don’t return the `Promise`. Keep a reference to the pending work and return a cleanup function that awaits it before tearing down. Awaiting the same promise in the cleanup callback ensures the resource is torn down even if cleanup runs before the asynchronous setup has finished – otherwise a slow import could create the widget after cleanup has already run, leaking it:

```java
getElement().addJsInitializer("""
        const widgetPromise = import('./my-widget.js')
                .then((module) => module.create(this));
        return async () => (await widgetPromise).destroy();
        """);
```

`AB7EDF45-DB22-4560-AF27-FF1DC6944482`