> Markdown version of [Properties & Attributes](https://vaadin.com/docs/next/flow/component-internals/element-api/properties-attributes). Section index: [llms.txt](https://vaadin.com/docs/next/flow/llms.txt)
# Element Properties & Attributes
The Element API contains methods to update and query parts of an element. You can use the Element API to change property and attribute values for server-side elements.
## About Attributes
Attributes are used mainly for the initial configuration of elements.
Attribute values are always stored as strings.
Example 1. Setting attributes for the `nameField` element
`AttributeTest.java`
```java
Element nameField = ElementFactory.createInput();
nameField.setAttribute("id", "nameField");
nameField.setAttribute("placeholder", "John Doe");
nameField.setAttribute("autofocus", "");
```
Example 2. The same example as the previous one, expressed as HTML
```html
```
You can also retrieve and manipulate attributes after they have been set.
Example 3. Retrieving and changing attributes in the `nameField` element
`AttributeTest.java`
```java
// Retrieve values of "placeholder" and "autofocus"
assertEquals("John Doe", nameField.getAttribute("placeholder"));
assertTrue(nameField.hasAttribute("autofocus"));
// Remove the "autofocus" attribute
assertEquals(List.of("autofocus", "id", "placeholder"),
nameField.getAttributeNames().toList());
nameField.removeAttribute("autofocus");
assertEquals(List.of("id", "placeholder"),
nameField.getAttributeNames().toList());
```
## About Properties
Properties are used mainly to dynamically change the settings of an element after it has been initialized.
Any JavaScript value can be used as a property value in the browser.
You can use different variations of the `Element.setProperty()` method to set a property value as a `String`, `boolean`, `double`, or `Element.setPropertyJson()` to use `BaseJsonNode`.
Example 4. Setting a property value as a `double`
`PropertyTest.java`
```java
Element input = ElementFactory.createInput();
input.setProperty("value", 42.2);
```
Similarly, you can use different variations of the `Element.getProperty()` method to retrieve the value of a property as a `String`, `boolean`, `double` or `Element.getPropertyBean()` to get value deserialized to a bean.
If you retrieve the value of a property as a different type from that used to set it, JavaScript type coercion rules are used to convert the value. For example, a property set as a non-empty `String` results as `true` if fetched as a `boolean`.
### Setting JSON Properties
For complex property values such as objects or arrays, use the `Element.setPropertyJson()` method with Jackson’s `BaseJsonNode` types.
Example 5. Setting a JSON object as a property
`PropertyTest.java`
```java
ObjectNode options = JacksonUtils.createObjectNode();
options.put("pageSize", 20);
options.put("sortable", true);
element.setPropertyJson("options", options);
```
Example 6. Setting a JSON array as a property
`PropertyTest.java`
```java
ArrayNode items = JacksonUtils.createArrayNode();
items.add("Option 1");
items.add("Option 2");
items.add("Option 3");
element.setPropertyJson("items", items);
```
Example 7. Setting a Java bean or record as a property
`PropertyTest.java`
```java
MyConfig config = new MyConfig("default", 100);
element.setPropertyBean("config", config);
```
Example 8. Converting retrieved value types
`PropertyTest.java`
```java
// The "value" property is 42.2
assertEquals("42.2", input.getProperty("value"));
// true, since any non-empty string is true in JavaScript
assertTrue(input.getProperty("value", true));
// 42, string is parsed to a JS number and truncated to an int
assertEquals(42, input.getProperty("value", 0));
```
## Difference between Using Attributes and Properties
Be cautious when using attributes and properties:
- It’s often possible to use either an attribute or property with the same name for the same effect, and both work fine.
- However, in certain cases:
- only one or the other works, or
- the attribute is considered only when the element is initialized, and the property is effective after initialization.
You should always check the specific documentation for the element you are using to find out whether a feature should be configured using a property or an attribute.
## Using the `textContent` Property
You can set an element’s `textContent` property using the `Element.setText()` method. This removes all the children of the element and replaces them with a single text node with the given value.
The `ElementFactory` interface provides helpers that you can use to create an element with a given text content.
Example 9. Using the `createSpan()` and `createDiv()` helper methods with the `setText()` method
`TextContentTest.java`
```java
//
Hello world
Element element = ElementFactory.createDiv("Hello world");
assertEquals("
(the span is removed)
element.setText("Replacement text");
assertEquals("
Replacement text
", element.toString());
```
To retrieve the text of an element, you can use the:
- `Element.getText()` method to return the text in the element itself. Text in child elements is ignored.
- `Element.getTextRecursively()` method to return the text of the entire element tree, by recursively concatenating the text from all child elements.
Example 10. Using the `getText()` and `getTextRecursively()` methods
`TextContentTest.java`
```java
//
Welcome back
Element element = ElementFactory.createDiv("Welcome back ");
Element name = ElementFactory.createStrong("Rudolph Reindeer");
//
// Welcome back Rudolph Reindeer
//
element.appendChild(name);
assertEquals("Welcome back Rudolph Reindeer",
element.getTextRecursively());
assertEquals("Welcome back ", element.getText());
```
## Synchronizing Properties to the Server
By default, values updated in the browser aren’t sent to the server. To synchronize a property, use the `Element.addPropertyChangeListener()` method. The method takes three parameters:
1. the name of the property to synchronize;
2. the name of the DOM event that triggers the synchronization; and
3. a listener that is invoked when the property value changes.
After the property has been synchronized to the server, you can retrieve its value using the `getProperty()` method. If you don’t need to react to the property change directly when it occurs, you can use a NO-OP listener.
Example 11. Using a NO-OP listener to synchronize the `value` property of a text input element whenever the `change` event occurs
`UserInputExample.java`
```java
textInput.addPropertyChangeListener("value", "change", e -> {
});
```
> **Note:** As an alternative, you can use the `addEventData()` method to transfer the value from the input to the server. See [Listening to Element Events](https://vaadin.com/docs/next/flow/component-internals/element-api/event-listener.md) for more information.
Example 12. Retrieving User Input
This example demonstrates how to use the Element API to retrieve user input. The example adds a text input field that allows the user to enter their name.
1. Create a text input element:
`UserInputExample.java`
```java
Element textInput = ElementFactory.createInput();
textInput.setAttribute("placeholder", "Enter your name");
```
2. Transfer the value to the server by asking the client to update the server-side input element every time the value changes in the browser:
`UserInputExample.java`
```java
textInput.addPropertyChangeListener("value", "change", e -> {
});
```
3. Retrieve the synchronized properties using `Element.getProperty()`:
`UserInputExample.java`
```java
Element button = ElementFactory.createButton("Say Hello");
button.addEventListener("click", e -> {
String responseText = "Hello " + textInput.getProperty("value"); // (1)
Element response = ElementFactory.createDiv(responseText);
getElement().appendChild(response);
});
```
1. The `value` property is `null` if the property wasn’t previously set and the user hasn’t typed text into the field.
`867075C4-D3EB-4AE2-B369-51E678673A7A`