vue-composition-pagination
is a ready to use composition-api
composable tool around axios to help you dealing with paginated APIs.
It is fully written in Typescript and supports types out of the box.
npm
npm install vue-composition-paginate
yarn
yarn add vue-composition-paginate
Given the following payload:
{
"data": [
{
"name": {
"title": "Miss",
"first": "Ninon",
"last": "Philippe"
},
"email": "ninon.philippe@example.com",
"id": {
"name": "INSEE",
"value": "2NNaN81837684 25"
}
},
{
"name": {
"title": "Mr",
"first": "Axel",
"last": "Skavhaug"
},
"email": "axel.skavhaug@example.com",
"id": {
"name": "FN",
"value": "11118811382"
}
},
{
"name": {
"title": "Monsieur",
"first": "Enrico",
"last": "Aubert"
},
"email": "enrico.aubert@example.com",
"id": {
"name": "AVS",
"value": "756.2544.6409.51"
}
}
// ...
],
"pagination": {
"page": 1,
"total": 624,
"resultsPerPage": 25,
"totalPage": 25
}
}
import usePaginate from 'vue-composition-paginate';
import myAxiosInstance from '@/utils/axios-instance';
export default defineComponent({
name: 'ListView',
setup() {
const paginate = usePaginate({
// It can also be the basic instance of axios
instance: myAxiosInstance,
url: 'http://api.project.local/documents', // Or '/documents' if your instance has a prefix
// Extract data from payload
dataTransformer: (response) => response.data,
// Extract total of pages from the payload
totalPageTransformer: (response) => response.pagination.totalPage,
});
// Initiate the first call
paginate.goToPage(1);
return {
// See below for details about this object
...paginate,
};
},
});
If you are using Typescript, you can also indicate through generics the type of the payload:
import myAxiosInstance from '@/utils/axios-instance';
interface User {
id: {
name: string;
value: string;
};
name: {
title: string;
first: string;
last: string;
};
email: string;
}
interface Payload {
data: User[];
pagination: {
total: number;
resultsPerPage: number;
page: number;
totalPage: number;
};
}
export default defineComponent({
name: 'ListView',
setup() {
// You will be able to benefit from type inference on properties of the `paginate` object
// and `usePaginate` options.
const paginate = usePaginate<User, Payload>({
instance: myAxiosInstance,
url: 'http://api.project.local/documents',
dataTransformer: (response) => response.data,
totalPageTransformer: (response) => response.pagination.totalPage,
});
paginate.goToPage(1);
return {
// See below for details about this object
...paginate,
};
},
});
Name | Type | Required | Default | Description |
---|---|---|---|---|
instance | AxiosInstance |
true |
— | Axios instance used to make requests |
url | String |
true |
— | URL of the resources to fetch. If you use a custominstance with a prefix, you can just use the resource path /documents for example. |
totalPageTransformer | (payload: Payload) => number |
true |
— | Function called to extract the total number of pages out of the payload |
dataTransformer | (payload: Payload) => T[] |
false |
(results) => results |
Function called to extract the paginated results data out of the payload |
totalTransformer | (payload: Payload) => number |
false |
() => {} |
Function called to extract the total number of items out of the payload |
pageField | String |
false |
"page" |
Name of the field in the query to specify the page we want to retrieve |
onUpdate | `(page?: number, params?: Record<string, string | number | boolean>) => void` | false |
currentPage | Number |
false |
1 |
Defines the current page to generate a range of pages around the current one |
resultsPerPage | Ref<number> | number |
false |
25 |
Sets the limit of results to fetch at once |
limitField | String |
false |
"limit" |
Name of the field in the query to specify the maximum number of items we want to fetch |
range | Number |
false |
5 |
Number of pages to display around the current one |
includeLimits | Boolean |
false |
true |
Whether to add first and last pages in the page list around the current one |
params | Ref<Record<string, number | boolean | string>> |
false |
{} |
Additional query params to add in the request. Must be a ref or a computed value, returning an object whose depth is 1. |
The function will return an object that is destructurable containing the following properties:
Name | Type | Description |
---|---|---|
data | Ref<T[]> |
Array of fetched results |
pages | Ref<number[]> |
Generated list of pages around the current page (ex: [1, 4, 5, <6>, 7, 8, 20] ) |
currentPage | Ref<number> |
Reactive reference of the current page |
goToPage | (page: number) => Promise<Payload> |
Function to call to go to a specific page. can be used to refresh the current query |
previous | (page: number) => Promise<Payload> |
Function to call to go to the previous page |
next | (page: number) => Promise<Payload> |
Function to call to go to the next page |
resultsPerPage | Ref<number> |
Reactive reference of the limit of results per page |
total | Ref<number> | undefined |
Reactive reference of the total number of items. undefined if no function to extract the total number of items is provided |
lastPage | Ref<number> |
Reactive reference of the number of the last page |
loading | Ref<boolean> |
Reactive reference of HTTP request completion state |
Thanks goes to these wonderful people (emoji key):
Nathael Arki 🤔 |
This project follows the all-contributors specification. Contributions of any kind welcome!