` element in the browser. `@JsModule` loads the connector file, and `@NpmPackage` declares the npm dependency. In `onAttach()`, the component calls the connector’s `init` function through `executeJs()`, which creates the slider on the element. Communication from client to server happens through DOM events, `CustomEvent`, captured by `@DomEvent`.
```
Java (server) ──executeJs──> Connector JS ──library API──> JS Library
Java (server) <──@DomEvent── Connector JS <──callbacks──── JS Library
```
##
The Connector Pattern
The connector is a small JavaScript file that bridges the Vaadin element and the library. It typically exports (or attaches to `window`) an object with these functions:
- **`init(element, …)`** — imports the library, creates an instance on the given DOM element, and wires up event listeners that dispatch custom events back to the element.
- **`update(element, …)`** or per-property setters — updates the library instance when server-side state changes.
- **`destroy(element)`** — tears down the library instance and removes event listeners.
Attaching the library instance to the element — for example, `element._slider` — keeps things self-contained and makes cleanup straightforward.
##
Sending Data to the Client
Use `executeJs()` to run arbitrary JavaScript with parameters:
```java
getElement().executeJs(
"window.MyConnector.setOptions(this, $0, $1)", min, max);
```
`$0`, `$1`, etc. are placeholders for the method arguments. Supported types include string, number, boolean, and `JsonValue`.
For functions defined directly on the element, you can also use `callJsFunction()`:
```java
getElement().callJsFunction("focus");
```
See [Calling JavaScript](https://vaadin.com/docs/latest/flow/component-internals/element-api/calling-javascript.md) for the full reference.
##
Receiving Data from the Client
Two approaches exist for sending data from client to server:
**DOM events** — dispatch a `CustomEvent` from JavaScript. The Java side picks it up with `@DomEvent` and `@EventData`:
```javascript
element.dispatchEvent(
new CustomEvent('value-changed', {
detail: { value: newValue }
})
);
```
```java
@DomEvent("value-changed")
public static class ValueChangeEvent extends ComponentEvent
{
private final double value;
public ValueChangeEvent(MyComponent source, boolean fromClient,
@EventData("event.detail.value") double value) {
super(source, fromClient);
this.value = value;
}
public double getValue() { return value; }
}
```
**`@ClientCallable`** — define a Java method the client can invoke directly:
```java
@ClientCallable
private void onSelectionChanged(String itemId) {
// Handle on the server
}
```
```javascript
element.$server.onSelectionChanged(selectedId);
```
DOM events are simpler for most cases. Use `@ClientCallable` when you need to send structured data or trigger server logic that does not map to an event. See [Remote Procedure Calls](https://vaadin.com/docs/latest/flow/component-internals/client-server-rpc.md) for the full reference.
## Pitfalls
**Initialize in `onAttach`, not in the constructor.** The DOM element doesn’t exist in the browser until the component is attached. Calling `executeJs()` in the constructor queues the call, but the element may not be ready for the library to use. Use `onAttach()` to ensure the element is in the DOM.
**Clean up in `onDetach`.** Many JavaScript libraries assign event listeners, timers, or resize observers. If you don’t destroy the instance when the component is removed, you get memory leaks. Always pair `init` with `destroy`.
**Guard against double initialization.** If a component is detached and reattached — for example, during navigation — `onAttach()` runs again. Check whether the library is already initialized before creating a new instance.
**Use `$0`, `$1` placeholders instead of string concatenation.** Never build JavaScript strings with user-provided values. The placeholder syntax in `executeJs()` handles escaping and type conversion for you.