Pagination

A versatile pagination component supporting three modes: client (items already in the DOM — JS shows/hides them), server (renders real <a> links for full-page navigation), and ajax (JS fetches each page and injects the HTML response into a target container).

Client-Side Pagination

All 47 items are rendered server-side. The pagination reads the item count automatically from the target container and shows/hides slices — no database query needed per page. Items must be direct children of the target, or carry data-pagination-item.

List Item #1
Client-side pagination — all items are in the DOM

List Item #2
Client-side pagination — all items are in the DOM

List Item #3
Client-side pagination — all items are in the DOM

List Item #4
Client-side pagination — all items are in the DOM

List Item #5
Client-side pagination — all items are in the DOM

List Item #6
Client-side pagination — all items are in the DOM

List Item #7
Client-side pagination — all items are in the DOM

List Item #8
Client-side pagination — all items are in the DOM

List Item #9
Client-side pagination — all items are in the DOM

List Item #10
Client-side pagination — all items are in the DOM

List Item #11
Client-side pagination — all items are in the DOM

List Item #12
Client-side pagination — all items are in the DOM

List Item #13
Client-side pagination — all items are in the DOM

List Item #14
Client-side pagination — all items are in the DOM

List Item #15
Client-side pagination — all items are in the DOM

List Item #16
Client-side pagination — all items are in the DOM

List Item #17
Client-side pagination — all items are in the DOM

List Item #18
Client-side pagination — all items are in the DOM

List Item #19
Client-side pagination — all items are in the DOM

List Item #20
Client-side pagination — all items are in the DOM

List Item #21
Client-side pagination — all items are in the DOM

List Item #22
Client-side pagination — all items are in the DOM

List Item #23
Client-side pagination — all items are in the DOM

List Item #24
Client-side pagination — all items are in the DOM

List Item #25
Client-side pagination — all items are in the DOM

List Item #26
Client-side pagination — all items are in the DOM

List Item #27
Client-side pagination — all items are in the DOM

List Item #28
Client-side pagination — all items are in the DOM

List Item #29
Client-side pagination — all items are in the DOM

List Item #30
Client-side pagination — all items are in the DOM

List Item #31
Client-side pagination — all items are in the DOM

List Item #32
Client-side pagination — all items are in the DOM

List Item #33
Client-side pagination — all items are in the DOM

List Item #34
Client-side pagination — all items are in the DOM

List Item #35
Client-side pagination — all items are in the DOM

List Item #36
Client-side pagination — all items are in the DOM

List Item #37
Client-side pagination — all items are in the DOM

List Item #38
Client-side pagination — all items are in the DOM

List Item #39
Client-side pagination — all items are in the DOM

List Item #40
Client-side pagination — all items are in the DOM

List Item #41
Client-side pagination — all items are in the DOM

List Item #42
Client-side pagination — all items are in the DOM

List Item #43
Client-side pagination — all items are in the DOM

List Item #44
Client-side pagination — all items are in the DOM

List Item #45
Client-side pagination — all items are in the DOM

List Item #46
Client-side pagination — all items are in the DOM

List Item #47
Client-side pagination — all items are in the DOM

Server-Side Pagination

PHP renders <a href="…"> links for each page. The controller passes total, perPage, and currentPage from the database query, and the component builds the correct button set. Full-page reload on navigation (standard web behaviour).

AJAX Pagination

On each page change, JS calls the configured URL (with {page} and {perPage} tokens), then injects the HTML response into the target container. The endpoint may return plain HTML or a JSON object { html, total } to also update the total count. A loading state is applied to the target during fetch.

Loading first page…

Variants — Compact, Large, Alignment

Compact

Record #1

Record #2

Record #3

Record #4

Record #5

Record #6

Record #7

Record #8

Record #9

Record #10

Record #11

Record #12

Record #13

Record #14

Record #15

Record #16

Record #17

Record #18

Large, left-aligned, with first/last jump buttons

Label Position

The ->labelPosition() method controls where the "Showing X–Y of Z" label appears relative to the page buttons. Accepted values: 'left' (default), 'right', 'above', 'below', and 'none'. Calling this method automatically shows the label — no separate ->showInfo() call is needed.

above — label row above the buttons

below — label row below the buttons

right — label on the right, controls centred

none — label hidden, controls centred

Label Position

above — label row above the buttons

below — label row below the buttons

right — label on the right side (controls centred)

none — label hidden, controls centred

Interact with the client or AJAX pager above to see events here…

// --- CLIENT MODE (simplest) ---
// All items in DOM. Total auto-detected from child count.
<?= $m->list('taskList')->items($listItems) ?>
<?= $m->pagination('taskPager')
      ->target('taskList')
      ->perPage(10)
      ->showInfo(true)
      ->showSizeSelector([5, 10, 25]) ?>

// Items need data-pagination-item, or be direct children of target.
// Add it via attrs when building items:
['html' => '...', 'attrs' => ['data-pagination-item' => '']]

// --- SERVER MODE ---
// Controller passes total/page from DB query:
$total = $model->count();
$items = $model->paginate($page, $perPage);
// View:
<?= $m->pagination('pager')
      ->total($total)
      ->perPage($perPage)
      ->currentPage($page)
      ->mode('server')
      ->url('/tasks?page={page}&perPage={perPage}')
      ->showInfo(true)
      ->showFirstLast(true) ?>

// --- AJAX MODE ---
// Fetches URL on each page change, injects response into target.
// Response: plain HTML  OR  JSON { html: string, total: int }
<?= $m->pagination('pager')
      ->mode('ajax')
      ->url('/api/tasks?page={page}&perPage={perPage}')
      ->target('taskList')
      ->total($initialTotal)
      ->perPage(10)
      ->showInfo(true)
      ->autoLoad(true) ?>   // auto-fetch page 1 on init

// Variants:
->compact()
->large()
->align('left')   // 'center' (default) | 'left' | 'right'
->showFirstLast(true)
->maxButtons(9)

// Get pagination instance (auto-inited on DOMContentLoaded)
var pager = m.pagination('my-pager');

// Navigate programmatically
pager.goTo(3);
pager.next();
pager.prev();
pager.first();
pager.last();

// Update total (after AJAX fetch returns a count)
pager.setTotal(200);

// Change per-page size
pager.setPerPage(25);

// Read current state
var s = pager.getState();
// { page, perPage, total, totalPages, offset, limit }
console.log('Fetching:', s.offset, '+', s.limit);

// Refresh client-mode items after DOM mutation
pager.refresh();

// External trigger elements (e.g. custom Next button elsewhere in page)
// Just add data attributes — no JS needed:
// <button data-m-pagination="my-pager" data-page="5">Go to 5</button>

// Listen to page changes
document.getElementById('my-pager').addEventListener('m:pagination:change', function(e) {
    var d = e.detail;
    console.log('Page', d.page, 'of', d.totalPages,
                '| offset:', d.offset, 'limit:', d.limit);
    // Example: re-fetch a custom component
    m.list('taskList').refresh('/tasks?offset=' + d.offset + '&limit=' + d.limit);
});

// Ajax-loaded event
document.getElementById('my-pager').addEventListener('m:pagination:loaded', function(e) {
    console.log('Loaded page', e.detail.page, 'from', e.detail.url);
});

PHP PHP Methods (Fluent)

Method / Property	Parameters	Description
`$m->pagination($id)`	`Pagination`	Create a new pagination component.
`->total($n)`	`self`	Total number of items. In client mode, leave 0 for auto-count.
`->perPage($n)`	`self`	Items per page. Default: `10`.
`->currentPage($n)`	`self`	Current page (1-based). Default: `1`.
`->target($id)`	`self`	ID of the container whose children are paginated (client/ajax).
`->mode($m)`	`self`	`'client'` (default), `'server'`, or `'ajax'`.
`->url($template)`	`self`	URL template. Tokens: `{page}`, `{perPage}`. Required for server mode; optional for ajax auto-fetch.
`->showInfo()`	`self`	Show "Showing X\u2013Y of Z" info text at the left. Default: false.
`->labelPosition($pos)`	`self`	Set info label position and show it. `'left'` (default), `'right'`, `'above'`, `'below'`, `'none'`. Preferred over `->showInfo()` when position matters.
`->showSizeSelector($sizes)`	`self`	Show a per-page size selector. E.g. `[10, 25, 50]`.
`->align($a)`	`self`	Alignment: `'center'` (default), `'left'`, `'right'`.
`->maxButtons($n)`	`self`	Max page buttons including ellipsis. Default: `7`.
`->showFirstLast()`	`self`	Show « (first) and » (last) jump buttons. Default: false.
`->compact()`	`self`	Use smaller buttons.
`->large()`	`self`	Use larger buttons.
`->autoLoad()`	`self`	Ajax mode: fetch page 1 automatically on init. Default: false.

JS JS Methods

Method / Property	Parameters	Description
`m.pagination(id)`	`object\|null`	Get or create a pagination instance.
`p.goTo(n)`		Navigate to page n.
`p.next() / p.prev() / p.first() / p.last()`		Navigate relative pages.
`p.setTotal(n)`		Update total item count and re-render controls.
`p.setPerPage(n)`		Change per-page size and navigate to page 1.
`p.getState()`	`object`	Returns `{ page, perPage, total, totalPages, offset, limit }`.
`p.refresh()`		Re-discover items in target (client mode) and re-scan external triggers.
`p.element`	`HTMLElement`	The underlying `<nav>` DOM element.

EVENT Events

Event Name	Detail	Description
`m:pagination:change`	`{ page, perPage, total, totalPages, offset, limit }`	Fired on every page or per-page change. Use `offset` and `limit` in AJAX calls for SQL-style slicing.
`m:pagination:loaded`	`{ page, perPage, url }`	Fired after ajax auto-fetch completes and HTML has been injected.