Vue Ads Pagination Component

Common errors

• [Vue warn]: Unknown custom element: <vue-ads-pagination> - did you register the component correctly?

  cause The `VueAdsPagination` component was not imported and/or registered in the `components` option of the Vue instance or parent component where it is being used.
  fix Ensure `import VueAdsPagination from 'vue-ads-pagination';` is present in your script and `VueAdsPagination` is listed in the `components: {}` object of your Vue component.

• Property 'total-items' is missing in type 'VueAdsPaginationProps'

  cause The `total-items` prop is marked as required by the component but was not provided, or was provided with an incorrect name (e.g., `totalItems` instead of `total-items`).
  fix Add the `:total-items="yourTotalCount"` prop to the `<vue-ads-pagination>` component, ensuring its value is a number representing the total count of items.

• TypeError: Cannot read properties of undefined (reading 'start') or TypeError: Cannot read property 'start' of undefined

  cause This error typically occurs when attempting to access properties of the scoped slot (like `props.start`, `props.end`, `props.total`) without correctly defining the `slot-scope` attribute on the `<template>` tag.
  fix Ensure your custom slot template uses `slot-scope="props"` (Vue 2) or `#default="props"` (Vue 2.6+ / Vue 3) to correctly destructure the scoped slot properties.

Warnings

• gotcha The `page` property is zero-based, meaning the first page is 0, the second is 1, and so on. Ensure your application logic and any user-facing page numbers account for this indexing difference.
  Fix: When binding `page`, pass a value that is 0-based. If displaying to a user, increment the `page` value by 1.
• gotcha The `page` prop is not automatically updated by the component. It functions as a one-way prop. You must listen to the `page-change` event and explicitly update the `page` data property in your parent component to reflect the new active page.
  Fix: Use an event listener like `@page-change="currentPage = $event"` or a method that updates your bound `page` data property.
• gotcha The default styles for `vue-ads-pagination` are not automatically included. You must manually import `vue-ads-pagination/dist/vue-ads-pagination.css` in your project's main entry file or a root component.
  Fix: Add `import 'vue-ads-pagination/dist/vue-ads-pagination.css';` to your main JavaScript/TypeScript file (e.g., `main.ts` or `main.js`) or within a `<style>` block in a root component.
• gotcha For the default button rendering to display icons (e.g., for 'first', 'last', 'next', 'previous' page buttons), the component's internal templates assume the availability of Font Awesome CSS. If Font Awesome is not included in your project, these icons will not render.
  Fix: Install `@fortawesome/fontawesome-free` and import its CSS (e.g., `import '@fortawesome/fontawesome-free/css/all.css';`) in your project, or override the 'buttons' slot with your custom button components that do not rely on Font Awesome.

Install

• npm install vue-ads-pagination npm
• yarn add vue-ads-pagination yarn
• pnpm add vue-ads-pagination pnpm

Imports

• VueAdsPagination
  wrong:

  const VueAdsPagination = require('vue-ads-pagination');

  correct:

  import VueAdsPagination from 'vue-ads-pagination';

  This is the default export of the main pagination component. While CommonJS `require` might work in some setups, ESM `import` is the standard for modern Vue projects.
• VueAdsPageButton
  wrong:

  import VueAdsPageButton from 'vue-ads-pagination/VueAdsPageButton';

  correct:

  import { VueAdsPageButton } from 'vue-ads-pagination';

  This is a named export for the individual page button component. It's useful if you want to reuse or customize the default button logic independently.
• CSS
  wrong:

  import 'vue-ads-pagination/src/vue-ads-pagination.css';

  correct:

  import 'vue-ads-pagination/dist/vue-ads-pagination.css';

  The default styles for the pagination component are not automatically injected and must be imported separately in your main application file or a root component to apply styling.

Quickstart

This example demonstrates how to integrate `VueAdsPagination` and `VueAdsPageButton` into a Vue component. It shows binding properties like `total-items`, `page`, and handling `page-change` and `range-change` events. The example also illustrates how to customize the display of item range information and individual pagination buttons using scoped slots.

<template>
    <div id="app">
        <vue-ads-pagination
            :total-items="200"
            :max-visible-pages="5"
            :page="currentPage"
            :loading="loading"
            @page-change="pageChange"
            @range-change="rangeChange"
        >
            <template slot-scope="props">
                <div class="vue-ads-pr-2 vue-ads-leading-loose">
                    Items {{ props.start }} to {{ props.end }} of {{ props.total }}
                </div>
            </template>
            <template
                slot="buttons"
                slot-scope="props"
            >
                <vue-ads-page-button
                    v-for="(button, key) in props.buttons"
                    :key="key"
                    v-bind="button"
                    @page-change="currentPage = button.page"
                />
            </template>
        </vue-ads-pagination>
        <p>Current Page: {{ currentPage + 1 }}</p>
    </div>
</template>

<script lang="ts">
import Vue from 'vue';
import '../node_modules/@fortawesome/fontawesome-free/css/all.css'; // For default button icons
import 'vue-ads-pagination/dist/vue-ads-pagination.css'; // For default styling

import VueAdsPagination, { VueAdsPageButton } from 'vue-ads-pagination';

export default Vue.extend({
    name: 'App',
    
    components: {
        VueAdsPagination,
        VueAdsPageButton,
    },

    data () {
        return {
            loading: false,
            currentPage: 4, // 0-based, so 5th page
        };
    },

    methods: {
        pageChange (page: number) {
            this.currentPage = page; // Update the bound prop
            console.log('Page changed to:', page + 1);
        },
        
        rangeChange (start: number, end: number) {
            console.log('Displaying items from', start + 1, 'to', end + 1);
        },
    },
});
</script>