> Markdown version of [Creating a Java API](https://vaadin.com/docs/next/flow/component-internals/web-components/java-api-for-a-web-component). Section index: [llms.txt](https://vaadin.com/docs/next/flow/llms.txt)

# Creating a Java API for a Web Component

For a step-by-step guide to wrapping a web component, see [Wrap a Web Component](https://vaadin.com/docs/next/building-apps/components/wrap-web-component.md). This page is a reference for the APIs involved.

There are several ways to interact with a Web Component from Java: set properties on the element to define how it should behave, listen to events to be notified when the user does something, call functions on the element to perform specific tasks, or add sub-elements to define child content.

## <a id="setting-reading-properties"></a>Setting & Reading Properties

Use `getElement().setProperty()` and `getElement().getProperty()` to read and write properties on the element. Use `PropertyDescriptor` and `PropertyDescriptors` to avoid repeating property names in getters and setters. Use `@Synchronize` to keep server-side property values in sync when they change on the client.

See [Component Properties](https://vaadin.com/docs/next/flow/component-internals/properties.md) for the full reference.

## <a id="synchronizing-the-value"></a>Synchronizing the Value

To make a value-based component work automatically as a field, it should implement the `HasValue` interface. See [Binding Data to Forms](https://vaadin.com/docs/next/flow/binding-data/components-binder.md) for more information on this.

The value needs to be synchronized automatically from the client to the server when the user changes it, as well as from the server to the client when it’s updated programmatically. Additionally, a value-change event should be fired on the server whenever the value changes.

Typically, when the `getValue()` method is based on a single-element property, the `AbstractSinglePropertyField` base class takes care of everything related to the value.

As an example, the following extends the `AbstractSinglePropertyField` base class:

```java
public class MwcSlider extends AbstractSinglePropertyField<MwcSlider, Integer> {

    public MwcSlider() {
        super("value", 0, false);
    }

}
```

The type parameters define the component type (`MwcSlider`) returned by the `getSource()` method in value change events, and the value type (`Integer`). The constructor parameters define the name of the element property that contains the value (`"value"`), the default value to use if the property isn’t set (`0`), and it determines whether `setValue(null)` should be allowed or throw an exception (i.e., `false` means that `null` isn’t allowed).

For more advanced cases that are still based on a one-element property, there is an alternative constructor that defines callbacks that convert between the low-level element property type and the high-level `getValue()` type. In cases where the value can’t be derived based on a single-element property, you can use the more generic `AbstractField` base class.

> **Note: Properties not related to the HasValue interface**
>
> For some Web Components, you need to update other properties that aren’t related to the `HasValue` interface. See [Component Properties](https://vaadin.com/docs/next/flow/component-internals/properties.md) for how to use the `@Synchronize` annotation to synchronize property values without automatically firing a value-change event.

## <a id="listening-to-events"></a>Listening to Events

Use the `@DomEvent` annotation to connect a server-side `ComponentEvent` to a client-side DOM event. Use `@EventData` to extract data from the DOM event object. Define an `addXxxListener()` method that calls `addListener()` to let callers register listeners.

See [Events](https://vaadin.com/docs/next/flow/component-internals/events.md) for the full reference, including event data expressions, filtering, and debouncing.

## <a id="calling-element-functions"></a>Calling Element Functions

Use `getElement().callJsFunction()` to invoke JavaScript methods on the element. Supported parameter types are `String`, `Boolean`, `Integer`, `Double`, the corresponding primitive types, `JsonValue`, and `Element` and `Component` references. The method returns a server-side promise for the return value.

See [Remote Procedure Calls](https://vaadin.com/docs/next/flow/component-internals/client-server-rpc.md) for the full reference.

## <a id="adding-child-content"></a>Adding Child Content

If the component accepts child elements, implement `HasComponents` for a standard `add`/`remove` API. For more control, use `getElement().appendChild()` directly.

See [Component Containers](https://vaadin.com/docs/next/flow/component-internals/container.md) for the full reference.

`AACDBA11-3ECD-4E3B-9A36-C64E3963C26C`