https://github.com/noook/vue-composition-paginate
A Vue Composition plugin that handles reactive pagination and HTTP requests with filters
https://github.com/noook/vue-composition-paginate
hooks pagination typescript vue vue-composition-api vuejs
Last synced: 9 months ago
JSON representation
A Vue Composition plugin that handles reactive pagination and HTTP requests with filters
- Host: GitHub
- URL: https://github.com/noook/vue-composition-paginate
- Owner: noook
- Created: 2020-04-28T11:21:23.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2020-10-20T20:30:52.000Z (about 5 years ago)
- Last Synced: 2025-03-18T15:59:05.927Z (9 months ago)
- Topics: hooks, pagination, typescript, vue, vue-composition-api, vuejs
- Language: TypeScript
- Homepage:
- Size: 441 KB
- Stars: 11
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
[](https://badge.fury.io/js/vue-composition-paginate)
[](#contributors-)
# Vue Composition Paginate
## Introduction
`vue-composition-pagination` is a ready to use [composition-api](https://github.com/vuejs/composition-api/)
composable tool around [axios](https://github.com/axios/axios) to help you dealing with paginated APIs.
It is fully written in Typescript and supports types out of the box.
# Installation
**npm**
```bash
npm install vue-composition-paginate
```
**yarn**
```bash
yarn add vue-composition-paginate
```
# Usage
Given the following payload:
```jsonc
{
"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
}
}
```
```javascript
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](https://www.typescriptlang.org/docs/handbook/generics.html)
the type of the payload:
```javascript
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({
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,
};
},
});
```
# Options
| 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) => void` | `false` | `() => {}` | Function to call everytime the current data is updated. May be useful to update the URL query parameters or to trigger other actions. |
| currentPage | `Number` | `false` | `1` | Defines the current page to generate a range of pages around the current one |
| resultsPerPage | `Ref \| 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>` | `false` | `{}` | Additional query params to add in the request. Must be a `ref` or a `computed` value, returning an object whose depth is 1. |
# Return values
The function will return an object that is destructurable containing the following properties:
| Name | Type | Description |
| -------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| data | `Ref` | Array of fetched results |
| pages | `Ref` | Generated list of pages around the current page (ex: `[1, 4, 5, <6>, 7, 8, 20]`) |
| currentPage | `Ref` | Reactive reference of the current page |
| goToPage | `(page: number) => Promise` | Function to call to go to a specific page. can be used to refresh the current query |
| previous | `(page: number) => Promise` | Function to call to go to the previous page |
| next | `(page: number) => Promise` | Function to call to go to the next page |
| resultsPerPage | `Ref` | Reactive reference of the limit of results per page |
| total | `Ref \| undefined` | Reactive reference of the total number of items. `undefined` if no function to extract the total number of items is provided |
| lastPage | `Ref` | Reactive reference of the number of the last page |
| loading | `Ref` | Reactive reference of HTTP request completion state |
## Contributors ✨
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
