You're browsing the documentation for an old version of Livewire. Consider upgrading your project to Livewire 3.x.
Be amazing at Livewire
with our in-depth screencasts. Watch Now
- Template Directives
- Alpine Component Object ($wire)
- Global Livewire JavaScript Object
- JavaScript Hooks
- Component Class Lifecycle Hooks
- Component Class Protected Properties
- Component Class Traits
- Class Methods
- PHP Testing Methods
- Artisan Commands
- PHP Lifecycle Hooks
Already familiar with Livewire and want to skip the long-form documentation? Here's a giant list of everything available in Livewire.
Template Directives
These are directives added to elements within Livewire component templates.
1<button wire:click="save">...</button>
Directive | Description |
---|---|
wire:key="foo" | Acts as a reference point for Livewire's DOM diffing system. Useful for adding/removing elements, and keeping track of lists. |
wire:click="foo" | Listens for a "click" event, and fires the "foo" method in the component. |
wire:click.prefetch="foo" | Listens for a "mouseenter" event, and "prefetches" the result of the "foo" method in the component. Then, if it is clicked, will swap in the "prefetched" result (without an extra request), if it's not clicked, will throw away the cached result. |
wire:keydown.enter="foo" | Listens for a keydown event on the enter key, which fires the "foo" method in the component. |
wire:foo="bar" | Listens for a browser event called "foo". (You can listen for any browser DOM event - not just those fired by Livewire). |
wire:model="foo" | Assuming $foo is a public property on the component class, every time an input element with this directive is updated, the property synchronizes with its value. |
wire:model.debounce.100ms="foo" | Debounces the input events emitted by the element every 100 milliseconds. |
wire:model.lazy="foo" | Lazily syncs the input with its corresponding component property at rest. |
wire:model.defer="foo" | Defers syncing the input with the Livewire property until an "action" is performed. This saves drastically on server roundtrips. |
wire:poll.500ms="foo" | Runs the "foo" method on the component class every 500 milliseconds. |
wire:init="foo" | Runs the "foo" method on the component immediately after it renders on the page. |
wire:loading | Hides the element by default, and makes it visible while network requests are in transit. |
wire:loading.class="foo" | Adds the foo class to the element while network requests are in transit. |
wire:loading.class.remove="foo" | Removes the foo class while network requests are in transit. |
wire:loading.attr="disabled" | Adds the disabled="true" attribute while network requests are in transit. |
wire:dirty | Hides the element by default, and makes it visible while the element's state is "dirty" (different from what exists on the backend). |
wire:dirty.class="foo" | Adds the foo class to the element while it's dirty. |
wire:dirty.class.remove="foo" | Removes the foo class while the element is dirty. |
wire:dirty.attr="disabled" | Adds the disabled="true" attribute while the element's dirty. |
wire:target="foo" | Scopes wire:loading and wire:dirty functionality to a specific action. |
wire:ignore | Instructs Livewire to not update the element or its children when updating the DOM from a server request. Useful when using third-party JavaScript libraries within Livewire components. |
wire:ignore.self | The "self" modifier restricts updates to the element itself, but allows modifications to its children. |
Alpine Component Object ($wire
)
These are methods and properties available on the $wire
object provided to Alpine components within a Livewire template. Read Full Documentation
1<div x-data>
2 <span x-show="$wire.showMessage">...</span>
3
4 <button x-on:click="$wire.toggleShowMessage()">...</button>
5</div>
API | Description |
---|---|
$wire.foo | Get the value of the "foo" property on the Livewire component |
$wire.foo = 'bar' | Set the value of the "foo" property on the Livewire component |
$wire.bar(..args) | Call the "bar" method (with params) on the Livewire component |
let baz = await $wire.bar(..args) | Call the "bar" method, but wait for the response and set baz to it |
$wire.on('foo', (..args) => {}) | Call a function when the "foo" event is emitted |
$wire.emit('foo', ...args) | Emit the "foo" event to all Livewire components |
$wire.emitUp('foo', ...args) | Emit the "foo" event to parent components |
$wire.emitSelf('foo', ...args) | Emit the "foo" event only to this component |
$wire.get('foo') | Get the "foo" property |
$wire.set('foo', 'bar') | Set the "foo" property on the component |
$wire.set('foo', 'bar', true) | Defer setting the "foo" property on the component |
$wire.call('foo', ..args) | Call the "foo" method with params on the component |
x-data="{ foo: $wire.entangle('foo') }" | Entangle the value of "foo" between Livewire and Alpine |
$wire.entangle('foo').defer | Only update Livewire's "foo" next time a Livewire request is fired |
Global Livewire JavaScript Object
These are methods available on the window.Livewire
object in the frontend. These are for deeper Livewire interaction and customization.
Method | Description |
---|---|
Livewire.first() | Get the first Livewire component's JS object on the page |
Livewire.find(componentId) | Get a Livewire component by it's ID |
Livewire.all() | Get all the Livewire components on a page |
Livewire.directive(directiveName, (el, directive, component) => {}) | Register a new Livewire directive (wire:custom-directive ) |
Livewire.hook(hookName, (...) => {}) | Call a method when JS lifecycle hook is fired. Read more |
Livewire.onLoad(() => {}) | Fires when Livewire is first finished loading on a page |
Livewire.onError((message, statusCode) => {}) | Fires when a Livewire request fails. You can return false from the callback to prevent Livewire's default behavior |
Livewire.onPageExpired((response, message) => {}) | When the page or session has expired it executes the callback instead of Livewire's page expired dialog |
Livewire.emit(eventName, ...params) | Emit an event to all Livewire components listening on a page |
Livewire.emitTo(componentName, eventName, ...params) | Emit an event to specific component name |
Livewire.on(eventName, (...params) => {}) | Listen for an event to be emitted from a component |
Livewire.start() | Boot Livewire on the page (done for you automatically via @livewireScripts ) |
Livewire.stop() | Tear down Livewire from the page |
Livewire.restart() | Stop, then start Livewire on the page |
Livewire.rescan() | Re-scan the DOM for newly added Livewire components |
JavaScript Hooks
These are "hooks" you can listen for in JavaScript. These allow you to hook into very specific parts of a Livewire component's JavaScript lifecycle for third-party packages or deep customizations. The abilities unlocked here are immense. A significant portion of Livewire's core uses these hooks to provide functionality.
1Livewire.hook('component.initialized', component => {
2 //
3})
Name | Params | Description |
---|---|---|
component.initialized | (component) | A new component has been initialized |
element.initialized | (el, component) | A new element has been initialized |
element.updating | (fromEl, toEl, component) | An element is about to be updated after a Livewire request |
element.updated | (el, component) | An element has just been updated from a Livewire request |
element.removed | (el, component) | An element has been removed after a Livewire request |
message.sent | (message, component) | A new Livewire message was just sent to the server |
message.failed | (message, component) | A Livewire ajax request (message) failed |
message.received | (message, component) | A message has been received (but hasn't affected the DOM) |
message.processed | (message, component) | A message has been fully received and implemented (DOM updates, etc...) |
Component Class Lifecycle Hooks
These are methods you can declare in your Livewire component classes to run code at specific times in the backend's lifecycle. Read Full Documentation
1class ShowPost extends Component
2{
3 public function mount()
4 {
5 //
6 }
7}
Name | Description |
---|---|
boot() | Called on all requests, immediately after the component is instantiated, but before any other lifecycle methods are called |
booted() | Called on all requests, after the component is mounted or hydrated, but before any update methods are called |
mount(...$params) | Called when a Livewire component is newed up (think of it like a constructor) |
hydrate() | Called on subsequent Livewire requests after the component has been hydrated, but before any other action occurs |
hydrateFoo() | Runs after a property called $foo is hydrated |
dehydrate() | Called after render() , but before the component has been dehydrated and sent to the frontend |
dehydrateFoo() | Runs before a property called $foo is dehydrated |
updating() | Runs before any update to the Livewire component's data (Using wire:model, not directly inside PHP) |
updated($field, $newValue) | Called after a property has been updated |
updatingFoo() | Runs before a property called $foo is updated |
updatedFoo($newValue) | Called after the "foo" property has been updated |
updatingFooBar() | Runs before updating a nested property bar on the $foo property |
updatedFooBar($newValue) | Called after the nested "bar" key on the "foo" property has been updated |
render() | Called before "dehydrate" and renders the Blade view for the component |
Component Class Protected Properties
Livewire provides core functionality through protected properties on a component's class. Most of these have corresponding methods by the same name if you prefer to return values in a method, rather than declare them as properties.
1class ShowPost extends Component
2{
3 protected $rules = ['foo' => 'required|min:6'];
4}
Name | Description |
---|---|
$queryString | Declare which properties to "bind" to the query sting. Read Docs |
$rules | Specify validation rules to be applied to properties when calling $this->validate() . Read Docs |
$listeners | Specify which events you want to listen for emitted by other components. Read Docs |
$paginationTheme | Specify whether you want to use Tailwind or Bootstrap for you pagination theme. Read Docs |
Component Class Traits
These are traits that unlock additional functionality in a Livewire component. Usually for features that are considered best as "opt-in".
1class ShowPost extends Component
2{
3 use WithPagination;
4}
Name | Description |
---|---|
WithPagination | This trait enables Livewire-based pagination instead of Laravel's stock pagination system. Read Docs |
WithFileUploads | This trait enables adding wire:model to an input of type="file" . Read Docs |
Class Methods
1class PostForm extends Component
2{
3 public function save()
4 {
5 ...
6
7 $this->emit('post-saved');
8 }
9}
Name | Description |
---|---|
$this->emit($eventName, ...$params) | Emit an event to other components on the page |
$this->emit($eventName, ...$params)->up() | Emit an event to parent components on the page |
$this->emit($eventName, ...$params)->self() | Emit an event only to THIS component |
$this->emit($eventName, ...$params)->to($componentName) | Emit an event to any component matching the provided name |
$this->dispatchBrowserEvent($eventName, ...$params) | Dispatch a browser event from this component's root element |
$this->validate() | Run the validation rules provided in the $rules property against the public component properties |
$this->validate($rules, $messages) | Run the provided validation rules against the public properties |
$this->validateOnly($propertyName) | Run the $rules property validation against a specific property provided and not others |
$this->validateOnly($propertyName, $rules, $messages) | Run the provided validation rules against a specific property name |
$this->redirect($url) | Redirect to a new URL when the Livewire request finishes and reaches the frontend |
$this->redirectRoute($routeName) | Redirect to a specific route name |
$this->skipRender() | Skip running the ->render() method for the current request. (Usually for performance reasons) |
$this->addError($name, $error) | Add a specific error name and value to the component's error bag manually |
$this->resetValidation() | Reset the currently stored validation errors (clear them) |
$this->fill([...$propertyData]) | Set public property names to provided values in bulk |
$this->reset() | Reset all public properties to their initial (pre-mount) state |
$this->reset($field) | Reset a specific public property to its pre-mount state |
$this->reset([...$fields]) | Reset multiple specific properties |
$this->all() | Return key->value pairs of property data |
$this->only([...$propertyNames]) | Return key->value pairs of property data only for a specific set of property names |
$this->except([...$propertyNames]) | Return key->value pairs of property data except for a specific set of property names |
PHP Testing Methods
These are methods available on Livewire's testing helpers. Read Full Documentation
1public function test()
2{
3 Livewire::test(ShowPost::class)
4 ->assertDontSee('bar')
5 ->set('foo', 'bar')
6 ->assertSee('bar');
7}
Name |
---|
->assertSet($propertyName, $value) |
->assertNotSet($propertyName, $value) |
->assertCount($propertyName, $value) |
->assertPayloadSet($propertyName, $value) |
->assertPayloadNotSet($propertyName, $value) |
->assertSee($string) |
->assertDontSee($string) |
->assertSeeHtml($string) |
->assertDontSeeHtml($string) |
->assertSeeHtmlInOrder([$firstString, $secondString]) |
->assertSeeInOrder([$firstString, $secondString]) |
->assertEmitted($eventName) |
->assertNotEmitted($eventName) |
->assertDispatchedBrowserEvent($eventName) |
->assertHasErrors($propertyName) |
->assertHasErrors($propertyName, ['required', 'min:6']) |
->assertHasNoErrors($propertyName) |
->assertHasNoErrors($propertyName, ['required', 'min:6']) |
->assertRedirect() |
->assertRedirect($url) |
->assertViewHas($viewDataKey) |
->assertViewHas($viewDataKey, $expectedValue) |
->assertViewHas($viewDataKey, function ($dataValue) {}) |
->assertViewIs('livewire.some-view-name') |
->assertFileDownloaded($filename) |
There are also Laravel testing response helpers available to check the presence of a component on a given page.
Name |
---|
$response->assertSeeLivewire('some-component') |
$response->assertDontSeeLivewire('some-component') |
Artisan Commands
These are the artisan
commands Livewire makes available to make frequent tasks like creating a component easier.
Name | Params | Description |
---|---|---|
artisan make:livewire | Create a new component | |
artisan livewire:make | Create a new component | |
artisan livewire:copy | Copy a component | |
artisan livewire:move | Move a component | |
artisan livewire:delete | Delete a component | |
artisan livewire:touch | Alias for livewire:make | |
artisan livewire:cp | Alias for livewire:copy | |
artisan livewire:mv | Alias for livewire:move | |
artisan livewire:rm | Alias for livewire:delete | |
artisan livewire:stubs | Publish Livewire stubs (used in the above commands) for local modification | |
artisan livewire:publish | Publish Livewire's config file to your project (config/livewire.php ) | |
artisan livewire:publish --assets | Publish Livewire's config file AND its frontend assets to your project | |
artisan livewire:configure-s3-upload-cleanup | Configure your cloud disk driver's S3 bucket to clear temporary uploads after 24 hours |
PHP Lifecycle Hooks
These are hooks provided by Livewire in PHP for listening to lifecycle occurences at a global level (not at a component level). These are used internally to provide a significant portion of Livewire's core functionality, and can be used in ServiceProviders to further extend Livewire yourself.
1Livewire::listen('component.hydrate', function ($component, $request) {
2 //
3});
Name | Params | Description |
---|---|---|
component.hydrate | ($component, $request) | Run on EVERY component hydration |
component.hydrate.initial | ($component, $request) | Run only on the INITIAL hydration (When the component is first loaded) |
component.hydrate.subsequent | ($component, $request) | Run only AFTER the initial component request |
component.dehydrate | ($component, $response) | Run on EVERY component dehydration |
component.dehydrate.initial | ($component, $response) | Run only on the INITIAL dehydration (When the component is first loaded) |
component.dehydrate.subsequent | ($component, $response) | Run on dehydrate AFTER the initial component request |
property.hydrate | ($name, $value, $component, $request) | Run when a specific property is hydrated |
property.dehydrate | ($name, $value, $component, $response) | Run when a specific property is dehydrated |
← Previous Topic Quickstart
Next Topic → Upgrading From 1.x