Lewati ke konten
MarkasUI
Ketik untuk mencari

    Panduan

    MarkasUI

    Form

    Feedback

    Overlay

    Navigasi

    Data

    Section

    Animasi

    Latar

    Tombol

    Template

    Halaman

    Livewire

    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/vite

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

    KomponenTerhubung keContoh
    Input, Textarea, Selectstring<x-markas.input label="Nama" wire:model.live="name" />
    Checkbox, Switchboolean<x-markas.switch label="Notifikasi" wire:model="notify" />
    Checkbox dengan valuearray nilai tercentang<x-markas.checkbox value="vue" wire:model="tags" />
    Radio groupnilai terpilih<x-markas.radio-group name="plan" wire:model="plan" ... />

    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.

    KomponenTerhubung ke
    Sliderangka
    Comboboxvalue terpilih (bukan teks ketikan)
    Currency inputangka polos, misalnya 12500000
    Input OTPkode gabungan sebagai satu string
    Toggleboolean
    Toggle groupstring atau null (single), array (type="multiple")
    Modal, Drawer, Alert dialogstatus terbuka (boolean)
    File dropzonefile 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.run($event.detail)" 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:model komponen (atau wire:key, atau name) ditambah urutannya, bukan dari nilai acak. Livewire mencocokkan elemen lewat id, jadi id yang berubah akan mengganti elemen dan menghilangkan fokus saat mengetik. Isi id sendiri kalau butuh nilai tetap, misalnya untuk <label> atau aria-describedby.
    • Yang terbuka tetap terbuka. Dialog, drawer, accordion details, dan panel Popover API (dropdown, popover, tooltip, daftar combobox) memakai wire: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>
    @endisland

    wire: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" />
    @endforeach

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

    optimize 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/views/components/markas, 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 :options dan :items ke 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 @island di Livewire 4 agar render ulang hanya mencakup bagian yang berubah. Muat bagian yang berat dengan lazy (atau defer di 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, ganti wire: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/livewire/perf-budgets.json, 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 pakai Route::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, lalu id (Livewire 3 memeriksa wire:key dulu, Livewire 4 wire:id dulu), 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).