> Markdown version of [Application Properties](https://vaadin.com/docs/next/flow/integrations/embedding/properties). Section index: [llms.txt](https://vaadin.com/docs/next/flow/llms.txt)

# Embedded Application Properties

This section covers how to define web component properties for embedded Vaadin applications. It also covers how to handle property changes on the server side, and how to fire custom events on the client side.

See [Creating an Embedded Application Tutorial](https://vaadin.com/docs/next/flow/integrations/embedding/exporter.md) for a detailed example of how to create an embedded Vaadin application.

## <a id="defining-web-component-properties"></a>Defining Web Component Properties

The `WebComponentExporter` class defines the properties that are exposed by the `WebComponent` public API.

Calling `WebComponentExporter.addProperty()` defines a property and adds it to the public API of the web component. The supported types are `Integer`, `Double`, `Boolean`, `String`, and `JsonValue`.

This example uses the `addProperty()` method to define web component properties:

```java
public class PersonExporter
        extends WebComponentExporter<PersonComponent> {
    private PropertyConfiguration<PersonComponent,
              Boolean> isAdultProperty;

    public PersonExporter() {
        super("person-display");
        addProperty("name", "John Doe")
                .onChange(PersonComponent::setName);
        addProperty("age", 0)
                .onChange(PersonComponent::setAge);

        isAdultProperty = addProperty("is-adult",
                false);
    }
```

This example defines three properties: `name`, `age`, and `is-adult`. The `is-adult` property is used in a later example in [Updating Properties on the Client Side](#updating-properties-on-the-client-side).

The `name` property type is a `String`, and the `age` property type is an `Integer`.

The default values serve a dual purpose: they define the property type and set the default value. If no default value is provided, you need to define the type explicitly by calling `definition.addProperty(String, Class<?extends Serializable>)`.

### <a id="property-event-attributes"></a>Property Event Attributes

Adding a property exposes a fluent API that you can use to configure the property. Properties have two event attributes:

`.onChange()`: It registers a callback that’s called when the value of the property changes on the client side; and accepts the parameter, `SerializableBiConsumer<C, P>`, where `C` is the type of the `Component` being exported and `P` is the type of the property. The component’s associated setter method is a conventional choice.

`.readOnly()`: It sets the property to read-only mode; the value of the property can’t be changed on the client side.

<!-- vale Vaadin.HeadingCase = NO -->

### <a id="addproperty-method-return-type"></a>addProperty() Method Return Type

<!-- vale Vaadin.HeadingCase = YES -->

The `addProperty()` method returns a `PropertyConfiguration<C, P>` object that provides the fluent API for configuring the property.

If you need to refer to the property later, you can use the received `PropertyDefinition` to identify the property in question.

## <a id="updating-properties-on-the-client-side"></a>Updating Properties on the Client Side

This section covers how the host environment (server) communicates with the client, and explain how to update client-side property values from the server.

To update client-side property values, you need a reference to the web component that contains the exported component, and a reference to the instance of the exported component itself.

You can implement the abstract `configureInstance()` method to update properties and [fire client-side events](#firing-custom-events-on-the-client-side).

The `configureInstance()` method receives references to `WebComponent<PersonComponent>` and `PersonComponent`, where `PersonComponent` is the exported component. `WebComponent` is used to communicate with the client side.

This example updates the `is-adult` boolean property when the `age` property changes in the `PersonComponent` instance.

```java
    @Override
    protected void configureInstance(
            WebComponent<PersonComponent> webComponent,
            PersonComponent component) {
        component.setAdultAge(18); // initialization

        component.addAgeChangedListener(event -> {
            webComponent.setProperty(isAdultProperty,
                    component.isAdult());
        });
```

The `WebComponent.setProperty()` method updates the property identified by the `PropertyConfiguration` to the new value.

> **Note:** The `configureInstance()` method can also be used to do further initialization on the `component` instance.

Now that the `is-adult` property is configured to update on the client side, the next step is to access and leverage this property.

The example below embeds the `person-display` component in a web page and updating `<span id='designator'>`:

```html
<person-display id="person" age=15></person-display>
<span id="designator">is a child</span>

<script>
    function updateDesignator() {
        var personComponent = document
                .querySelector("#person");
        if (personComponent["is-adult"]) {
            document.querySelector("#designator")
                    .innerText = "is an adult!";
        } else {
            setTimeout(updateDesignator, 1000);
        }
    }

    updateDesignator();
</script>
```

The script checks periodically whether the person has reached adulthood, and updates `<span id="designator">` when this occurs.

## <a id="firing-custom-events-on-the-client-side"></a>Firing Custom Events on the Client Side

A `WebComponent` instance can also be used to fire custom events on the client side. You can use the \[methodname]\`webComponent\`fireEvent()# method to fire events for given parameters.

Here’s an example using the ``webComponent`fireEvent()# method to fire the `"retirement-age-reached"`` event:

```java
        component.addAgeChangedListener(event -> {
            if (event.getAge() > 65) {
                webComponent.fireEvent(
                        "retirement-age-reached");
            }
        });
    }
}
```

This example uses custom logic and a custom event; if a person’s age reaches 66 or more, an event of type `"retirement-age-reached"` is fired on the client side.

The `fireEvent()` method has three variants:

- `fireEvent(String)`

- `fireEvent(String, JsonValue)`

- `fireEvent(String, JsonValue, EventOptions)`

The parameters are:

- `String`: the name or `type` of the event;

- `JsonValue`: a custom JSON object set as the value of the `detail` key in the client-side event; and

- `EventOptions`: to configure the `bubbles`, `cancelable`, and `composed` event options.

See [CustomEvent](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent) in the MDN documentation for more information about these parameters.

The final step is to update the `<span>` tag with the event results. This example is updating `<span id="designator">` with the `"retirement-age-reached"` event result:

```html
<person-display id="person" age=15></person-display>
<span id="designator">is a child</span>

<script>
    var personComponent = document
            .querySelector("#person");

    personComponent.addEventListener(
            "retirement-age-reached", function(event) {
        document.querySelector("#designator")
                .innerText = "is allowed to retire!";
    });
</script>
```

`B05162A1-925B-49C2-8550-E1FC8CDCC19D`