This is the full developer documentation for Wire Drupal. # Start of Wire documentation # Quickstart Get started with Wire Drupal quickly ## Install Wire Drupal Install the modules ```bash composer require wire-drupal/wire ``` Enable the module ```bash drush en wire ``` ## Create a component A new component can be generated with a Drush command ```bash drush generate wire ``` Assuming all needed prompts have been answered and the ID has been set as `counter`, the following two files are going to be generated: `../wiredemo/src/Plugin/WireComponent/Counter.php` ```php namespace Drupal\wiredemo\Plugin\WireComponent; use Drupal\wire\Plugin\Attribute\WireComponent; use Drupal\wire\WireComponentBase; use Drupal\wire\View; #[WireComponent(id: 'counter')] class Counter extends WireComponentBase { public function render(): ?View { return View::fromTpl('counter'); } } ``` `../wiredemo/templates/wire/counter.html.twig` ```html

``` A boiler plate twig file has been created so let's add some content ```html

Hello World!

``` > Worth noting that each Wire component must have a single root element. ## Include the component A Wire component can be included anywhere throughout your app with `wire()` Twig function ```twig ... {{ wire('counter') }} ... ``` It can also be included in any render-able array via `wire` render element. E.g: ```php namespace Drupal\wiredemo\Controller; use Drupal\Core\Controller\ControllerBase; class CounterController extends ControllerBase { public function content(): array { return [ '#type' => 'wire', '#id' => 'counter', ]; } } ``` Visit the page where Wire Component has been included in the browser and you should see "Hello World!". > **Note**: Ensure that the module in which the component has been generated is enabled ## Add "counter" functionality Replace generated content of the `counter` component class and template with the following `../wiredemo/src/Plugin/WireComponent/Counter.php` ```php namespace Drupal\wire\Plugin\WireComponent; use Drupal\wire\Plugin\Attribute\WireComponent; use Drupal\wire\WireComponentBase; use Drupal\wire\View; #[WireComponent(id: 'counter')] class Counter extends WireComponentBase { public int $count = 0; public function increment() { $this->count++; } public function render(): ?View { return View::fromTpl('counter'); } } ``` `../wiredemo/templates/wire/counter.html.twig` ```twig

``` ## View it in the browser Now reload the page in the browser, you should see the counter component rendered. If you click the "+" button, the page should automatically update without a page reload. > This is the most basic example to give you an idea of what is going on here. Check other Docs pages to see what Wire can do and what problems it can solve. ## Credits WireDrupal is inspired by [Livewire](https://livewire.laravel.com/) and uses [Alpine.js](https://alpinejs.dev/) to deliver DOM diffing and client-side functionality. It integrates these tools into the [Drupal](https://drupal.org) ecosystems, building on the foundational work of [Caleb Porzio](https://calebporzio.com/). # Essentials Learn the fundamental concepts of Wire including components, properties, actions, and events. Welcome to the Wire Drupal essentials section. Here you'll learn the fundamental concepts and building blocks of Wire components. ## What You'll Learn This section covers the core concepts you need to understand to work effectively with Wire: - **Installation** - Get Wire up and running in your Drupal project - **Making Components** - Create your first Wire components - **Rendering Components** - Display components in your templates - **Properties** - Manage component state and data - **Actions** - Handle user interactions and events - **Events** - Communicate between components - **Hooks** - Use lifecycle methods - **Nesting Components** - Build complex UIs with component composition ## Getting Started If you're new to Wire, we recommend starting with the [Installation](/docs/installation) guide and then working through each topic in order. Each guide builds on the concepts from the previous ones. ## Prerequisites Before diving into these guides, you should have: - A working Drupal installation - Basic knowledge of PHP and Drupal module development - Familiarity with HTML and JavaScript ## Installation Complete installation guide for Wire Drupal ## Requirements 1. PHP 8.1 or higher 2. Drupal ^10.2 3. Drush ^12 (optional) Visit the [composer.json](https://github.com/wire-drupal/wire/blob/main/composer.json) for the complete list of package requirements. ## Install Wire Drupal Install the module ```bash composer require wire-drupal/wire ``` Enable the module ```bash drush en wire ``` Wire doesn't need any other config at this point. ## Making Components Learn how to create Wire components ## Introduction Run the following Drush command to create a new Wire component > We'll assume you entered the Wire Label as "Articles" in a module with "wiredemo" machine name ```bash drush generate wire ``` > **Note:** Drush ^12 is required for the generate command to work Two new files were created in your chosen module: ``` ../wiredemo/src/Plugin/WireComponent/Articles.php ../wiredemo/templates/wire/articles.html.twig ``` ## Inline Components If you wish to create an Inline component (without `.twig` files), you can answer the "Inline" prompt as "Yes" and only the PHP class will be created: ``` ../wiredemo/src/Plugin/WireComponent/Articles.php ``` Here's what it would look like: ```php namespace Drupal\wiredemo\Plugin\WireComponent; use Drupal\wire\Plugin\Attribute\WireComponent; use Drupal\wire\WireComponentBase; use Drupal\wire\View; #[WireComponent(id: 'articles')] class Articles extends WireComponentBase { public function render(): ?View { $twig = <<<'TWIG'

TWIG; return View::fromString($twig); } } ``` ## Rendering Components How to render components in templates ## The Basics To render a Wire component on a page use the `wire()` Twig function: ```twig

... {{ wire('related_articles') }} ...

``` Or, if you're in the context of a renderable array (e.g. Form, Controller), you can use the `wire` render element: ```php $build['related_articles'] = [ '#type' => 'wire', '#id' => 'related_articles', ]; ``` > **Note**: Ensure that the module in which the component has been generated is enabled ## Parameters ### Passing Parameters You can pass data into a component by passing additional parameters into the `wire()` function. For example, let's say we have a "related_articles" component we want to include via Node's `node.html.twig` template. Here's how you would pass in the ID of the Node entity object: ```twig {{ wire('related_articles', {'nodeId': node.id}) }} ``` When using `wire` render element you would do: ```php $build['related_articles'] = [ '#type' => 'wire', '#id' => 'related_articles', '#context' => ['nodeId' => 999], ]; ``` ### Receiving Parameters Wire will automatically assign parameters to matching **public** properties. Make sure to read the [Properties](/docs/properties#important-notes) section to align your expectations. For example, in the case of `wire('related_nodes', {'nodeId': node.id})`, if the respective component has a public property named `$nodeId`, it will be automatically assigned and persist between Wire updates: ```php use Drupal\wire\Plugin\Attribute\WireComponent; use Drupal\wire\WireComponentBase; #[WireComponent(id: 'related_articles')] class RelatedArticles extends WireComponentBase { public ?int $nodeId; ... } ``` If for whatever reason, this automatic behavior doesn't work, you can intercept parameters using the `mount()` method: ```php use Drupal\node\Entity\Node; use Drupal\wire\Plugin\Attribute\WireComponent; use Drupal\wire\WireComponentBase; #[WireComponent(id: 'related_articles')] class RelatedArticles extends WireComponentBase { public ?int $nodeId; public string $label; public function mount($nodeId) { $this->label = 'Related articles for: ' . Node::load($nodeId)->label(); } } ``` The `mount()` method is only called when the component is first mounted and will NOT be called again when the component is refreshed or re-rendered. Think of it as a class `__construct()` method. At this point you might wonder if you can pass in the whole Node entity object. The answer is yes, but with a caveat. When you pass any unsupported [property](/docs/properties), it can be intercepted in the `mount()` method but it won't persist during Wire updates. ```twig {{ wire('related_articles', {'node': node}) }} ``` In the PHP class: ```php use Drupal\wire\Plugin\Attribute\WireComponent; use Drupal\wire\WireComponentBase; use Drupal\wire\View; #[WireComponent(id: 'related_articles')] class RelatedArticles extends WireComponentBase { protected ?Node $node; public string $label; public function mount(?Node $node) { $this->node = $node; } public function render(): ?View { // $this->node is available here but only on the initial load. } } ``` ## The Render Method A Wire component's `render` method gets called on the initial page load and every subsequent component update. ### Returning Template The `render()` method is expected to return an instance of `Drupal\wire\View` which has a few different ways to get its HTML. Here is an example using `View::fromTpl()`: > Make sure your Twig template only has ONE root element. ```php public function render(): ?View { return View::fromTpl('articles', [ 'articles' => Node::loadMultiple(), ]); } ``` `/wiredemo/templates/wire/articles.html.twig` ```twig

{% for article in articles %}

{% endfor %}

``` The `::fromTpl()` method expects the filename without its extension part, which must be located in a `templates/wire/` directory of a module or theme. The priority of loading the template is: active theme → parent/base theme(s) → module. ### Returning String If you don't want to use a Twig file at all, you can return a template string directly from `render()` method: ```php public function render(): ?View { $twig = <<<'TWIG'

{% for article in articles %}

{% endfor %}

TWIG; return View::fromString($twig); } ``` ### Returning anything Renderable You might want to render using Theme Implementations (`hook_theme`), [Render elements](https://www.drupal.org/docs/drupal-apis/render-api/render-elements), etc. This can be achieved with the [render_var](https://www.drupal.org/docs/theming-drupal/twig-in-drupal/functions-in-twig-templates#s-render-vararg) function. Example: ```php public function render(): ?View { $rendarableEl = [ '#type' => 'theme', '#theme' => 'my_theme_accepting_dynamic_value', '#my_dynamic_value' => $this->dynamicValue, ]; $twig = <<<'TWIG'

TWIG; return View::fromString($twig, [ 'my_dynamic_value' => $this->count, 'rendarableEl' => $rendarableEl, ]); } ``` ## Properties Working with component properties # Properties ## Introduction Wire components store and track data as public properties on the component class. ```php class HelloWorld extends WireComponentBase { public string $message = 'Hello World!'; public function render(): ?View { $twig = <<<'TWIG'

TWIG; return View::fromString($twig); } } ``` No need to explicitly pass them into the view although you can if you want or maybe you need to to modify it, in which case it will be: ```php ... return View::fromString($twig, ['message' => strtolower($this->message)]); ``` ### Important Notes Essential things to note about public properties: - Property names can't conflict with property names reserved for Wire (e.g. id) - Data stored in public properties is made visible to the front-end JavaScript. Therefore, you SHOULD NOT store sensitive data in them. - Properties can ONLY be either JavaScript-friendly data types (string, int, array, boolean), OR one of the following PHP types: Stringable, Collection, DateTime. > `protected` and `private` properties DO NOT persist between Wire updates. Generally, you should avoid using them for storing state. > Also, note that while `null` data type is JavaScript-friendly, public properties set to `null` DO NOT persist between Wire updates. ## Initializing Properties Properties can be initialized by using the `mount` method of the component. ```php class HelloWorld extends WireComponentBase { public string $message; public function mount() { $this->message = 'Hello World!'; } } ``` Additionally, a `$this->fill()` method is available for cases where you have to set lots of properties. ```php public function mount() { $this->fill(['message' => 'Hello World!']); } ``` Also, Wire offers `$this->reset()` and `$this->resetExcept()` to programmatically reset public property values to their initial state. This is useful for cleaning input fields after performing an action. ```php public function resetFilters() { // Reset the search property only. $this->reset('search'); // Reset both, search AND tags properties. $this->reset(['search', 'tags']); // Reset everything but the search property. $this->resetExcept('search'); } ``` ## Data Binding Wire can "bind" (or "synchronize") the current value of some HTML element with a specific property in your component. ```php class HelloWorld extends WireComponentBase { public string $message; } ``` ```twig

``` When a user types something into the text field, the value of the `$message` property will automatically update. Internally, Wire will listen for an `input` event on the element, and when triggered, it will send an AJAX request to re-render the component with the new data. > You can add `wire:model` to any element that dispatches an `input` event. Even custom elements, or third-party JavaScript libraries. Common elements to use `wire:model` on include: - `` - `` - `` - `

### Binding Nested Data

Wire supports binding to nested data inside arrays using dot notation:

```php
public array $formValues = [
  'name' => '',
  'email' => '',
];
```

```html
<div>
  <input type="text" wire:model="formValues.name">
  <input type="text" wire:model="formValues.email">
</div>
```

### Debouncing Input

By default, Wire applies a 150ms debounce to text inputs. This avoids too many network requests being sent as a user types into a text field.

If you wish to override this default (or add it to a non-text input), Wire offers a "debounce" modifier. If you want to apply a half-second debounce to an input, you would include the modifier like so:

```html
<input type="text" wire:model.debounce.500ms="name">
```

### Lazy Updating

By default, Wire sends a request to the server after every `input` event (or `change` in some cases). This is usually fine for things like `<select>` elements that don't typically fire rapid updates, however, this is often unnecessary for text fields that update as the user types.

In those cases, use the `lazy` directive modifier to listen for the native `change` event.

```html
<input type="text" wire:model.lazy="name">
```

Now, the `$name` property will only be updated when the user clicks away from the input field. This is useful for validating user inputs.

### Deferred Updating

In cases where you don't need data updates to happen live, Wire has a `.defer` modifier that batches data updates with the next network request.

Given the following component HTML

```html
<input type="text" wire:model.defer="name">
<button wire:click="search">Search</button>
```

As the user types into the `<input>` field, no network requests will be sent. Even if the user clicks away from the input field and onto other fields on the page, no requests will be sent.

When the user presses "Search", only one network request that contains both the new "name" state, and the "search" action to perform.

This can drastically cut down on network usage when it's not needed. In fact, most of the times you might want to use it this way.

## Wireable Properties

Sometimes you may want to have a component property which is not a data type supported by Wire.

For example, let's say we have a custom object in our app called `Settings`. Rather than just store settings data as a plain array in the component, we can attach associated behavior to this data with a convenient wrapper object or DTO like `Settings`:

```php
class Settings implements \Drupal\wire\Wireable {
  public array $items = [];
  
  public function __construct($items) {
    $this->items = $items;
  }
  
  public function toWire() {
    return $this->items;
  }
  
  public static function fromWire($value) {
    return new static($value);
  }
  
}
```

Now you can use this object as a public property of your component as long as that object implements the `\Drupal\wire\Wireable` interface AND the property is type-hinted like so:

```php
class HelloWorld extends WireComponentBase {

public Settings $settings;
  
  public function mount() {
    $this->settings = new Settings([
      'foo' => 'bar',
    ]);
  }
  
  public function changeSetting() {
    $this->settings->foo = 'baz';
  }
  
}
```

With this approach, changes to the component are persisted between requests.

## Actions

Component actions and methods

## Introduction

The goal of actions in Wire is to be able to easily listen to page interactions, and call a method on your Wire
component (re-rendering the component).

Assuming bellow component is initiated and `$nodeId` variable is being passed. Here's the basic usage:

```php
class ChangeNodeTitle extends WireComponentBase {
  public int $nodeId;
  
  public string $nodeLabel;
  
  public function mount() {
    $node = Node::load($this->nodeId);
    $this->nodeLabel = $node->label();
  }
 
  public function changeTitle() {
    $node = Node::load($this->nodeId);
    $node->title->value = substr(str_shuffle("abcdefghijklmnopqrstuvwxyz"), 0, 8);
    $node->save();
    $this->nodeLabel = $node->label();
  }
  
  public function render(): ?View {
    $twig = <<<'TWIG'
      <div>
        <h2>{{ nodeLabel }}</h2>
        <button wire:click="changeTitle">Change Node Title</button>
      </div>
    TWIG;
    
    return View::fromString($twig);
  }
}
```

Wire offers a handful of directives to make listening to browser events trivial. The common format for all of them is:
`wire:[dispatched browser event]="[action]"`.

Here are some common events you may need to listen for:

| Event   | Wire Directive |
|---------|----------------|
| click   | `wire:click`   |
| keydown | `wire:keydown` |
| submit  | `wire:submit`  |

Examples:

```html

<button wire:click="doSomething">Do Something</button>
```

```html
<input wire:keydown.enter="doSomething">
```

```html

<form wire:submit.prevent="save">
  ...
  <button>Save</button>
</form>
```

You can listen for any event dispatched by the element you are binding to.

Let's say you have an element that dispatches a browser event called "foo", you could listen for that event like so:
`<button wire:foo="doSomething">`

## Passing Action Parameters

You can pass extra parameters into a Wire action directly in the expression like so:

```html
<h2>{{ nodeLabel }}</h2>

<button wire:click="changeTitle('a string', '{{ random() }}')">
  Change Node Title
</button>
```

Extra parameters passed to an action, will be passed through to the component's method as standard PHP parameters:

```php
public function changeTitle($aString, $rand) {

$node = Node::load($this->nodeId);
  $node->title->value = "{$aString} {$rand}";
  $node->save();
  
}
```

## Event Modifiers

Like you saw in the **keydown** example, Wire directives sometimes offer "modifiers" to add extra functionality to an
event. Below are the available modifiers that can be used with any event.

| Modifier       | Description                                                                                                                                                                                                                      |
|----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| stop           | Equivalent of `event.stopPropagation()`                                                                                                                                                                                          |
| prevent        | Equivalent of `event.preventDefault()`                                                                                                                                                                                           |
| self           | Only triggers an action if the event was triggered on itself. This prevents outer elements from catching events that were triggered from a child element. (Like often in the case of registering a listener on a modal backdrop) |
| debounce.150ms | Adds X milliseconds before handling the action.                                                                                                                                                                                  |

### Keydown Modifiers

To listen for specific keys on **keydown** events, you can pass the name of the key as a modifier. You can directly use
any valid key names exposed
via [KeyboardEvent.key](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values) as modifiers by
converting them to kebab-case.

Here is a quick list of some common ones you may need:

| Key        | Modifier    |
|------------|-------------|
| Backspace  | backspace   |
| Escape     | escape      |
| Shift      | shift       |
| Tab        | tab         |
| ArrowRight | arrow-right |

E.g.:

```html

<input wire:keydown.arrow-down="foo">
```

## Magic Actions

"Magic" actions are prefixed with a "$" symbol

There are some "magic" actions that are usually prefixed with a "$" symbol:

| Function                      | Description                                                                                                                                               |
|-------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|
| $set('*property*', *value*)   | Shortcut to update the value of a property                                                                                                                |
| $toggle('*property*')         | Shortcut to toggle boolean properties on or off                                                                                                           |
| $emit('*event*', *...params*) | Will emit an event on the global event bus, with the provided params                                                                                      |
| $event                        | A *special* variable that holds the value of the event fired that triggered the action. Example usage: `wire:change="setMyProperty($event.target.value)"` |

You can pass these as the value of an event listener to do special things in Wire.

Examples:

- `$set()` can be used to manually set a component property's value.

Instead of

```html
  <button wire:click="setMessageToMyValue">My Value</button>
  ```

it can be done as

```html
  <button wire:click="$set('message', 'My Value')">My Value</button>
  ```

- `$event()` used to get the value of triggered element

```html
  <select wire:change="setMyMessage($event.target.value)">
    <option value="10">10</option>
    <option value="20">20</option>
    <option value="30">30</option>
  </select>
  ```

```php
  public function setMyMessage($value) {
    $this->message = $value;
  }
  ```

- `$emit()` is the bridge between firing events from JS and handling on back-end and vice-versa

See [Events](/docs/events) for more details.

## Events

Handling component events

Wire components can communicate with each other through a global event system. As long as two Wire components are living
on the same page, they can communicate using events and listeners.

## Firing Events

There are a few ways to fire events from Wire components.

### From The Template

```html

<button wire:click="$emit('nodeAdded')">
```

### From The Component

```php
$this->emit('nodeAdded');
```

### From Global JavaScript

```html

Wire.emit('nodeAdded')

</script>
```

## Event Listeners

Event listeners are registered in the $listeners property of components.

Listeners are a key -> value pair where the key is the event to listen for, and the value is the method to call on the
component.

```php
class ShowNodes extends WireComponentBase {

public int $nodeCount;
  
  protected $listeners = ['nodeAdded' => 'updateNodeCount'];
  
  public function updateNodeCount() {

$this->nodeCount = \Drupal::entityTypeManager()
      ->getStorage('node')
      ->getQuery()
      ->accessCheck(TRUE)
      ->count()
      ->execute();
    }
}
```

Now when any other component on the page emits a `nodeAdded` event, this component will pick it up and fire the
`updateNodeCount` method on itself.

> If the name of the event and the method you're calling match, you can leave out the key. For example:
`protected $listeners = ['nodeAdded'];` will call the `nodeAdded` method when the `nodeAdded` event is emitted.

If you need to name event listeners dynamically, you can substitute the `$listeners` property for the `getListeners()`
protected method on the component:

```php
class ShowNodes extends WireComponentBase {

public int $nodeCount;
  
  protected function getListeners() {
    return ['nodeAdded' => 'updateNodeCount'];
  }
  
}
```

> The `getListeners()` method will only dynamically generate the names of listeners when the component is mounted. Once
> the listeners are setup, these can't be changed.

## Passing Parameters

You can send parameters with an event emission.

```php
$this->emit('nodeAdded', $node->id());
```

```php
class ShowNodes extends WireComponentBase {

public int $nodeCount;

public int $latestAddedNodeId;

protected $listeners = ['nodeAdded' => 'incrementNodeCount'];

public function postAdded($nodeId) {

$this->latestAddedNodeId = $nodeId;

$this->nodeCount = \Drupal::entityTypeManager()
      ->getStorage('node')
      ->getQuery()
      ->accessCheck(TRUE)
      ->count()
      ->execute();
  }

}
```

## Scoping Events

### Scoping To Parent Listeners

When dealing with [nested components](/docs/nesting-components), sometimes you may only want to emit events to parents
and not children or sibling components.

In these cases, you can use the `emitUp` method.

```php
$this->emitUp('nodeAdded');
```

```html

<button wire:click="$emitUp('nodeAdded')">
```

### Scoping To Components By Name

You may only want to emit an event to other components of the same type(by name).

In these cases, you can use `emitTo`:

```php
$this->emitTo('counter', 'nodeAdded');
```

```html

<button wire:click="$emitTo('counter', 'nodeAdded')">
```

With above, if the button is clicked, the "nodeAdded" event will only be emitted to components with ID `counter`.

### Scoping To Self

You may only want to emit an event on the component that fired the event.

In these cases, you can use `emitSelf`:

```php
$this->emitSelf('nodeAdded');
```

```html

<button wire:click="$emitSelf('nodeAdded')">
```

With above implementation, if the button is clicked, the "nodeAdded" event will only be emitted to the instance of the
component that it was emitted from.

## Listening For Events In JavaScript

Wire allows you to register event listeners in JavaScript like so

```php
<script>

document.addEventListener("DOMContentLoaded", () => {
    
    Wire.on('nodeAddedNotify', nodeId => {
      alert('A new Node entity has been created with the id of: ' + nodeId);
    })
    
  });
  
</script>
```

## Dispatching Browser Events

Fire browser window events like so

```php
$this->dispatchBrowserEvent('node-added', ['newName' => $this->title]);
```

And listen for this window event with JavaScript

```javascript
window.addEventListener('node-added', event => {
  alert('A new Node entity has been created with the Title of: ' + event.detail.nodeTitle);
})
```

If you have [AlpineJS](https://alpinejs.dev/), it allows you to easily listen for these window events within your HTML.

E.g: Show a message when the Event is dispatched:

```html
<p
  x-data="{ open: false }"
  @node-added.window="open = true"
  x-show="open"
  style="display: none;"
>A new Node entity has been created</p>
```

## Hooks

Component lifecycle hooks

## Component Hooks

Whenever a Wire component is included on the page it undergoes a series of hooks which allow us to intervene at any time
during the component's lifecycle, or before specific properties are updated.

| Hooks          | Description                                                                                                                                                                                               |
|----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| boot           | Runs on every request, immediately after the component is instantiated, but before any other hooks are called                                                                                             |
| booted         | Runs on every request, after the component is mounted or hydrated, but before any update methods are called                                                                                               |
| mount          | Runs once, immediately after the component is instantiated, but before `render()` is called. This is only called once on initial page load and never called again, even on component refreshes            |
| hydrate        | Runs on every subsequent request, after the component is hydrated, but before an action is performed, or `render()` is called                                                                             |
| hydrateFoo     | Runs after a property called `$foo` is hydrated                                                                                                                                                           |
| dehydrate      | Runs on every subsequent request, before the component is dehydrated, but after `render()` is called                                                                                                      |
| dehydrateFoo   | Runs before a property called `$foo` is dehydrated                                                                                                                                                        |
| updating       | Runs before any update to the Wire component's data (Using `wire:model`, not directly inside PHP)                                                                                                         |
| updated        | Runs after any update to the Wire component's data (Using `wire:model`, not directly inside PHP)                                                                                                          |
| updatingFoo    | Runs before a property called `$foo` is updated. Array properties have an additional `$key` argument passed to this function to specify changing element inside array, like `updatingArray($value, $key)` |
| updatedFoo     | Runs after a property called `$foo` is updated. Array properties have additional `$key` argument as above                                                                                                 |
| updatingFooBar | Runs before updating a nested property `bar` on the `$foo` property or a multiword property such as `$fooBar` or `$foo_bar`                                                                               |
| updatedFooBar  | Runs after updating a nested property `bar` on the `$foo` property or a multiword property such as `$fooBar` or `$foo_bar`                                                                                |

> **Note!** Modifying a value of a property directly inside a Wire component class doesn't trigger any of the
> updating/updated hooks.

A hook can be implemented as following:

```php
class FooComponent extends WireComponentBase {

public string $foo;

public function boot() { }

public function booted() { }

public function mount() { }

public function hydrateFoo($value) { }

public function dehydrateFoo($value) { }
  
  public function hydrate() { }
  
  public function dehydrate() { }

public function updating($name, $value) { }

public function updated($name, $value) { }

public function updatingFoo($value) { }

public function updatedFoo($value) { }

public function updatingFooBar($value) { }

public function updatedFooBar($value) { }

}
```

## Javascript Hooks

Javascript can be executed during certain events.

| Hook                  | Description                                                                         |
|-----------------------|-------------------------------------------------------------------------------------|
| component.initialized | Component has been initialized on the page                                          |
| element.initialized   | When an individual element is initialized                                           |
| element.updating      | Before an element is updated during its DOM-diffing cycle after a network roundtrip |
| element.updated       | After an element is updated during its DOM-diffing cycle after a network roundtrip  |
| element.removed       | Called after Wire removes an element during its DOM-diffing cycle                   |
| message.sent          | Called when a Wire update triggers a message sent to the server via AJAX            |
| message.failed        | Called if the message send fails for some reason                                    |
| message.received      | Called when a message has finished its roudtrip, but before Wire updates the DOM    |
| message.processed     | Called after Wire processes all side effects (including DOM-diffing) from a message |

```html

document.addEventListener("DOMContentLoaded", () => {

Wire.hook('component.initialized', (component) => {})

Wire.hook('element.initialized', (el, component) => {})

Wire.hook('element.updating', (fromEl, toEl, component) => {})

Wire.hook('element.updated', (el, component) => {})

Wire.hook('element.removed', (el, component) => {})

Wire.hook('message.sent', (message, component) => {})

Wire.hook('message.failed', (message, component) => {})

Wire.hook('message.received', (message, component) => {})

Wire.hook('message.processed', (message, component) => {})

});

</script>
```

## Nesting Components

Creating component hierarchies

## Introduction

Component nesting is very powerful technique, but there are a few moments to be aware of:

- Nested components can accept parameters/values from their parents, however they're not reactive. In other words, if a
  state of a nested component changed, an update to other components has to me manually triggered via
  Wire [Events](/docs/events).
- Wire Components should not be used for extracting snippets into separate files(code/organizational). This is to avoid
  unneeded processing. A new theme element or SDC component would be the way to go.

Here is an example of a nested component called `add_node` from another Wire component's view.

```twig
<div>

{% for nodeTypeId, nodes in nodesByType %}
  
    <h2>{{ nodeTypes[nodeTypeId].label }}</h2>
    
    {% for node in nodes %}
    
      <h3>{{ node }}</h3>
      
    {% endfor %}
    
    <hr>
    
    {{ wire('add_node', {'type': nodeTypeId}) }}
    
  {% endfor %}
  
</div>
```

We're passing the `nodeTypeId` as `type` to our nested Wire components which is used as an unique identifier and should
be added as a value for `wire:key` attribute.

```twig
<div wire:key="{{ type }}">

<h2>Create a node of type {{ type }}</h2>
  
  <input type="text" wire:model.title.defer="title">
  
  <button wire:click="createNode">Create</button>
  
</div>
```

See [wire_demo_create_nodes](https://github.com/hugronaphor/wire_demo_create_nodes) repo for full example.

# Component Features

Explore advanced component features like file uploads, pagination, and data handling.

## Available Features

Wire provides several built-in features to handle common UI patterns:

- **File Uploads** - Handle file uploads with progress tracking and validation
- **Query String** - Sync component state with URL parameters
- **Pagination** - Implement efficient data pagination
- **Redirecting** - Navigate users programmatically

## When to Use These Features

These features are designed to solve specific problems you'll encounter when building interactive applications:

### File Uploads
Use when you need to:
- Accept file uploads from users
- Show upload progress
- Validate file types and sizes
- Handle multiple file uploads

### Query String
Use when you need to:
- Make component state shareable via URL
- Preserve filter/search state on page refresh
- Enable browser back/forward navigation

### Pagination
Use when you need to:
- Display large datasets efficiently
- Reduce initial page load time
- Provide navigation through data pages

### Redirecting
Use when you need to:
- Navigate after successful actions
- Implement conditional navigation
- Handle authentication flows

## File Uploads

Handle file uploads in components

## Basics

To upload a file with WireDrupal, add the `\Drupal\wire\WithFileUploads` trait to your component.

As with any other input field types, you can use `wire:model` on file inputs.

Here's an example of a component that handles uploading an image:

```php
use Drupal\wire\Plugin\Attribute\WireComponent;
use Drupal\wire\WireComponentBase;
use Drupal\wire\View;
use Drupal\wire\TemporaryUploadedFile;
use Drupal\wire\WithFileUploads;
use Drupal\file\Entity\File;

#[WireComponent(id: 'upload_image')]
class UploadImage extends WireComponentBase {

use WithFileUploads;
  
  public $image;
  
  public function saveImage(): void {
  
    $tempFile = $this->image ?? NULL;
    if (!$tempFile instanceof TemporaryUploadedFile) {
      return;
    }
    
    // Store file into temporary directory.
    if (!$filepath = $tempFile->store()) {
      return;
    }
    
    // Create File entity.
    try {
    
      $file = File::create([
        'filename' => basename($filepath),
        'uri' => $filepath,
        'status' => 1,
        'uid' => \Drupal::currentUser()->id(),
      ]);
      $file->save();
      
    } catch (\Exception $e) {
      watchdog_exception('wire_save_file', $e);
    }
    
  }
  
  public function render(): ?View {
    return View::fromTpl('upload_image');
  }
  
}
```

And the TWIG associated with above:

```html
<div>

<input
    wire:model="image"
    type="file"
    accept="image/*"
    id="image"
  >
  
  <button wire:click="saveImage">Save Image</button>
  
</div>
```

When an image is chosen, the `wire:model` directive will store the file in your temporary directory while triggering `saveImage` action will attempt to create a Drupal `\Drupal\file\Entity\File` instance.

## File Upload Preview

It is possible to preview the file before it is being saved to Drupal's File System(from Temp directory).

To achieve this, the `temporaryUrl` method is available as part of Wire's `TemporaryUploadedFile` object which will retrieve the path to the temporarily stored file.

However, due to `TwigSandboxPolicy`, in order to use the method you need to register the method as allowed in your `settings.php` file as following:

```php
$settings['twig_sandbox_allowed_classes'] = [
  '\Drupal\wire\TemporaryUploadedFile',
];
```

After witch you can use the method as following:

```twig
<div>

<input
    wire:model="image"
    type="file"
    accept="image/*"
    id="image"
  >
  
  {% if image %}
  
    <img src="{{ image.temporaryUrl() }}" style="width: 100px">
    
  {% endif %}
  
  <button wire:click="saveImage">Save Image</button>
  
</div>
```

## File Upload Remove

It is possible to remove the file from temporary directory.

To achieve this, add a new action into your template:

```twig
{% if image %}

<button wire:click="removeImage">Remove Image</button>

{% endif %}
```

And the called method itself:

```php
public function removeImage(): void {

$this->removeUpload('image', $this->image->getFilename());
    
}
```

## Multiple Files

Multiple file uploads are handled automatically by detecting the multiple attribute on the <input> tag. E.g:

```html
<input
  wire:model="image"
  type="file"
  accept="image/*"
  id="image"
  multiple
>
```

*Make sure your property is defined as array in the PHP component.

## Loading Indicators

You can display a loading indicator scoped to the file upload like so:

```html
<div wire:loading wire:target="image">Uploading...</div>
```

Now, while the file is uploading the "Uploading..." message will be shown and then hidden when the upload is finished.

This works with any other [Loading States API.](/docs/loading-states)

## JavaScript Events

On every file upload JavaScript events are dispatched on the `<input>` element for custom JavaScript to listen to.

Here are the dispatched events:

| Event | Description |
|-------|-------------|
| `wire-upload-start` | Dispatched when the upload starts |
| `wire-upload-finish` | Dispatches if the upload is successfully finished |
| `wire-upload-error` | Dispatches if the upload fails in some way |
| `wire-upload-progress` | Dispatches an event containing the upload progress percentage as the upload progresses |

Above are useful for showing for example the progress bar.

Here is an example implementation with AlpineJS:

```twig
<div
  x-data="{ isUploading: false, progress: 0 }"
  x-on:wire-upload-start="isUploading = true"
  x-on:wire-upload-finish="isUploading = false"
  x-on:wire-upload-error="isUploading = false"
  x-on:wire-upload-progress="progress = $event.detail.progress"
>

{# Progress Bar #}
  <div x-show="isUploading">

</div>

{% if image %}

<button wire:click="removeImage">Remove Image</button>

{% endif %}

<button wire:click="saveImage">Save Image</button>

</div>
```

## JavaScript upload API

To integrate with file-uploading libraries or have a more granular control over the behavior, Wire exposes dedicated JavaScript functions.

```js
  let file = document.querySelector('input[type="file"]').files[0];

// Upload a file.
  @this.upload('myFile', file, (uploadedFilename) => {
    // Success callback.
  }, () => {
    // Error callback.
  }, (event) => {
    // Progress callback.
  })

// Upload multiple files.
  @this.uploadMultiple('myFiles', [file], successCallback, errorCallback, progressCallback);

// Remove single file from multiple uploaded files.
  @this.removeUpload('myFiles', uploadedFilename, successCallback)
```

> ***Note***: the `@this` directive compiles to the following string for JavaScript to interpret: `Wire.find([component-id])`

See [A complete Drag and Drop file uploader with progressbar using Wire Drupal, Alpinejs and tailwindcss](https://cornel.co/article/drag-and-drop-file-uploader-progressbar-wire-drupal) for a complete example.

## Query String

URL query string handling

## Introduction

Updating the browser's query string when a component state change is supported and easy to implement.

E.g: When implementing an "Articles" component with a text input to search by keywords you would expect the URL to
change as `https://my-app.com/articles?search=mySearchString`

This way, when a user hits the back button, or bookmarks the page, you can get the initial state out of the query
string, rather than resetting the component every time.

To achieve this, you should add a property's name of your component to `protected $queryString`. The query string will
update every time the property value changes, and the property value will update when the query string changes.

```php
use Drupal\wire\Plugin\Attribute\WireComponent;
use Drupal\wire\WireComponentBase;
use Drupal\wire\View;
use Symfony\Component\DependencyInjection\ContainerInterface;
use Drupal\Core\Entity\EntityTypeManagerInterface;

#[WireComponent(id: 'articles')]
class Articles extends WireComponentBase {

public string $search = '';

protected array $queryString = ['search'];

protected ?EntityTypeManagerInterface $entityTypeManager;

public static function create(
    ContainerInterface $container,
    array              $configuration,
                       $plugin_id,
                       $plugin_definition
  ) {
    $instance = new static($configuration, $plugin_id, $plugin_definition);
    $instance->entityTypeManager = $container->get('entity_type.manager');
    return $instance;
  }

public function render(): ?View {

$nodeStorage = $this->entityTypeManager->getStorage('node');
    $nodeQuery = $nodeStorage->getQuery()->accessCheck(TRUE);
    $nodeQuery->condition('type', 'article')
      ->condition('status', 1)
      ->condition('title', '%' . addcslashes($this->search, '\%_') . '%', 'LIKE');

$articleEntities = $nodeStorage->loadMultiple($nodeQuery->execute());

return View::fromTpl('articles', [
      'items' => array_map(function ($article) {
        return $article->label();
      }, $articleEntities),
    ]);
  }

}
```

```html

<div>

<h1>Articles</h1>

<ul>

{% for item in items %}

{% endfor %}

</ul>

</div>
```

## Clean Query String

In the case above, when the search property is empty, the query string will look as `?search=`

It is possible to only manipulate the query string if it is NOT the default value.

Use except keyword as shown bellow.

```php
class Articles extends WireComponentBase {

public string $dummy = '';
  
  public string $search = '';
  
  public int $page = 0;
  
  protected array $queryString = [
    'dummy',
    'search' => ['except' => ''],
    'page' => ['except' => 0],
  ];
  
  ...
```

Note additional example provided for pagination via `$page` public property which would be used to not track the first
page.

## Query String Aliases

It is possible to modify how properties are represented in the URL.

For example, if you want to shorten the URL, where the page property is represented as `p` and search as `s`, you can
use the `as` modifier to achieve that outcome.

```php
class Articles extends WireComponentBase {

public string $search = '';

public int $page = 1;

protected array $queryString = [
    'search' => ['except' => '', 'as' => 's'],
    'page' => ['except' => 1, 'as' => 'p'],
  ];
  
  ...
```

## Pagination

Implement pagination in components

WireDrupal offers the ability to paginate results within a component.

Unfortunately, Drupal's existing pagination implementation is not flexible enough to be extended but a helper trait
`\Drupal\wire\WithPagination` is available to help with the implementation.

## Paginating Data

Assuming you have a `articles` component, but you want to limit the results to 10 articles per page.

Here is an example of a simple prev/next pager implementation.

```php
use Drupal\wire\Plugin\Attribute\WireComponent;
use Drupal\wire\WireComponentBase;
use Drupal\wire\View;
use Drupal\wire\WithPagination;
use Symfony\Component\DependencyInjection\ContainerInterface;
use Drupal\Core\Entity\EntityTypeManagerInterface;

#[WireComponent(id: 'articles')]
class Articles extends WireComponentBase {

use WithPagination;

const ITEMS_PER_PAGE = 10;

public string $search = '';

protected string $pagerId = 'page';

protected array $queryString = [
    'search' => ['except' => '', 'as' => 's'],
    'page' => ['except' => 0, 'as' => 'p'],
  ];

protected ?EntityTypeManagerInterface $entityTypeManager;

public function render(): ?View {

$nodeStorage = $this->entityTypeManager->getStorage('node');
    $nodeQuery = $nodeStorage->getQuery()->accessCheck(TRUE);

$getBaseQuery = function () use ($nodeQuery) {
      $thisQuery = clone $nodeQuery;
      $query = $thisQuery
        ->condition('type', 'article')
        ->condition('status', 1);
      if (!empty($this->search)) {
        $query->condition('title', '%' . addcslashes($this->search, '\%_') . '%', 'LIKE');
      }
      return $query;
    };

$articleEntities = $nodeStorage->loadMultiple(
      $getBaseQuery()
        ->range(floor($this->page * self::ITEMS_PER_PAGE), self::ITEMS_PER_PAGE)
        ->execute()
    );

$totalPages = ceil($getBaseQuery()->count()->execute() / self::ITEMS_PER_PAGE);

return View::fromTpl('articles', [
      'items' => array_map(function ($article) {
        return $article->label();
      }, $articleEntities),
      'paginator' => $this->getPaginationData($totalPages),
    ]);
  }

private function getPaginationData($totalPages): ?array {
    $items = [];

if ($this->page > 0) {
      $items['previous']['hasItems'] = TRUE;
    }

if ($this->page < ($totalPages - 1)) {
      $items['next']['hasItems'] = TRUE;
    }

return ['items' => $items];
  }

}
```

```twig
<div>

<h1>Articles</h1>

<ul>

{% for item in items %}

{% endfor %}

</ul>

{% if paginator.items %}

{% if paginator.items.previous.hasItems %}
        <button
          wire:click="previousPage()"
          wire:loading.attr="disabled"
          type="button"
          title="{{ 'Go to previous page'|t }}"
        >
          {{ 'Prev'|t }}
        </button>
      {% endif %}

{% if paginator.items.next.hasItems %}
        <button
          wire:click="nextPage()"
          wire:loading.attr="disabled"
          type="button"
          title="{{ 'Go to next page'|t }}"
        >
          {{ 'Next'|t }}
        </button>
      {% endif %}
    </nav>

{% endif %}

</div>
```

* Note that the `$pagerId` property must be defined in order to identify the pager in case there are multiple ones on
  the same page.

* The `previousPage()` and `nextPage()` methods are provided by `WithPagination` trait which calls `setPage()` method.
  You should call this method if you're implementing a Full pagination to go to a specific page.

## Resetting Pagination

You might need to reset pagination to it's first page when performing any filtering of data as it would return a
different set of results.

E.g: If a user is on the page "2" and types into a search field to narrow the results you might want to reset the page
as first one to make sense of any pagination if any.

The `WithPagination` trait exposes a `resetPage()` method to accomplish this.

This method can be used in combination with the `updating/updated` lifecycle hooks to reset the page when certain
component data is updated.

```php
public function updatingSearch(): void {

$this->resetPage();
  
}
```

If you implemented the search when a specific action, add `$this->resetPage();` in the action method accordingly.

## Redirecting

Component-based redirects

You may want to redirect from inside a Wire component to another page.

E.g: After submitting some data, perform all needed operations like saving an entity or sending an email you might want
to redirect the user to a specific page.

To do this, two helper methods are available withing your Wire Component:

```php
// Redirects to given route.
$this->redirectRoute('<front>');
// Redirects to given path.
$this->redirect('/completed');
```

# UI Features

Advanced UI patterns including loading states, polling, and real-time updates.

Build responsive and interactive user interfaces with Wire's advanced UI features.

## Overview

Wire provides several features to create polished, professional user experiences:

- **Loading States** - Show feedback during server operations
- **Polling** - Keep data fresh with automatic updates
- **Offline State** - Handle network connectivity issues gracefully
- **Dirty States** - Track unsaved changes in forms
- **Defer Loading** - Optimize initial page load performance

## Creating Better User Experiences

These features work together to create applications that feel fast and responsive:

### Loading States
Provide immediate visual feedback when users interact with your components. Wire automatically manages loading states for all server requests.

### Polling
Keep your UI in sync with server data without manual refreshes. Perfect for dashboards, notifications, and real-time data displays.

### Offline State
Detect when users lose internet connectivity and provide appropriate feedback. Queue actions to be performed when connection is restored.

### Dirty States
Track when forms have unsaved changes and warn users before they navigate away. Improve data integrity and user confidence.

### Defer Loading
Load expensive content after the initial page render. Improve perceived performance by showing the page structure immediately.

## Best Practices

- Use loading states for any action that takes more than 200ms
- Implement polling intervals that balance freshness with server load
- Always provide offline feedback for critical user actions
- Use dirty states for any form that takes significant effort to fill out
- Defer load content that's below the fold or not immediately needed

## Loading States

Show loading indicators and states

## Introduction

When an user event takes a while to perform(long execution), Wire provides needed tools to display loading states, so the apps feel more responsive.

## Toggling elements during loading

The wire:loading directive make elements visible only while waiting for actions to complete.

```html
<div>

<button wire:click="submit">Submit</button>

Submitting...

</div>

</div>
```

When the "Submit" button is clicked, the "Submitting..." message will show. When the action is finished, the message will disappear.

By default, the loading element will get "display" CSS property set to "inline-block". To change this, use the following modifiers.

```html
<div wire:loading.block>...</div>

<div wire:loading.table>...</div>
```

You can also "hide" an element during a loading state using the `.remove` modifier.

```html
<div>

<button wire:click="submit">Submit</button>

Hidden while loading...

</div>

</div>
```

## Delaying loading indicator

To avoid flickering because loading is very fast, you can add the `.delay` modifier, and it will only show up if loading takes longer than `200ms`.

```html
<div wire:loading.delay> ... </div>
```

If you wish, you can customize the delay duration with the following modifiers:

```html
<div wire:loading.delay.shortest>...</div>

<div wire:loading.delay.longest>...</div>  
```

## Targeting specific actions

You can show loading indicators only for specific actions. For example, you might want to show a loading piece of content when `submit` action is performed but not `reset`. See bellow example.

```html
<div>

<button wire:click="submit">Submit</button>
  
  <button wire:click="reset">Reset</button>
  
  <div wire:loading wire:submit="checkout">
  
    Submitting...
    
  </div>
  
</div>
```

`wire:target` can accept multiple arguments in a comma separated format, e.g: `wire:target="submit, reset"`.

An actions with a specific parameters can also be targeted.

```html
<div>

<button wire:click="update('title')">Update Title</button>
  
  <div wire:loading wire:target="update('title')">

Updating Title...

</div>

</div>
```

Also, loading content can be triggered when ANY of the properties of an array change.

```html
<div>

Updating Node...

</div>

</div>
```

## Targeting models

Any `wire:model` can be targeted whenever it is synchronized.

```html
<div>

Updating quantity...

</div>

</div>
```

## Toggling classes

CSS classes can be added or removed from an element during loading states, by adding the `.class` modifier to the `wire:loading` directive.

```html
<div>

Submit

</button>

</div>
```

To remove classes, use the `.remove` modifier.

```html
<div>

<button
    wire:click="submit"
    wire:loading.class.remove="loading"
    class="loading"
  >Submit</button>

</div>
```

With above, the `loading` class will be removed from the button while loading.

## Toggling attributes

Similar to classes, HTML attributes can be added or removed from elements during loading states:

```html
<div>

Submit

</button>

</div>
```

With above, when the "Submit" button is clicked, the `disabled="true"` attribute will be added to the element while loading.

## Polling

Real-time data updates

## Introduction

WireDrupal offers a directive called `wire:poll` that, when added to an element, will refresh the component every `2s`.

Polling for changes over Ajax is a lightweight, simpler alternative to WebSocket strategy.

```html
<div wire:poll>

Current time: {{ date().timestamp }}
  
</div>
```

You can customize the frequency by passing a directive modifier like `750ms`. E.g:

```twig
<div wire:poll.500ms>

Current time: {{ date().timestamp }}
  
</div>
```

You can also specify a specific action to fire on the polling interval by passing a value to `wire:poll`:

```twig
<div wire:poll="doSomething">

Current time: {{ date().timestamp }}
  
</div>
```

With above, the `doSomething` method on the component will be called every 2 seconds.

## Polling in the background

WireDrupal reduces polling when the browser tab is in the background so that it doesn't bog down the server with ajax requests unnecessarily. Only about 5% of the expected polling requests are kept.

If you'd like to keep polling at the normal rate even while the tab is in the background, you can use the `keep-alive` modifier:

```twig
<div wire:poll.keep-alive>

Current time: {{ date().timestamp }}
  
</div>
```

## Polling only when element is visible

If your component isn't always visible in the browser's viewport (further down the page for example), you can opt to only poll the server when an element is visible by adding the `.visible` modifier to `wire:poll`. E.g:

```html
<div wire:poll.visible>

...

</div>
```

## Offline State

Handle offline scenarios

You might want to notify a user if their internet connection is lost.

WireDrupal provides helpful utilities to perform actions based on a user's "offline" state.

## Toggling elements

To show an element when the internet connection is lost (offline), use `wire:offline` attribute.

```html

You are offline.

</div>
```

With above, the element will be hidden by default, and shown to the user when the browser goes offline.

## Toggling classes

Adding the `class` modifier allows adding a class to an element when "offline".

```html

<div wire:offline.class="offline"></div>
```

With above, when the browser goes offline, the element will receive the `offline` class. The class will be removed again
once the user is back online.

To remove classes, use the `.remove` modifier.

```html

<div wire:offline.class.remove="offline" class="offline"></div>
```

With above, the `offline` class will be removed while offline.

## Toggling attributes

With the `attr` modifier, it is possible to add an attribute to an element when "offline".

```html

<button wire:offline.attr="disabled">Submit</button>
```

With above, when the browser goes offline, the `disabled="true"` attribute will be added to the button.

You can also perform the inverse, and remove attributes by adding the `.remove` modifier.

## Dirty States

Track form changes

Dirty States are helpful for providing feedback that content has changed and is not yet in-sync with the back-end Wire component.

For input that uses `wire:model`, or `wire:model.lazy`, you may want to display that a field is 'dirty' until WireDrupal has fully updated.

## Toggling classes on "dirty" elements

Elements with the `wire:dirty` directive will watch for differences between the front-end value, and the last returned Wire data value.

Adding the `class` modifier allows you to add a class to the element when dirty.

```html
<input wire:dirty.class="text-red" wire:model.lazy="node.title">
```

With above, when a user modifies the input value, the element will receive the `text-red` class. The class will be removed again if the input value returns to its original state, or if the Wire component updates.

You can also perform the reverse, and remove classes by adding the `.remove` modifier, similar to how `wire:loading` works.

```html
<input wire:dirty.class.remove="text-red" class="text-red" wire:model.lazy="node.title">
```

The `text-red` class will be removed from the input while dirty.

## Toggling elements

The default behaviors of the `wire:dirty` directive without modifiers is that the element will be hidden until dirty. This can create a paradox if used on the input itself, but like loading states, the `dirty` directive can be used to toggle the appearance of other elements using `wire:target`

```html
<span wire:dirty wire:target="node.title">Updating...</span>

<input wire:model.lazy="node.title">
```

With above, the `span` will be hidden by default, and only visible when the input element is dirty.

## Toggling classes on other elements

The class and attribute modifiers can be used in the same way for referenced elements

```html
<label wire:dirty.class="text-red" wire:target="node.title">Title</label>

<input wire:model.lazy="node.title">
```

With above, when the `input` is dirty, the label text will receive the `text-red` class.

## Defer Loading

Lazy load components

WireDrupal offers a `wire:init` directive to run an action as soon as the component is rendered. This can be helpful in cases where you don't want to hold up the entire page load, but want to load some data immediately after the page load. Think of it as BigPipe of Drupal but instead, it makes a standalone requests to itself.

Bellow is an example of loading some Nodes after the component renders on the page.

```php
class ShowNodes extends WireComponentBase {

public bool $readyToLoad = FALSE;

public function loadNodes(): void {

$this->readyToLoad = TRUE;

}

public function render(): View {

return View::fromTpl('show_nodes', [
      'nodes' => $this->readyToLoad
        ? Node::loadMultiple([2, 3])
        : [],
    ]);

}

}
```

The Twig template would look as bellow.

```twig
<div wire:init="loadNodes">

<ul>
  
    {% for node in nodes %}
    
      <li>{{ node.label }}</li>
      
    {% endfor %}
    
  </ul>
  
</div>
```

The `loadNodes` action will be run immediately after the Wire component renders on the page.

# Inline Scripts

Working with JavaScript in Wire components

[AlpineJS](https://alpinejs.dev/) is recommended for most of your JavaScript needs, but using `<script>` tags directly inside component is perfectly acceptable.

```html
<div>
  
  ...

document.addEventListener('wire:load', function () {

// Your JS here.

})

</script>

</div>
```

## JavaScript component instance

Each component has a JavaScript object. You can access this object using the special `@this` directive in your component.

Here's an example.

Assuming you're dispatching and event after performing some updates in a action handler:

```php
public function update(): void {
  // My action code here...
  
  $this->emitSelf('notifyUpdatedSuccess');
}
```

In your component template you can do:

```html

<div>

...

document.addEventListener('wire:load', function () {

// Get the value of the "count" property.
      let someValue = @this.count

// Set the value of the "count" property.
      @this.count = 5;

// Call the increment component action.
    @this.increment()

// Run a callback when an event ("notifyUpdatedSuccess")
    // is emitted from this component.
    @this.on('notifyUpdatedSuccess', () => {
      console.log('Successfully updated');
    })

});

</script>

</div>
```

Another example using AlpineJs to display a Success message disappearing in 2.5 seconds.

```html
<span
  x-data="{ open: false }"
  x-init="
          @this.on('notifyUpdatedSuccess', () => {
              if (open === false) setTimeout(() => { open = false }, 2500);
              open = true;
          })
         "
  x-show="open"
  style="display: none;"
  class="text-green-500 mr-5"
>Updated!</span>
```

> Note: the `@this` directive compiles to the following string for JavaScript to interpret: "Wire.find([component-id])"

# Troubleshooting

Common issues and solutions

## Root Element Issues

It is a requirement for each Wire component template to have only one HTML element at the root.

Having multiple root elements will lead to unexpected and broken behavior.

This is wrong:

```html
<div>

Some content

</div>

<button wire:click="doSomething">Do Something</button>
```

Bellow is the correct version (note that the button has been moved inside the root tag):

```html
<div>

<div>

Some content

</div>
 
    <button wire:click="doSomething">Do Something</button>

</div>
```

## Typed property accessed before initialization

***Error***

```plaintext
Error: Typed property Drupal\...\Plugin\WireComponent\MyClass::$myProp
must not be accessed before initialization in ...
```

***Solution***

Add a default value when declaring public property

## Query string not persisting on page refresh

Most likely, you rendered HTML is being cached.

Use CacheTrait and make usage of it on `mount` hook

## Uncaught (in promise) TypeError: this.messageInTransit is undefined

This error could be caused by [Mixed content](https://developer.mozilla.org/en-US/docs/Web/Security/Mixed_content)

If you're behind a reverse proxy environment you should ensure that HTTPS is on and the content of `w-app-url` meta tags has https in is

# End of Wire documentation

Hello World!

{{ count }}

{{ article.label }}

{{ article.label }}

{{ $message }}