Live List

<x-wirekit::live-list> holds a list that changes while somebody reads it: an inbox that a broadcast refreshes, a queue that new orders join. An entry inserted above the rows in view would push them down, and the reader would lose the line they were on. The live list keeps the first row in view where it was, and when new entries land out of sight, a hint says so and brings them into view.

Basic Usage

Put the list in the slot and mark each row with data-wk-live-row. A row the server marks data-wk-live-fresh is new or has moved.

<x-wirekit::live-list>
    <x-wirekit::stack gap="xs">
        <x-wirekit::card data-wk-live-row data-wk-live-fresh>
            <x-wirekit::card.body>
                <x-wirekit::text weight="medium">Refund for order 1042</x-wirekit::text>
                <x-wirekit::text size="sm" intent="muted">Arrived a moment ago</x-wirekit::text>
            </x-wirekit::card.body>
        </x-wirekit::card>
        <x-wirekit::card data-wk-live-row>
            <x-wirekit::card.body>
                <x-wirekit::text weight="medium">Invoice address change</x-wirekit::text>
                <x-wirekit::text size="sm" intent="muted">12 minutes ago</x-wirekit::text>
            </x-wirekit::card.body>
        </x-wirekit::card>
        <x-wirekit::card data-wk-live-row>
            <x-wirekit::card.body>
                <x-wirekit::text weight="medium">Delivery to a pick-up point</x-wirekit::text>
                <x-wirekit::text size="sm" intent="muted">1 hour ago</x-wirekit::text>
            </x-wirekit::card.body>
        </x-wirekit::card>
    </x-wirekit::stack>
</x-wirekit::live-list>

Live Renders

live says that a render answers a live event. Set it when the component re-renders because something arrived, and leave it off when the reader asked for a different list, a filter or the next page: only a live render keeps the reader's place, and a filter that moved the reader to the top would otherwise be undone.

// 1. A Livewire component that re-renders its inbox when a conversation arrives.
use Livewire\Attributes\On;

public bool $live = false;

#[On('echo-private:inbox,ConversationArrived')]
public function arrived(): void
{
    $this->live = true;
}

public function updatedFilter(): void
{
    $this->live = false;
}

{{-- 2. Every row with its key, and the rows that arrived marked fresh. --}}
<x-wirekit::live-list :live="$live">
    @foreach ($conversations as $conversation)
        <a href="{{ route('conversations.show', $conversation) }}"
           wire:key="conversation-{{ $conversation->id }}"
           data-wk-live-row
           @if ($conversation->arrivedRecently()) data-wk-live-fresh @endif
        >{{ $conversation->subject }}</a>
    @endforeach
</x-wirekit::live-list>

The list keeps its place in the region it scrolls in: a panel of its own with overflow-y: auto, or the page. It does not depend on the browser's scroll anchoring, so it behaves the same in every engine.

Fresh Rows Out of Sight

A fresh row the reader cannot see raises a hint at the top of the list, "New entries above", or at the bottom, "New entries below", and a screen reader hears the same sentence. The hint brings the first such row into view and puts the focus on its link, or on the row itself where it has no link. A fresh row counts until it has been in view once.

Props

Accessibility

• The hints are buttons, named by their text, and they announce themselves in a role="status" region when they appear after a live render.
• A hint moves the focus to the row it brings into view, so the next Tab continues from there.
• Without live, the list leaves the scroll alone, so a list the reader filtered starts where the reader expects.

Keyboard Interaction