TODOvue Pagination (TvPagination)

A pagination component for Vue 3, flexible and customizable, with support for smart ranges (sibling pages and boundaries), ellipsis, optional navigation buttons, icons, custom styles, and a slot for labels. Designed for SPAs and SSR environments (e.g. Nuxt 3) without assuming DOM details.

Demo: https://ui.todovue.blog/pagination

Table of Contents

• Features
• Installation
• Quick Start (SPA)
• Usage in Nuxt 4 / SSR
• Component Registration Options
• Props
• Events
• Slots
• Customization (Styles / Theming)
• Accessibility
• SSR Notes
• Development
• Contribute
• License
• Attributions

Features

• Automatic calculation of total pages from totalItems and pageSize.
• Dynamic range with sibling pages (siblingCount) and boundaries (boundaryCount).
• Conditional left / right ellipsis when large jumps exist.
• Optional buttons: first / last (showFirstLast) and previous / next (showPrevNext).
• Navigation icons (internally uses @todovue/tv-button).
• Custom styles for active / inactive pages (activeStyle, inactiveStyle).
• Slot to customize each page label (page-label).
• Controlled via v-model (current page) + semantic change event.
• Ready for SSR (no direct access to window / document).
• No heavy dependencies (only vue as peer + @todovue/tv-button).
• Easy integration in TODOvue design systems.

Installation

Using npm:

npm install @todovue/tv-pagination

Using yarn:

yarn add @todovue/tv-pagination

Using pnpm:

pnpm add @todovue/tv-pagination

Requires vue@^3. @todovue/tv-button installs as a dependency.

Quick Start (SPA)

Global registration (main.js / main.ts):

import { createApp } from 'vue'
import App from './App.vue'
import { TvPagination } from '@todovue/tv-pagination'
import '@todovue/tv-pagination/style.css' // import styles
import '@todovue/tv-button/style.css' // import styles

createApp(App)
  .use(TvPagination) // enables <TvPagination /> globally
  .mount('#app')

Local usage inside a component:

<script setup>
import { ref } from 'vue'
import { TvPagination } from '@todovue/tv-pagination'
import '@todovue/tv-pagination/style.css' // import styles
import '@todovue/tv-button/style.css' // import styles

const page = ref(1)
</script>

<template>
  <TvPagination v-model="page" :total-items="500" :sibling-count="2" :boundary-count="2" />
</template>

Usage in Nuxt 4 / SSR

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    '@todovue/tv-card/nuxt'
  ]
})

Use anywhere:

<TvPagination v-model="page" :total-items="120" />

Component Registration Options

Approach	When to use
Global app.use(TvPagination)	Frequent use in many views
Local import { TvPagination }	Isolated contexts / code-splitting
Default import import TvPagination from ...	Single usage or manual registration
Nuxt plugin	SSR / design consistency

Props

Prop	Type	Default	Required	Description
modelValue	Number	1	No	Current page (v-model). Normalized to valid range.
totalItems	Number	—	Yes	Total items being paginated.
pageSize	Number	10	No	Page size to calculate totalPages.
siblingCount	Number	1	No	Number of visible pages next to the active one.
boundaryCount	Number	1	No	Number of always-visible starting and ending pages.
showFirstLast	Boolean	true	No	Shows first/last page buttons.
showPrevNext	Boolean	true	No	Shows previous/next buttons.
showIcons	Boolean	false	No	Uses icons on navigation buttons (arrows).
disabled	Boolean	false	No	Disables all interaction.
ariaLabel	String	'Pagination'	No	Accessible label for <nav>.
labels	Object	{ first:'First', prev:'Prev', next:'Next', last:'Last' }	No	Text for navigation buttons.
buttonProps	Object	{}	No	Additional props (and styles) passed to each TvButton.
activeStyle	Object	{}	No	Inline styles for active pages ({ backgroundColor, color }).
inactiveStyle	Object	{ backgroundColor:'#ffffff', color:'#000000' }	No	Inline styles for inactive pages.
square	Boolean	false	No	Controls if buttons are square.
size	String	'small'	No	Button size ('small', 'md', 'large').
showSummary	Boolean	false	No	Displays text showing the current range of items.
textSummary	String	'Showing {from} to {to} of {total} items'	No	Template for summary text (uses {from}, {to}, {total}).

Note: If activeStyle is empty, TvButton default styling is used. inactiveStyle always provides white/black fallback if omitted.

Events

Name (kebab)	Payload	Description
update:modelValue	number	Emits new page number for v-model.
change	number	Semantic event triggered when the page changes (only if different).

Example:

<TvPagination v-model="page" :total-items="300" @change="onPage" />

function onPage(newPage) {
  console.log('Current page:', newPage)
}

Slots

Slot	Exposed props	Description
page-label	{ page, active }	Customize content of each page button.

Example:

<TvPagination
  v-model="page"
  :total-items="100"
>
  <template #page-label="{ page, active }">
    <span :style="active ? 'font-weight:600' : ''">Pg {{ page }}</span>
  </template>
</TvPagination>

Customization (Styles / Theming)

Active styles with activeStyle:

<TvPagination
  v-model="page"
  :total-items="300"
  :active-style="{ backgroundColor: '#10b981', color: '#ffffff' }"
/>

Inactive styles:

<TvPagination
  v-model="page"
  :total-items="300"
  :inactive-style="{ backgroundColor: '#f1f5f9', color: '#0f172a' }"
/>

Passing styles / variants to base button via buttonProps:

<TvPagination
  v-model="page"
  :total-items="120"
  :button-props="{ outlined: true, small: true }"
/>

All buttonProps values are passed to each TvButton instance (including variants like success, outlined, small, etc.).

Accessibility

• nav container with configurable aria-label (ariaLabel).
• Active page receives aria-current="page".
• Ellipsis marked with aria-hidden="true" and are not focusable.
• Disabled buttons use disabled attribute (inherited from TvButton).
• If icons are used (showIcons=true) accessible text is preserved (or empty for icon-only). Ensure labels.* describe the action.

SSR Notes

• No direct DOM access → safe for server rendering.
• Styles are served as a separate CSS file (dist/tv-pagination.css) that must be explicitly imported (see Importing Styles).
• vue is marked as external in the library build (tree-shake friendly).
• Compatible with Nuxt 3/4 by adding the stylesheet to the css array in nuxt.config.ts.

Development

git clone https://github.com/TODOvue/tv-pagination.git
cd tv-pagination
npm install
npm run dev        # runs playground demo (Vite)
npm run build      # builds the library

Build demo (uses environment variable):

npm run build:demo  # generates dist-demo with README in public/

Output structure:

• dist/tv-pagination.es.js
• dist/tv-pagination.cjs.js
• Types: dist/tv-pagination.d.ts

Contribute

PRs and issues are welcome! See CONTRIBUTING.md and CODE_OF_CONDUCT.md.

License

MIT © TODOvue

Attributions

Created for the TODOvue component ecosystem.