(original) (raw)

Vue Pagination Headless

Headless and non-style pagination for Vue 3. DEMO

Vue Pagination
- Installation
- Getting Started
  * Create A Simple Pagination
- Parameters
  * Max Items
  * Page Route and LinkTag
  * Page Click
- Custom Slots
  * Page Icons and Numbers
  * Page Items
- Custom UI by Composable
- Interfaces
  * Props
  * Events
  * Slots
- Contribution

Installation

npm i @asika32764/vue-pagination --save

OR

yarn add @asika32764/vue-pagination

Getting Started

Use bundler and Vue SFC:

Include JS file.

ES Module

Create A Simple Pagination

You will see a pagination with empty style.

This is an example for Bootstrap style:

class="pagination"
item-class="page-item"
link-class="page-link"
active-class="active"
disabled-class="disabled"

You could add your own class or style to this pagination components for every UI framework.

Parameters

Max Items

Configure max items shows on pagination, default is 5:

The example that we limit it only 3 items one time:

Page Route and LinkTag

Simply add route parameter to create link for every page items:

The return value can be a string for <a href="..."> or any types. You can customize the link tag by:

The accepted link-tag value includes:

a => Page item will be <a> link and route will be href attribute.
button => Page item will be <button> and without route, you must use @page-click to handle click event.
router-link, NuxtLink or any other component => The route will be to="...." props.

This is an example for VueRouter, you must install vue-router first to use therouter-link component.

You can provide true to route prop that component will auto use { query: { page: item.page } } as route:

Page Click

If you want to do something on page clicked, use @page-click event:

Custom Slots

Page Icons and Numbers

{{ item.page }}

Page Items

If you need to build your own pagination items, use page-item slot to implement it.

The PageItem and PageType interfaces:

interface PageItem { type: PageType; page: number; active: boolean; disabled: boolean; }

enum PageType { FIRST = 'first', PREVIOUS = 'previous', LOWER = 'lower', CURRENT = 'current', HIGHER = 'higher', NEXT = 'next', LAST = 'last', }

Custom UI by Composable

Vue-Pagination provides a usePagination() composable that you can implement your custom pagination UI.

You can send empty options and configure options later, every ref variables can be changed and pagination will auto re-compile.

const { total, perPage, currentPage, maxItems, pages, pagesCount, } = usePagination();

total.value = 150; perPage.value = 10;

If you are building a pagination wrapper, you can send MaybeRefOrGetter as options, Vue-Pagination will auto listen it.

const props = defineProps<{ total: number; perPage: number; maxItems?: number; }>();

const currentPage = defineModel({ default: 1 });

const { pages } = usePagination({ total: () => props.total, // Getter function perPage: () => props.perPage, currentPage, // ref maxItems: () => props.maxItems });

// Pages will auto refresh after any options changed. for (var page of pages.value) { // ... }

Interfaces

Props

Prop	Type	Description
total	number	The total rows number.
per-page	number	The number per-page.
max-items	?number	The max items shows once time.
link-tag	any	The link tag name or component.
route	((page: PageItem) => any) or boolean	The route link logic.
item-class	any	The page item class.
link-class	any	The page link class.
active-class	any	The current page class.
disabled-class	any	The disabled class.

Events

Event	Interface	Description
page-click	(e: MouseEvent, item: PageItem)	The page clicked event.
pages-updated	([currentPage, total, perPage])	When currentPage, total, perPage any one changed
update:modelValue	(page: number)	When currentPage changed

Slots

Slot	Values	Description
first-icon	{ item: PageItem, to: any }	The item text for first link.
previous-icon	{ item: PageItem, to: any }	The item text for previous link.
next-icon	{ item: PageItem, to: any }	The item text for next link.
last-icon	{ item: PageItem, to: any }	The item text for last link.
page	{ item: PageItem, to: any }	The item text for every page links.
page-item	{ item: PageItem, to: any }	The page item HTML for every page items.

Contribution

Run:

The vite server will raise a doc site on http://localhost:5173

The doc site entry file is located at: src/docs/main.ts.

You can add your code at this file to test your changes, remeber don't commit your test code to git.

After developed, run this command to build dist files.