Skip to content

Latest commit

 

History

History
473 lines (361 loc) · 12.1 KB

README.md

File metadata and controls

473 lines (361 loc) · 12.1 KB
Raw

Vue Pagination

Version License

A very simple pagination without any style that supports developers to custom for every project. DEMO

Installation

npm i @asika32764/vue-pagination --save

# OR

yarn add @asika32764/vue-pagination

Getting Started

Use bundler and Vue SFC:

<script setup lang="ts">
  import VuePagination from '@asika32764/vue-pagination';
</script>

Include JS file.

<script src="path/to/package/dist/vue-pagination.umd.js"></script>

<script>
  const app = Vue.createApp();
  app.component('vue-pagination', VuePagination);
</script>

ES Module

<script type="module">
  import VuePagination from 'path/to/package/dist/vue-pagination.umd.js';
  import { createApp } from 'path/to/vue.umd.js';

  const app = createApp();
  app.component('vue-pagination', VuePagination);
</script>

Create A Simple Pagination

<script setup lang="ts">
  import VuePagination from '@asika32764/vue-pagination';

  const items = ref([]);
  const total = ref(0);
  const perPage = ref(15);
  const currentPage = ref(1);

  const res = axios.get('item/list', { params: { limit: perPage.value, page: currentPage } });

  items.value = res.data.items;
  total.value = res.data.totalRows;
</script>

<template>
  <VuePagination
    v-model="currentPage"
    :total="total"
    :per-page="perPage"
  />
</template>

You will see a pagination with empty style.

This is an example for Bootstrap style:

<template>
  <VuePagination
    v-model="currentPage"
    :total="total"
    :per-page="perPage"

    class="pagination"
    item-class="page-item"
    link-class="page-link"
    active-class="active"
    disabled-class="disabled"
  />
</template>

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:

<VuePagination
  :max-items="3"
/>

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:

<script setup lang="ts">
  import type { PageItem } from '@asika32764/vue-pagination';

  function createLink(item: PageItem) {
    return `blog/articles?page=${item.page}`;
  }
</script>

<template>
  <VuePagination
    :route="createLink"
  />
</template>

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

<VuePagination
  :route="createLink"
  :link-tag="'button' or 'router-link'"
/>

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 the router-link component.

<script setup lang="ts">
  import type { PageItem } from '@asika32764/vue-pagination';

  function createLink(item: PageItem) {
    return { query: { page: item.page } };
  }
</script>

<template>
  <VuePagination
    :route="createLink"
    link-tag="router-link"
  />
</template>

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

<VuePagination
  :route="true"
  link-tag="router-link"
/>

Page Click

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

<script setup lang="ts">
  import type { PageItem } from '@asika32764/vue-pagination';

  function onPageClick(event: MouseEvent, item: PageItem) {
    currentPage.value = item.page;
  }
</script>

<template>
  <VuePagination
    @page-click="onPageClick"
  />
</template>

Custom Slots

Page Icons and Numbers

<script setup lang="ts">
  import { faBackward, faBackwardStep, faForward, faForwardStep } from '@fortawesome/free-solid-svg-icons';
  import { FontAwesomeIcon } from '@fortawesome/vue-fontawesome';

</script>

<template>
  <VuePagination
    v-model="page"
    :total="total"
    :per-page="perPage"
    class="pagination"
    item-class="page-item"
    link-class="page-link"
    active-class="active"
    disabled-class="disabled"
  >
    <template #first-icon>
      <FontAwesomeIcon :icon="faBackwardStep" />
    </template>
    <template #previous-icon>
      <FontAwesomeIcon :icon="faBackward" />
    </template>
    <template #next-icon>
      <FontAwesomeIcon :icon="faForward" />
    </template>
    <template #last-icon>
      <FontAwesomeIcon :icon="faForwardStep" />
    </template>
    <template #page="{ item }">
      <em>{{ item.page }}</em>
    </template>
  </VuePagination>
</template>

Page Items

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

<script setup lang="ts">
  import { PageType } from '@asika32764/vue-pagination';
  import { faBackward, faBackwardStep, faForward, faForwardStep } from '@fortawesome/free-solid-svg-icons';
  import { FontAwesomeIcon } from '@fortawesome/vue-fontawesome';
</script>

<template>
  <VuePagination
    v-model="page"
    :total="total"
    :per-page="perPage"
    class="pagination"
    item-class="page-item"
    link-class="page-link"
    active-class="active"
    disabled-class="disabled"
  >
    <template #page-item="{ item, to }">
      <div class="page-item">
        <NuxtLink :to="to" class="page-link"
          :class="{ active: item.active, disabled: item.disabled }"
        >
          <FontAwesomeIcon v-if="item.type === PageType.FIRST" :icon="faBackwardStep" />
          <FontAwesomeIcon v-else-if="item.type === PageType.PREVIOUS" :icon="faBackward" />
          <FontAwesomeIcon v-else-if="item.type === PageType.NEXT" :icon="faForward" />
          <FontAwesomeIcon v-else-if="item.type === PageType.LAST" :icon="faForwardStep" />
          <span v-else>{{ item.page }}</span>
        </NuxtLink>
      </div>
    </template>
  </VuePagination>
</template>

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.

<script setup lang="ts">
import { usePagination, PageType } from '@asika32764/vue-pagination';

const {
  total,
  perPage,
  currentPage,
  maxItems,
  pages,
  pagesCount,
} = usePagination({ total: 150, perPage: 10, currentPage: 1 });

</script>

<template>
  <div class="pagination">
    <div v-for="item of pages" class="page-item">
      <a href="javascript:void(0)" class="page-link"
        :class="{ active: item.active, disabled: item.disabled }"
        @click.prevent="currentPage = item.page"
      >
        <FontAwesomeIcon v-if="item.type === PageType.FIRST" :icon="faBackwardStep" />
        <FontAwesomeIcon v-else-if="item.type === PageType.PREVIOUS" :icon="faBackward" />
        <FontAwesomeIcon v-else-if="item.type === PageType.NEXT" :icon="faForward" />
        <FontAwesomeIcon v-else-if="item.type === PageType.LAST" :icon="faForwardStep" />
        <span v-else>{{ item.page }}</span>
      </a>
    </div>
  </div>
</template>

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:

yarn install
yarn dev

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.

yarn build:prod