{"id":13424232,"url":"https://github.com/TahaSh/vue-paginate","last_synced_at":"2025-03-15T18:34:18.823Z","repository":{"id":55157864,"uuid":"52541340","full_name":"TahaSh/vue-paginate","owner":"TahaSh","description":"A simple vue.js plugin to paginate data","archived":false,"fork":false,"pushed_at":"2021-01-06T11:40:45.000Z","size":415,"stargazers_count":594,"open_issues_count":65,"forks_count":103,"subscribers_count":21,"default_branch":"master","last_synced_at":"2025-02-28T10:02:01.918Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TahaSh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-02-25T16:54:08.000Z","updated_at":"2024-10-18T19:02:34.000Z","dependencies_parsed_at":"2022-08-14T13:51:07.454Z","dependency_job_id":null,"html_url":"https://github.com/TahaSh/vue-paginate","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TahaSh%2Fvue-paginate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TahaSh%2Fvue-paginate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TahaSh%2Fvue-paginate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TahaSh%2Fvue-paginate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TahaSh","download_url":"https://codeload.github.com/TahaSh/vue-paginate/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243775789,"owners_count":20346262,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T00:00:50.475Z","updated_at":"2025-03-15T18:34:13.798Z","avatar_url":"https://github.com/TahaSh.png","language":"JavaScript","funding_links":[],"categories":["Awesome Vue.js [![Awesome](https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg)](https://github.com/sindresorhus/awesome)","JavaScript","UI Utilities [🔝](#readme)","UI组件","UI实用程序","Components \u0026 Libraries","UI Components","UI Utilities","Awesome Vue.js"],"sub_categories":["Libraries \u0026 Plugins","分页","UI Utilities","Pagination"],"readme":"# vue-paginate [![CDNJS version](https://img.shields.io/cdnjs/v/vue-paginate.svg)](https://cdnjs.com/libraries/vue-paginate)\n\n\u003e This version only works with Vue 2.0. For Vue 1.0, check out the [1.0 branch](https://github.com/TahaSh/vue-paginate/tree/1.0).\n\nThe idea of `vue-paginate` is pretty simple. You give it an array of items; specify how many items per page; then get your list of items paginated!\n\n## Setup\n\n```\nnpm install vue-paginate --save\n```\n\nYou have two ways to setup `vue-paginate`:\n\n#### CommonJS (Webpack/Browserify)\n\n- ES6\n\n```js\nimport VuePaginate from 'vue-paginate'\nVue.use(VuePaginate)\n```\n\n- ES5\n\n```js\nvar VuePaginate = require('vue-paginate')\nVue.use(VuePaginate)\n```\n\n#### Include\n\nInclude it directly with a `\u003cscript\u003e` tag. In this case, you don't need to write `Vue.use(VuePaginate)`, this will be done automatically for you.\n\n## Usage\n\n\u003e Before you start, you may want to check a live example on [jsfiddle](https://jsfiddle.net/taha_sh/hmapx482/).\n\n`vue-paginate` consists of two main components: `Paginate` and `PaginateLinks`. And both get registered globally once the plugin is installed.\n\nTo paginate any list of data, we have to follow these three small steps:\n\n1. Register the name of the paginated list.\n2. Use `Paginate` component to paginate and display the paginated list.\n3. Use `PaginateLinks` component to display the links for the pagination.\n\nNow, let’s see them in an example:\n\n### Example\n\nIn this example, we have a small list of items registered in our data list.\n \n``` js\nnew Vue({\n  el: '#app',\n  data: {\n    langs: ['JavaScript', 'PHP', 'HTML', 'CSS', 'Ruby', 'Python', 'Erlang']\n  }\n})\n```\n\nNow, let’s see how we can paginate this list to display two items per page.\n\nFirst step is to register the name of our future paginated list. We register it by adding it to an array called `paginate`.\n\n``` js\nnew Vue({\n  el: '#app',\n  data: {\n    langs: ['JavaScript', 'PHP', 'HTML', 'CSS', 'Ruby', 'Python', 'Erlang'],\n    paginate: ['languages']\n  }\n})\n```\n\nNote that you can name it the same as the original list – I named it differently here just for the sake of clarity.\n\nSecond step is to use the `Paginate` component to paginate the list. Since it was globally registered by the plugin, you don’t have to import it.\n\nThis component requires at least two props to be passed. The `name` of the registered paginated list – `languages` in this case. And the `list` that you want to paginate – `langs` in this case.\n\nAfter that, you start using the paginated list inside the body of that `\u003cpaginate\u003e` component. And, you get access to the paginated list using the method `paginated('languages')`.\n\nHere’s how it looks in action:\n\n``` html\n\u003cpaginate\n  name=\"languages\"\n  :list=\"langs\"\n  :per=\"2\"\n\u003e\n  \u003cli v-for=\"lang in paginated('languages')\"\u003e\n    {{ lang }}\n  \u003c/li\u003e\n\u003c/paginate\u003e\n```\n\nNote how we specified the number of items per page using the `per` prop. If we didn’t specify it here, it would use the default value instead, which is `3` items per page.\n\nThat’s it! Now your list has been paginated successfully. And you still have access to the original `langs` list if you need it.\n\nHowever, we still don’t have a way to navigate through those pages. Here’s where `PaginateLinks` component comes into play.\n\nAll that component needs to know is the name of the registered paginated list. We pass that using its `for` prop. Like this:\n\n``` html\n\u003cpaginate-links for=\"languages\"\u003e\u003c/paginate-links\u003e\n```\n\nSo, that was the third step!\n\n### Rendering PaginateLinks asynchronously\n\nA common error users get when using this plugin is this:\n\n\u003e [vue-paginate]: \u003cpaginate-links for=\"items\"\u003e can't be used without its companion \u003cpaginate name=\"items\"\u003e\n\nThis error occurs for two reasons:\n1. You haven't added your `\u003cpaginate\u003e` yet! — Just add it and it will be fixed.\n2. Or your defined `\u003cpaginate\u003e` component is rendered after its companion `\u003cpaginate-links\u003e` has been rendered (usually happens when using `v-if` on `\u003cpaginate\u003e` or on one of its parents)\n\nHere's some contrived example of the second case:\n\n``` html\n\u003cpaginate v-if=\"shown\"\n  name=\"items\"\n  :list=\"items\"\n\u003e\n  \u003cli v-for=\"item in paginated('items')\"\u003e\n    {{ item }}\n  \u003c/li\u003e\n\u003c/paginate\u003e\n\u003cpaginate-links for=\"items\"\u003e\u003c/paginate-links\u003e\n```\n\n``` js\nnew Vue({\n  el: '#app',\n  data: {\n    langs: ['JavaScript', 'PHP', 'HTML', 'CSS', 'Ruby', 'Python', 'Erlang'],\n    paginate: ['languages'],\n    shown: false\n  },\n  mounted () {\n    setTimeout(() =\u003e {\n      this.shown = true\n    }, 1000)\n  }\n})\n```\n\nIf you try this example in the browser, you'll see the error described in this section. And the reason for that is because our `PaginateLinks` component can't find its companion `Paginate` component to show the links for — since it takes a complete second to render itself.\n\nTo fix this issue we have to tell our `PaginateLinks` to wait for its companion `Paginate` component to be rendered first. And we can do that simply by using `:async=\"true\"` on `\u003cpaginate-links\u003e`.\n\n``` html\n\u003cpaginate-links for=\"items\" :async=\"true\"\u003e\u003c/paginate-links\u003e\n```\n*So the bottom line is this: `\u003cpaginate\u003e` component should always be rendered before `\u003cpaginate-links\u003e` component.*\n\n### Using it inside a component's slot\n\n`Paginate` and `PaginateLinks` components get their current state from the parent component they're used in. You can find that state defined inside an object called `paginate`. For example, if your pagination is named `languages`, its state will be defined inside `paginate.languages`.\n\nBut what if those components are used inside a [slot](https://vuejs.org/v2/guide/components-slots.html#Slot-Content)? In this case, its parent component will be the slot's component (not the component it's defined in).\n\nIn this case we have to tell our pagination components where they can find the component that contains their state. We can do so using the `container` prop.\n\nAlthough both components, `Paginate` and `PaginateLinks`, use the same prop name, they take different values. `Paginate` component just needs the reference to the parent component that has its state. That value is usually `this`.\n\n`PaginateLinks`, however, takes an object with two values: `state` and `el`.\n\n`state` takes the current state object of the pagination. This value can be, for example, `paginate.languages`.\n\nFor `el` we should pass a reference to the component that contains `Paginate` component. In most cases it will be the component with the slot. For example: `$refs.layout`.\n\n#### Example\n\nNote: this example is based on the previous example.\n\n``` html\n\u003cdiv id=\"app\"\u003e\n  \u003clayout ref=\"layout\"\u003e\n    \u003cpaginate\n      name=\"languages\"\n      :list=\"langs\"\n      :per=\"2\"\n      :container=\"this\"\n    \u003e\n      \u003cli v-for=\"lang in paginated('languages')\"\u003e\n        {{ lang }}\n      \u003c/li\u003e\n    \u003c/paginate\u003e\n    \u003cpaginate-links\n      for=\"languages\"\n      :container=\"{\n        state: paginate.languages,\n        el: $refs.layout\n      }\"\n    /\u003e\n  \u003c/layout\u003e\n\u003c/div\u003e\n```\n\n### Types of paginate links\n\n`vue-paginate` provides us with three different types of pagination links:\n\n1. Full list of links. This is the default behavior, which displays all available page links from page 1 to N.\n2. Simple links. It contains only two links: *Previous* and *Next*.\n3. Limited links. It limits the number of displayed links, and provides left and right arrows to help you navigate between them.\n\n#### Full links\n\nTo use this you don’t have to do anything; this is the default behavior.\n\n#### Simple links\n\nFor this, we use the `simple` prop, which accepts an object that contains the names of the *Previous* and *Next* links. For example:\n\n``` html\n\u003cpaginate-links\n  for=\"languages\"\n  :simple=\"{\n    prev: 'Back',\n    next: 'Next'\n  }\"\n\u003e\u003c/paginate-links\u003e\n```\n\n\n#### Limited links\n\nTo activate this mode, you just need to specify the limit using the `limit` prop. Like this:\n\n``` html\n\u003cpaginate-links\n  for=\"languages\"\n  :limit=\"2\"\n\u003e\u003c/paginate-links\u003e\n```\n\n### Step Links\n\nAs in simple links, you can have next/previous links — which I call step links — in full links and limited links. To add them, use `:show-step-links=\"true\"` prop on the `PaginateLinks` component you want. For example:\n\n``` html\n\u003cpaginate-links\n  for=\"languages\"\n  :show-step-links=\"true\"\n\u003e\u003c/paginate-links\u003e\n```\n\n#### Customizing step links\n\nThe default symbols for the step links are `«` for previous and `»` for next. But, of course, you can change them to what you want using the `:step-links` prop, like this:\n\n``` html\n\u003cpaginate-links for=\"languages\"\n  :show-step-links=\"true\"\n  :step-links=\"{\n    next: 'N',\n    prev: 'P'\n  }\"\n\u003e\u003c/paginate-links\u003e\n```\n\n### Listening to links @change event\n\nWhen the current page changes, `PaginateLinks` emits an event called `change` to inform you about that. It also passes the switched page numbers with it, if you need them.\n\n``` html\n\u003cpaginate-links\n  for=\"languages\"\n  @change=\"onLangsPageChange\"\n\u003e\u003c/paginate-links\u003e\n```\n\n``` js\nmethods: {\n  onLangsPageChange (toPage, fromPage) {\n    // handle here…\n  }\n}\n```\n\n### Navigate pages programmatically\n\n`Paginate` component exposes a method that allows you to go to a specific page manually (not through `PaginateLinks` component). That method is called `goToPage(pageNumber)`.\n\nTo access this method, you need to get an access to your `\u003cpaginate\u003e` component instance using `ref` property.\n\nHere's an example:\n\n``` html\n\u003cpaginate ref=\"paginator\"\n  name=\"items\"\n  :list=\"items\"\n\u003e\n  \u003cli v-for=\"item in paginated('items')\"\u003e\n    {{ item }}\n  \u003c/li\u003e\n\u003c/paginate\u003e\n\u003cbutton @click=\"goToSecondPage\"\u003eGo to second page\u003c/button\u003e\n```\n\n``` js\nmethods: {\n  goToSecondPage () {\n    if (this.$refs.paginator) {\n      this.$refs.paginator.goToPage(2)\n    }\n  }\n}\n```\n\n### Displaying page items count (`X-Y of Z`)\n\nA common need for paginated lists is to display the items count description of the currently viewed items. It's usually displayed in this format `X-Y of Z` (e.g. `1-3 of 14`).\n\nYou can get that from your `\u003cpaginate\u003e` component instance's `pageItemsCount` computed property. And in order to use that, you have to get an access to that component instance using `ref` property.\n\nAn example:\n\n``` html\n\u003cpaginate ref=\"paginator\"\n  name=\"items\"\n  :list=\"items\" \n\u003e\n  \u003cli v-for=\"item in paginated('items')\"\u003e\n    {{ item }}\n  \u003c/li\u003e\n\u003c/paginate\u003e\n\u003cpaginate-links for=\"items\"\u003e\u003c/paginate-links\u003e\n\n\u003cspan v-if=\"$refs.paginator\"\u003e\n  Viewing {{$refs.paginator.pageItemsCount}} results\n\u003c/span\u003e\n```\n\nAn important thing to note here is `v-if=\"$refs.paginator\"`. We needed to do that check to make sure our `\u003cpaginate\u003e` component instance is completely rendered first. Otherwise, we'll get this error:\n\n`Cannot read property 'pageItemsCount' of undefined\"`\n\n### Paginate container\n\nThe default element `vue-paginate` uses for the `\u003cpaginate\u003e` container is `UL`. But, of course, you can change it to whatever you want using the `tag` prop. And the same is true for its class using the `class` prop.\n\n``` html\n\u003cpaginate\n  name=\"languages\"\n  :list=\"langs\"\n  :per=\"2\"\n  tag=\"div\"\n  class=\"paginate-langs\"\n\u003e\n  \u003cli v-for=\"lang in paginated('languages')\"\u003e\n    {{ lang }}\n  \u003c/li\u003e\n\u003c/paginate\u003e\n```\n\n### Updating the full list\n\nSince this plugin is built using the components system, you get all the flexibility and power that regular Vue components provide. I’m talking here specifically about the reactivity system.\n\nSo, when you want to update the original list (e.g. `langs`), just update it; everything will work seamlessly!\n\n### Filtering the paginated list\n\nThere’s nothing special the plugin does to support list filtering. It’s your responsibility to filter the list you pass to `\u003cpaginate\u003e` component via `list` prop.\n\nSo, if we were to filter the list (or any other operation), we would have something similar to this:\n\n``` js\n// Assume we have a text input bound to `searchLangs` data via v-model for example.\ncomputed: {\n  fLangs () {\n    const re = new RegExp(this.searchLangs, 'i')\n    return this.langs.filter(lang =\u003e lang.match(re))\n  }\n}\n```\n\nThen just pass that `fLangs` to the `list` prop instead of the original `langs`.\n\n### Hide single page\n\nBy default, paginated links will always be displayed even if there's only one page. But sometimes you want to hide it when there's a single page — especially after filtering the items. The plugin allows you to do so by using the `:hide-single-page=\"true\"` prop.\n\n``` html\n\u003cpaginate-links for=\"items\"\n  :hide-single-page=\"true\"\n\u003e\u003c/paginate-links\u003e\n```\n\n### Links customization\n\nIn `vue-paginate`, you can customize every bit of your pagination links.\n\nBut first, let’s see the html structure used for all link types:\n\n``` html\n\u003cul\u003e\n  \u003cli\u003e\u003ca\u003e1\u003c/a\u003e\u003c/li\u003e\n  \u003cli\u003e\u003ca\u003e2\u003c/a\u003e\u003c/li\u003e\n  \u003c!-- … --\u003e\n\u003c/ul\u003e\n```\n\nNow, let’s see what CSS selectors we often need to use:\n\n#### All links containers:\n\n`ul.paginate-links`\n\n#### Specific links container:\n\n`ul.paginate-links.languages`\n\n`languages` here is the name of your paginated list.\n\n#### Current page:\n\nThis only works for full \u0026 limited links.\n\n`ul.paginate-links \u003e li.active \u003e a`\n\n#### Previous \u0026 Next Links:\n\nObviously, this is only for simple links.\n\nPrevious –\u003e `ul.paginate-links \u003e li.prev \u003e a`\n\nNext –\u003e `ul.paginate-links \u003e li.next \u003e a`\n\n#### Disabled Next/Previous Links:\n\n`ul.paginate-links \u003e li.disabled \u003e a`\n\n#### Limited Links:\n\nNumber links –\u003e `ul.paginate-links \u003e li.number \u003e a`\n\nLeft arrow –\u003e `ul.paginate-links \u003e li.left-arrow \u003e a`\n\nRight arrow –\u003e `ul.paginate-links \u003e li.right-arrow \u003e a`\n\nEllipses –\u003e `ul.paginate-links \u003e li.ellipses \u003e a`\n\n#### Adding additional classes\n\nIn some cases, especially when you're using a CSS framework, you'll need to add additional classes to your links elements. You can do so simply by using the `classes` prop on your `PaginateLinks` component. This prop takes an object that contains the element's selector as the key, and the class you want to add as the value.\n\nHere's an example:\n\n``` html\n\u003cpaginate-links\n  for=\"languages\"\n  :simple=\"{\n    prev: 'Back',\n    next: 'Next'\n  }\"\n  :classes=\"{\n    'ul': 'simple-links-container',\n    '.next \u003e a': 'next-link',\n    '.prev \u003e a': ['prev-link', 'another-class'] // multiple classes\n  }\"\n\u003e\u003c/paginate-links\u003e\n```\n\nNote that this feature works on all link types – full links, simple links, and limited links.\n\n## License\n\n[MIT](http://opensource.org/licenses/MIT)\n\nCopyright (c) 2016–2017 Taha Shashtari\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTahaSh%2Fvue-paginate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FTahaSh%2Fvue-paginate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTahaSh%2Fvue-paginate/lists"}