Pakai komponen Blade di Livewire 4 (dan 3) dengan wire:model, render ulang, dan wire:navigate.
Komponen Blade jalan di Livewire 4 tanpa setup tambahan, dan di Livewire 3 dengan cara yang sama. Kontrol form menerima wire:model, dialog dan menu yang terbuka tetap terbuka saat komponen dirender ulang, dan tidak ada yang rusak setelah wire:navigate.
Setup
Ikuti instalasi Laravel (Blade) dengan satu perubahan: jangan pasang atau jalankan Alpine.js sendiri. Livewire sudah membawa Alpine dan menjalankannya. Memuat salinan kedua membuat setiap x-data berjalan dua kali dan merusak wire:model.
npm install tailwindcss @tailwindcss/viteBiarkan resources/js/app.js tanpa import Alpine. Livewire menyisipkan script-nya di halaman yang merender komponen. Kalau layout tidak punya komponen Livewire, tambahkan @livewireScripts sebelum </body>.
Untuk mendaftarkan data atau plugin Alpine sendiri, dengarkan alpine:init, yang berjalan sebelum Alpine mulai:
document.addEventListener("alpine:init", () => {
Alpine.data("counter", () => ({ count: 0 }));
});Kalau Anda membundel Livewire sendiri, pakai @livewireScriptConfig di layout lalu jalankan dari app.js:
import {
Livewire,
Alpine,
} from "../../vendor/livewire/livewire/dist/livewire.esm";
Alpine.data("counter", () => ({ count: 0 }));
Livewire.start();Tidak ada komponen yang butuh plugin Alpine. Livewire sudah membawa morph, intersect, collapse, focus, anchor, mask, dan resize (Livewire 4 menambah sort), jadi direktif itu bisa dipakai di markup Anda tanpa memasang apa pun.
wire:model
Setiap komponen form menerima wire:model dengan modifier biasa (.live, .blur, .change, .debounce.300ms, .throttle). Ada dua pola, tergantung di mana nilainya disimpan.
Kontrol native. Atribut jatuh ke input, textarea, atau select asli, jadi Livewire memperlakukannya seperti HTML biasa.
| Komponen | Terhubung ke | Contoh |
|---|---|---|
| Input, Textarea, Select | string | <x-markas |
| Checkbox, Switch | boolean | <x-markas |
Checkbox dengan value | array nilai tercentang | <x-markas |
| Radio group | nilai terpilih | <x-markas |
Radio group menyalin wire:model ke setiap radio.
Kontrol Alpine. Nilainya ada di state Alpine, jadi wire:model dipasang di root komponen yang punya x-modelable. Perubahan dari server ikut masuk: set $this->country = 'jp' menampilkan “Jepang” di combobox.
| Komponen | Terhubung ke |
|---|---|
| Slider | angka |
| Combobox | value terpilih (bukan teks ketikan) |
| Currency input | angka polos, misalnya 12500000 |
| Input OTP | kode gabungan sebagai satu string |
| Toggle | boolean |
| Toggle group | string atau null (single), array (type="multiple") |
| Modal, Drawer, Alert dialog | status terbuka (boolean) |
| File dropzone | file terunggah, atau array dengan multiple |
x-model bekerja dengan cara yang sama untuk Alpine biasa.
Di kontrol Alpine, .blur dan .enter mendengarkan elemen root dan tidak terpicu oleh input di dalamnya. Pakai .live, .live.debounce, atau .change.
Membuka dialog dari server
<x-markas.modal title="Ubah profil" wire:model="showEdit">
...
</x-markas.modal>public bool $showEdit = false;
public function save(): void
{
// ...
$this->showEdit = false;
}Menutup dengan Escape, tombol tutup, atau backdrop mengembalikan properti ke false.
Unggah file
Tambahkan use WithFileUploads; di komponen lalu hubungkan dropzone:
<x-markas.file-dropzone multiple accept="image/*" :max-size="5242880" wire:model="photos" />Hanya file yang lolos accept, maxSize, dan maxFiles yang diunggah. Progres unggah mengisi setiap bar. Tetap validasi lagi di server.
Event
Komponen memancarkan event browser seperti markas-select, markas-change, markas-action, dan markas-cancel. Livewire bisa mendengarkan event apa pun dengan wire: ditambah nama event:
<x-markas.dropdown-menu label="Aksi" :items="$actions" wire:markas-select="run($event.detail)" />
<x-markas.alert-dialog title="Hapus project?" wire:model="confirming" wire:markas-action="delete">
Tindakan ini tidak bisa dibatalkan.
</x-markas.alert-dialog>x-on:markas-select="$wire sama hasilnya. wire:click, wire:loading, dan atribut wire: lain diteruskan apa adanya. Event yang dipancarkan tiap komponen tercantum di halamannya.
Untuk menampilkan toast dari action, kirim event toast. Livewire memancarkannya di window, tempat <x-markas.toast /> mendengarkan:
$this->dispatch('markas-toast', title: 'Tersimpan', variant: 'success');Render ulang
Livewire memperbarui halaman dengan menggabungkan (morph) HTML baru ke HTML lama. Komponen disusun agar render ulang mempertahankan apa yang dilihat user:
- Id tidak berubah. Id otomatis berasal dari
wire:modelkomponen (atauwire:key, atauname) ditambah urutannya, bukan dari nilai acak. Livewire mencocokkan elemen lewat id, jadi id yang berubah akan mengganti elemen dan menghilangkan fokus saat mengetik. Isiidsendiri kalau butuh nilai tetap, misalnya untuk<label>atauaria-describedby. - Yang terbuka tetap terbuka. Dialog, drawer, accordion
details, dan panel Popover API (dropdown, popover, tooltip, daftar combobox) memakaiwire:ignore.self. Livewire tetap memperbarui isinya, tapi tidak menyentuh status terbuka dan posisinya. Pengecualiannya daftar opsi combobox: setelah render pertama daftar itu dipegang Alpine (lihat Performa). - State Alpine tetap. Tab aktif, slide carousel, item yang di-toggle, dan state animasi tidak di-reset.
Komponen yang menggambar dengan JavaScript (drag elements, stacking cards, canvas pixel trail, ikon theme toggle) dan lapisan dekoratif yang dibangkitkan dilewati morph sepenuhnya lewat wire:ignore.
Island
@island di Livewire 4 dirender ulang sendiri, jadi id otomatis di dalamnya tidak bisa bergantung pada komponen di sekitarnya. Beri komponen di dalam island yang tidak punya wire:model sebuah id atau wire:key:
@island(name: 'stats')
<x-markas.tabs wire:key="stats-tabs" :items="$periods">...</x-markas.tabs>
@endislandwire:key di daftar
Beri setiap item di loop sebuah wire:key, seperti anjuran Livewire. Di komponen MarkasUI, wire:key juga menjadi dasar id otomatis:
@foreach ($users as $user)
<x-markas.checkbox wire:key="user-{{ $user->id }}" :label="$user->name" value="{{ $user->id }}" wire:model="selected" />
@endforeachwire:navigate
Komponen dengan listener global (scroll, resize, hotkey Ctrl+K, event toast) melepasnya di destroy() milik Alpine saat halaman berganti, jadi bolak-balik halaman tidak menumpuk listener atau membuka dua dialog. Komponen yang mulai saat dimuat, seperti number ticker atau typing text, mulai lagi di halaman baru.
Letakkan bagian bersama seperti <x-markas.toast /> atau navbar di layout. Bungkus dengan @persist('toast') kalau state-nya harus bertahan saat navigasi.
Performa
Setiap update merender ulang seluruh komponen Livewire di server lalu menggabungkan (morph) HTML barunya ke halaman. Tiga hal menentukan kecepatannya: kerja Blade di server, ukuran HTML yang dikirim balik, dan jumlah elemen yang dilewati morph di browser.
Di server
Kerja Blade per komponen kecil: beberapa string class dan satu pencarian id, tanpa query atau akses file. Sebagian besar waktu per komponen adalah penanganan anonymous component milik Laravel sendiri (sekitar 0,05 sampai 0,1 ms per komponen di laptop), jadi aktifkan semua cache saat deploy:
composer install --no-dev --optimize-autoloader
php artisan optimizeoptimize menyimpan cache config, route, event, dan view Blade yang sudah dikompilasi (php artisan view:cache saja untuk view). Biarkan OPcache aktif di production. Komponen yang disalin CLI ada di resources/, yang sudah dikenali Laravel sebagai <x-markas.*>. Kalau disimpan di folder lain, daftarkan folder itu sekali dengan prefix, jangan include view lewat path:
// AppServiceProvider::boot()
Blade::anonymousComponentPath(resource_path('views/ui/markas'), 'markas');Lebih sedikit yang dikirim dan di-morph
- Batasi
:optionsdan:itemske pilihan yang memang dibutuhkan user. Keduanya dicetak ke HTML (dan ke state Alpine) di setiap render. Buat di property#[Computed]agar daftar dibuat sekali per request. - Komponen Livewire mengirim seluruh HTML-nya di setiap update, walau yang berubah hanya satu property yang tidak terkait. Pecah halaman menjadi komponen yang lebih kecil, atau pakai
@islanddi Livewire 4 agar render ulang hanya mencakup bagian yang berubah. Muat bagian yang berat denganlazy(ataudeferdi Livewire 4). - Lapisan dekoratif (stars, sparkles, meteors, beams, background lines dan boxes), ikon theme toggle, dan daftar opsi combobox dilewati morph dengan
wire:ignore. Semuanya digambar sekali lalu dipegang CSS atau Alpine, jadi props yang membentuknya (count,seed,cols,options) dibaca di render pertama. Untuk menggambar ulang dengan props baru, gantiwire:key-nya.
Mengetik
wire:model.live di input teks menunggu 150 ms setelah tombol terakhir sebelum memanggil server (bawaan Livewire). Kontrol Alpine yang nilainya berubah saat diketik atau digeser (currency input, input OTP, slider) mendapat debounce 150 ms yang sama kalau ditulis wire:model.live tanpa waktu sendiri, jadi satu rentetan ketikan mengirim satu request, bukan satu per tombol. Tulis .debounce.500ms atau .throttle untuk memilih sendiri, dan pakai wire:model biasa kalau nilainya baru penting saat submit:
<x-markas.input label="Cari" wire:model.live.debounce.250ms="search" />
<x-markas.currency-input label="Jumlah" wire:model.live="amount" />x-model di dalam komponen Livewire
Hubungkan kontrol Alpine ke Livewire dengan wire:model. Kalau dihubungkan ke state Alpine lokal dengan x-model di dalam komponen Livewire, setiap update Livewire menyisakan salinan elemen yang sudah terlepas (masalah Alpine pada x-modelable saat morph, masih ada sampai Alpine 3.17), jadi memori bertambah di setiap update. Pakai wire:model, atau letakkan state Alpine itu di luar komponen Livewire.
Budget
pnpm test:livewire mengukur setiap komponen di app Laravel dengan cache di atas aktif: waktu render Blade, ukuran HTML (mentah dan gzip), ukuran atribut Alpine, elemen yang dilewati morph, waktu init Alpine dan morph, pertambahan listener dan node DOM selama 20 update, dan jumlah request per rentetan ketikan. Ukuran byte dan jumlah elemen diberi budget pasti di tests/, waktu diberi batas longgar.
Livewire 3
Semua di atas jalan di Livewire 3.6 ke atas. Perbedaannya ada di sisi Livewire:
- Livewire 4 mendaftarkan route halaman penuh dengan
Route::livewire(). Di Livewire 3 pakaiRoute::get('/.path', Component::class) - Livewire 4 menambah island, single file component, dan
wire:ref. Fitur itu tidak mengubah perilaku komponen. - Kedua versi mencocokkan elemen saat morph lewat
wire:key,wire:id, laluid(Livewire 3 memeriksawire:keydulu, Livewire 4wire:iddulu), karena itu id yang stabil penting di keduanya. - Livewire 3 tidak membawa plugin sort Alpine. Tidak ada komponen yang memakainya.
Setiap perubahan diuji di CI terhadap Livewire 3 dan 4 di app Laravel baru: setiap komponen dirender ulang tanpa kehilangan elemen atau state, kontrol form terhubung dua arah, dan wire:navigate tidak menambah listener. Jalankan pengecekan yang sama dengan pnpm test:livewire (LIVEWIRE=3 untuk versi 3).