Vue Pagination Headless

August 2, 2025 · View on GitHub

Headless and non-style pagination for Vue 3. DEMO

Vue Pagination

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