orion/docs/frontend/shared/pagination.md

Admin List Pages - Pagination & Search Implementation

Overview

All admin list pages (Stores, Merchants, Users) share a consistent pagination and search pattern using server-side pagination with Alpine.js.

---

Files Using This Pattern

Page	HTML Template	JavaScript
Stores	templates/admin/stores.html	static/admin/js/stores.js
Merchants	templates/admin/merchants.html	static/admin/js/merchants.js
Users	templates/admin/users.html	static/admin/js/users.js

---

State Structure

Filters Object

filters: {
    search: '',        // Search query string
    is_active: '',     // 'true', 'false', or '' (all)
    is_verified: ''    // 'true', 'false', or '' (all) - stores/merchants only
    role: ''           // 'admin', 'store', or '' (all) - users only
}

Pagination Object

pagination: {
    page: 1,           // Current page number
    per_page: 10,      // Items per page
    total: 0,          // Total items from API
    pages: 0           // Total pages (calculated)
}

---

Computed Properties

All three pages implement these computed properties:

paginatedStores / paginatedMerchants / users

Returns the items array (already paginated from server):

get paginatedStores() {
    return this.stores;
}

totalPages

get totalPages() {
    return this.pagination.pages;
}

startIndex

get startIndex() {
    if (this.pagination.total === 0) return 0;
    return (this.pagination.page - 1) * this.pagination.per_page + 1;
}

endIndex

get endIndex() {
    const end = this.pagination.page * this.pagination.per_page;
    return end > this.pagination.total ? this.pagination.total : end;
}

pageNumbers

Generates smart page number array with ellipsis:

get pageNumbers() {
    const pages = [];
    const totalPages = this.totalPages;
    const current = this.pagination.page;

    if (totalPages <= 7) {
        for (let i = 1; i <= totalPages; i++) {
            pages.push(i);
        }
    } else {
        pages.push(1);
        if (current > 3) pages.push('...');

        const start = Math.max(2, current - 1);
        const end = Math.min(totalPages - 1, current + 1);
        for (let i = start; i <= end; i++) {
            pages.push(i);
        }

        if (current < totalPages - 2) pages.push('...');
        pages.push(totalPages);
    }
    return pages;
}

---

Methods

debouncedSearch()

Triggers search after 300ms delay:

debouncedSearch() {
    if (this._searchTimeout) {
        clearTimeout(this._searchTimeout);
    }
    this._searchTimeout = setTimeout(() => {
        this.pagination.page = 1;
        this.loadStores(); // or loadMerchants(), loadUsers()
    }, 300);
}

Pagination Methods

previousPage() {
    if (this.pagination.page > 1) {
        this.pagination.page--;
        this.loadStores();
    }
}

nextPage() {
    if (this.pagination.page < this.totalPages) {
        this.pagination.page++;
        this.loadStores();
    }
}

goToPage(pageNum) {
    if (pageNum !== '...' && pageNum >= 1 && pageNum <= this.totalPages) {
        this.pagination.page = pageNum;
        this.loadStores();
    }
}

---

API Integration

Building Query Parameters

async loadStores() {
    const params = new URLSearchParams();
    params.append('skip', (this.pagination.page - 1) * this.pagination.per_page);
    params.append('limit', this.pagination.per_page);

    if (this.filters.search) {
        params.append('search', this.filters.search);
    }
    if (this.filters.is_active !== '') {
        params.append('is_active', this.filters.is_active);
    }
    if (this.filters.is_verified !== '') {
        params.append('is_verified', this.filters.is_verified);
    }

    const response = await apiClient.get(`/admin/stores?${params}`);

    this.stores = response.stores;
    this.pagination.total = response.total;
    this.pagination.pages = Math.ceil(response.total / this.pagination.per_page);
}

API Response Format

{
    "stores": [...],
    "total": 45,
    "skip": 0,
    "limit": 10
}

---

HTML Template Structure

Search & Filters Bar

<div class="mb-6 p-4 bg-white rounded-lg shadow-xs dark:bg-gray-800">
    <div class="flex flex-col md:flex-row md:items-center md:justify-between gap-4">
        <!-- Search Input -->
        <div class="flex-1 max-w-md">
            <div class="relative">
                <span class="absolute inset-y-0 left-0 flex items-center pl-3">
                    <span x-html="$icon('search', 'w-5 h-5 text-gray-400')"></span>
                </span>
                <input
                    type="text"
                    x-model="filters.search"
                    @input="debouncedSearch()"
                    placeholder="Search..."
                    class="w-full pl-10 pr-4 py-2 text-sm border rounded-lg..."
                >
            </div>
        </div>

        <!-- Filters -->
        <div class="flex flex-wrap gap-3">
            <select x-model="filters.is_active" @change="pagination.page = 1; loadStores()">
                <option value="">All Status</option>
                <option value="true">Active</option>
                <option value="false">Inactive</option>
            </select>

            <select x-model="filters.is_verified" @change="pagination.page = 1; loadStores()">
                <option value="">All Verification</option>
                <option value="true">Verified</option>
                <option value="false">Pending</option>
            </select>

            <button @click="loadStores()">Refresh</button>
        </div>
    </div>
</div>

Pagination Footer

<div class="grid px-4 py-3 text-xs font-semibold tracking-wide text-gray-500 uppercase border-t bg-gray-50 sm:grid-cols-9">
    <!-- Results Info -->
    <span class="flex items-center col-span-3">
        Showing <span x-text="startIndex"></span>-<span x-text="endIndex"></span>
        of <span x-text="pagination.total"></span>
    </span>
    <span class="col-span-2"></span>

    <!-- Pagination Controls -->
    <span class="flex col-span-4 mt-2 sm:mt-auto sm:justify-end">
        <nav>
            <ul class="inline-flex items-center">
                <!-- Previous -->
                <li>
                    <button @click="previousPage()" :disabled="pagination.page === 1">
                        <!-- SVG arrow -->
                    </button>
                </li>

                <!-- Page Numbers -->
                <template x-for="pageNum in pageNumbers" :key="pageNum">
                    <li>
                        <button
                            x-show="pageNum !== '...'"
                            @click="goToPage(pageNum)"
                            :class="pagination.page === pageNum ? 'bg-purple-600 text-white' : ''"
                            x-text="pageNum"
                        ></button>
                        <span x-show="pageNum === '...'" class="px-3 py-1">...</span>
                    </li>
                </template>

                <!-- Next -->
                <li>
                    <button @click="nextPage()" :disabled="pagination.page === totalPages">
                        <!-- SVG arrow -->
                    </button>
                </li>
            </ul>
        </nav>
    </span>
</div>

---

Page Number Display Examples

Few pages (<=7):

← 1 2 3 4 5 6 7 →

Many pages, current = 1:

← [1] 2 3 ... 10 →

Many pages, current = 5:

← 1 ... 4 [5] 6 ... 10 →

Many pages, current = 10:

← 1 ... 8 9 [10] →

---

Visual Layout

┌──────────────────────────────────────────────────────────────────┐
│ Store Management                           [+ Create Store]    │
├──────────────────────────────────────────────────────────────────┤
│ [Total] [Verified] [Pending] [Inactive]         ← Stats Cards    │
├──────────────────────────────────────────────────────────────────┤
│ [🔍 Search...        ] [Status ▼] [Verified ▼] [Refresh]         │
├──────────────────────────────────────────────────────────────────┤
│ Store │ Subdomain │ Status   │ Created │ Actions                │
├────────┼───────────┼──────────┼─────────┼────────────────────────┤
│ Acme   │ acme      │ Verified │ Jan 1   │ 👁 ✏️ 🗑              │
│ Beta   │ beta      │ Pending  │ Jan 2   │ 👁 ✏️ 🗑              │
│ ...    │ ...       │ ...      │ ...     │ ...                    │
├──────────────────────────────────────────────────────────────────┤
│ Showing 1-10 of 45                    ← 1 2 [3] 4 ... 9 →       │
└──────────────────────────────────────────────────────────────────┘

---

Configuration

Change Items Per Page

In the JavaScript file:

pagination: {
    page: 1,
    per_page: 25,  // Change from 10 to 25
    total: 0,
    pages: 0
}

---

Features Summary

• Server-side pagination with skip/limit API params
• Debounced search (300ms delay)
• Multiple filter dropdowns
• Smart page number display with ellipsis
• Refresh button
• Contextual empty state messages
• Dark mode support
• Responsive design
• Consistent across all admin list pages