Migrating from UIPagination to HighRise Pagination

This guide will help you migrate from the ghl-ui Pagination component to the new HighRise Pagination component.

Component Implementation Changes

Import Changes

- import { UIPagination } from '@gohighlevel/ghl-ui'
+ import { HLPagination } from '@platform-ui/highrise'

Breaking Changes

1. Identifier and model
   • id is required.
   • page ➜ currentPage with @update:page.
2. Counts and totals
   • pageCount ➜ totalPages (explicit), or provide item-count with per-page to derive totals.
3. Page size selection
   • pageSizes (number array) ➜ perPageDropdownOptions with { key: number; label: string } items.
   • showSizePicker ➜ showPerPageDropDown.
4. Layout
   • simple ➜ collapsed (compact layout toggle).
   • pageSlot ➜ pagesToDisplay (how many page buttons to show).
5. Per-page label
   • perPageText is now a string label; omit it to use the default translation.

Props Changes

ghl-ui Prop	HighRise Prop	Notes
page	currentPage	Required for current page
pageCount	totalPages	Optional if item-count and per-page are provided
pageSize	perPage	Current page size
pageSizes	perPageDropdownOptions	Array of { key, label }
pageSlot	pagesToDisplay	Visible page buttons (default: 7)
showSizePicker	showPerPageDropDown	Toggle per-page dropdown
simple	collapsed	Compact mode
-	id	Required
-	itemCount	Alternative to totalPages when paired with perPage
-	isPageDropDown	Show current page as dropdown when collapsed
-	showCurrentRange	Show "X - Y of Z" (default: true)
-	showTotalPages	Show "Page X of Y" (default: false)
-	inline	Inline condensed layout
-	size	'sm' | 'md'
-	perPageText	Custom label for per-page dropdown

Examples

Basic Pagination (Pages Only)

<template>
  <HLPagination
    id="basic-pagination"
    :current-page="currentPage"
    :total-pages="10"
    :show-per-page-drop-down="false"
    :show-current-range="false"
    @update:page="handlePageChange"
  >
    <template #prev>Previous</template>
    <template #next>Next</template>
  </HLPagination>
</template>

With Item Count and Per-Page Selection

<template>
  <HLPagination
    id="pagination-with-size"
    :current-page="currentPage"
    :item-count="itemCount"
    :per-page="pageSize"
    :per-page-dropdown-options="[
      { key: 10, label: '10' },
      { key: 20, label: '20' },
      { key: 50, label: '50' },
      { key: 100, label: '100' },
    ]"
    :show-per-page-drop-down="true"
    :show-total-pages="true"
    :show-current-range="true"
    @update:page="handlePageChange"
    @update:perPage="handlePageSizeChange"
  >
    <template #prev>Previous</template>
    <template #next>Next</template>
  </HLPagination>
</template>

Compact (Collapsed) Mode

<template>
  <HLPagination
    id="compact-pagination"
    :current-page="currentPage"
    :total-pages="18"
    collapsed
    :show-per-page-drop-down="false"
    :show-current-range="false"
    @update:page="handlePageChange"
  >
    <template #prev>Previous</template>
    <template #next>Next</template>
  </HLPagination>
</template>

Inline Display

<template>
  <HLPagination
    id="inline-pagination"
    :current-page="currentPage"
    :total-pages="8"
    inline
    :show-per-page-drop-down="false"
    :show-current-range="false"
    :show-total-pages="true"
    @update:page="handlePageChange"
  />
</template>

Type Definitions

interface PerPageOption {
  key: number
  label: string
}

Best Practices

1. Provide either total-pages or item-count + per-page—avoid mixing both in the same instance.
2. Use collapsed for compact layouts; pair with is-page-drop-down when many pages exist.
3. Keep perPageDropdownOptions consistent across the product (e.g., 10/20/50/100).
4. Hide per-page controls with show-per-page-drop-down="false" when pagination is read-only.
5. Set show-current-range to false when item counts are unknown to avoid misleading ranges.
6. Customize perPageText only when the default copy needs localization tweaks.

Additional Notes

1. Emits update:page and update:perPage only; other UI events (prev/next buttons) resolve to these updates.
2. Default show-current-range is true; show-total-pages is false unless set.
3. Sizes default to md; sm tightens padding and font sizes.
4. RTL and keyboard navigation are handled internally through HighRise primitives.