> Markdown version of [Enabled State](https://vaadin.com/docs/v24/flow/create-ui/enabled-state). Section index: [llms.txt](https://vaadin.com/docs/v24/flow/llms.txt)

# Component Enabled State

Components that allow user interaction, such as `TextField` or `Button`, can have three different enabled states:

- **Enabled**: An enabled component allows the user to interact with it. This is the default state.

- **Explicitly disabled**: A component is explicitly disabled when `setEnabled(false)` is called directly on it. The user can’t interact with the component, and communication from the client to the server is blocked.

- **Implicitly disabled**: A component is implicitly disabled when it’s a child of an explicitly disabled container. The component behaves exactly like an explicitly disabled component, except that it’s automatically enabled again as soon as it detaches from the disabled container.

## <a id="explicitly-enabling-and-disabling-components"></a>Explicitly Enabling and Disabling Components

Any component that implements the `HasEnabled` interface can be explicitly enabled or disabled.

**Example**: Disabling a component using the `component.setEnabled()` method.

```java
TextField name = new TextField("Name");
name.setEnabled(false);
```

- This disables the `name` field:

  - users can’t interact with it, and

  - events from the client to the server are blocked.

- The server doesn’t handle status updates from the component, even if the component is changed manually on the browser, for example by a client-side script or via a developer console.

**Example**: Disabling all components in a container by using the same API:

```java
FormLayout form = new FormLayout();

TextField name = new TextField("Name");
TextField email = new TextField("E-mail");
Button submit = new Button("Submit");

form.add(name, email, submit);
// all children are implicitly disabled
form.setEnabled(false);
System.out.println(name.isEnabled()); // prints false
```

> **Note:** Server-side components mapped via `@Id` don’t inherit the template element hierarchy. As a consequence, disabling a mapped component doesn’t disable other mapped components whose elements are children of the disabled component’s element in the template. See [Mapped Components Limitations](https://vaadin.com/docs/v24/flow/create-ui/templates/limitations.md) for details.

> **Note:** LitTemplate doesn’t support the `disabled` attribute on `@Id` mapped components. See [Mapped Components Limitations](https://vaadin.com/docs/v24/flow/create-ui/templates/limitations.md) for details.

## <a id="implicitly-enabled-and-disabled-components"></a>Implicitly Enabled and Disabled Components

When an implicitly disabled component is detached from a disabled container, it’s automatically enabled again. Similarly, if an enabled component is attached to a disabled container, it’s automatically implicitly disabled.

**Examples**: Implicitly enabled and disabled components

```java
FormLayout form = new FormLayout();
form.setEnabled(false); // the entire form is disabled

TextField name = new TextField("Name");
// prints true, since it isn't attached yet
System.out.println(name.isEnabled());

Button submit = new Button("Submit");
// the submit button is explicitly disabled
submit.setEnabled(false);
System.out.println(submit.isEnabled()); // prints false

form.add(name, submit); // attaches children

System.out.println(name.isEnabled()); // prints false
System.out.println(submit.isEnabled()); // prints false

form.remove(name); // the name field gets detached
System.out.println(name.isEnabled()); // prints true

form.remove(submit); // the submit button gets detached

// prints false, since it was explicitly disabled
System.out.println(submit.isEnabled());
```

## <a id="overriding-default-disabled-behavior"></a>Overriding Default Disabled Behavior

By default, disabled components don’t allow user interaction from the client side. However, it’s sometimes necessary for complex (composite) components to remain partially functional, even in the disabled state. For example, you may want to fully enable a registration form only after a user selects a checkbox to accept a license agreement.

### <a id="enabling-property-changes"></a>Enabling Property Changes

You can override the default disabled behavior by enabling certain client-side Remote Procedure Calls (RPC) that would normally be blocked for disabled components.

The first way to do this is by providing the property that should be synchronized to the server in the `addPropertyChangeListener()` call.

**Example**: This Polymer template component controls its own enabled state via the checkbox. The checkbox is never disabled, and it enables and disables the component.

```java
@Tag("registration-form")
@JsModule("./src/registration-form.js")
public class RegistrationForm
        extends PolymerTemplate<TemplateModel>
        implements HasEnabled {

    @Id
    private TextField name;

    @Id
    private TextField email;

    @Id
    private Button submit;

    @Id
    private Element enable;

    public RegistrationForm() {
        enable.addPropertyChangeListener("checked", "checked-changed",
                this::handleEnabled);
        setEnabled(false);
    }

    private void handleEnabled(
            PropertyChangeEvent event) {
        setEnabled((Boolean) event.getValue());
    }

    @EventHandler
    private void register() {
        String userName = name.getValue();
        String userEmail = email.getValue();
        System.out.println("Register user with name='"
                + userName
                + "' and email='" + userEmail + "'");
    }
}
```

Here is its template file:

```javascript
class RegistrationForm extends PolymerElement {

  static get template() {
    return html`
      <vaadin-text-field id="name" value="{{name}}"></vaadin-text-field>
      <vaadin-text-field id="email" value="{{email}}"></vaadin-text-field>
      <vaadin-button id="submit" on-click="register">Register</vaadin-button>
      <vaadin-checkbox
        id="enable"
        label="Accept License Agreement"
      ></vaadin-checkbox>
    `;
  }

  static get is() {
    return 'registration-form';
  }
}

customElements.define(RegistrationForm.is, RegistrationForm);
```

- The checkbox is implicitly disabled if the template (which is its parent) is disabled. As a result, no RPC is allowed for the checkbox.

- The `addPropertyChangeListener()` method (with the extra "checked-changed" argument) is used to synchronize the `checked` property.

- The following RPC communications are blocked for the disabled element:

  - Property changes

  - DOM events

  - Event handler methods (annotated with `@EventHandler`). For example, the `register()` method is an event handler method that’s blocked when the component is disabled.

  - Client delegate methods (annotated with `@ClientCallable`)

As an alternative, you can use the `@Synchronize` annotation with the `DisabledUpdateMode.ALWAYS` argument value.

**Example**: Using the `@Synchronize` annotation for the property getter in your component.

```java
@Synchronize(property = "prop", value = "prop-changed",
             allowUpdates = DisabledUpdateMode.ALWAYS)
public String getProp() {
    return getElement().getProperty("prop");
}
```

### <a id="enabling-dom-events"></a>Enabling DOM Events

You can enable DOM events in two ways:

1. with an `addEventListener()` overload method in the `Element` API, or

2. with the `@DomEvent` annotation.

**Example**: Unblocking a DOM event for a disabled element using the `addEventListener()` overload method that accepts the `DisabledUpdateMode.ALWAYS` parameter.

```java
public Notification() {
    getElement().addEventListener("opened-changed",
            event -> System.out.println("Opened"))
      .setDisabledUpdateMode(DisabledUpdateMode.ALWAYS);
}
```

**Example**: Unblocking a DOM event for a disabled component using the `@DomEvent` annotation with the parameter value `allowUpdates = DisabledUpdateMode.ALWAYS`:

```java
@DomEvent(value = "click",
          allowUpdates = DisabledUpdateMode.ALWAYS)
public class CustomEvent
        extends ComponentEvent<Component> {
}
```

### <a id="enabling-server-handler-methods"></a>Enabling Server-Handler Methods

If there are server-handler methods annotated with `@ClientCallable` or `@EventHandler`, you can unblock them for disabled components by specifying `DisabledUpdateMode.ALWAYS` as a value.

**Example**: Specifying `DisabledUpdateMode.ALWAYS`

```java
@EventHandler(DisabledUpdateMode.ALWAYS)
private void eventHandler() {
}

@ClientCallable(DisabledUpdateMode.ALWAYS)
private void clientRequest() {
}
```

`02D183A6-D516-4232-B4BE-851D50B73DBA`