Actions

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:

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:

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

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

<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:

<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:

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 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.:

<!-- Call action only when event.key is equal to 'ArrowDown'. -->
<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

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

  it can be done as

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

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

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

  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 for more details.