Vue Composition Paginate

Introduction

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.

Installation

npm

npm install vue-composition-paginate

yarn

yarn add vue-composition-paginate

Usage

Given the following payload:

{
  "data": [
    {
      "name": {
        "title": "Miss",
        "first": "Ninon",
        "last": "Philippe"
      },
      "email": "[email protected]",
      "id": {
        "name": "INSEE",
        "value": "2NNaN81837684 25"
      }
    },
    {
      "name": {
        "title": "Mr",
        "first": "Axel",
        "last": "Skavhaug"
      },
      "email": "[email protected]",
      "id": {
        "name": "FN",
        "value": "11118811382"
      }
    },
    {
      "name": {
        "title": "Monsieur",
        "first": "Enrico",
        "last": "Aubert"
      },
      "email": "[email protected]",
      "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,
    };
  },
});

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 | (payload: Payload) => number | false | (page?: number) => void | Function to call everytime the current page value is edited. 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> \| 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. |

Return values

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 |