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

The following architectural changes have been made:

1. Pagination Calculation:

   • Old: Used pageCount prop to determine total pages
   • New: Uses totalPages prop

2. Page Size Selection:

   • Old: Used pageSizes prop array of numbers
   • New: Uses structured perPageDropdownOptions prop array with key-label pairs

3. Simplified Mode:

   • Old: Used simple prop
   • New: Uses collapsed prop with enhanced layout

Props Changes

1. New Required Props:

   • id: Required for accessibility

2. Renamed Props:

   • page → currentPage
   • pageSize → perPage
   • pageSlot → pagesToDisplay
   • showSizePicker → showPerPageDropDown
   • pageSizes → perPageDropdownOptions
   • simple → collapsed
   • pageCount → totalPages

3. New Props:

   • size: 'sm' | 'md'
   • showCurrentRange: Show current items range, make it false
   • showTotalPages: Show "Page X of Y", make it false
   • perPageText: Customize "Rows per page" text, make it false

Events Changes

1. Renamed Events:
   • update:page-size → update:perPage

Examples

Basic Pagination

- <UIPagination
-   id="basic-pagination"
-   :page-count="10"
-   :page="currentPage"
-   @update:page="handlePageChange"
- />

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

With Per Page and Item Count

INFO

• per-page is mapped to page-size in GHL-UI
• total-pages is mapped to page-count in GHL-UI
• In HighRise, either total-pages or item-count and per-page is required

- <UIPagination
-   id="basic-pagination"
-   :page="currentPage"
-   :page-size="10"
-   :page-count="10"
- />

+ <HLPagination
+   id="basic-pagination"
+   :current-page="currentPage"
+   :per-page="10"
+   :total-pages="10" <!-- Either total-pages or item-count and per-page is required -->
+ >
+   <template #prev>Previous</template>
+   <template #next>Next</template>
+ </HLPagination>

With Page Size Selection

- <UIPagination
-   id="pagination-with-size"
-   :page-count="totalPages"
-   :page="currentPage"
-   :page-size="pageSize"
-   :show-size-picker="true"
-   :page-sizes="[10, 20, 50, 100]"
-   @update:page="handlePageChange"
-   @update:page-size="handlePageSizeChange"
- />

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

Compact/Simple Mode

- <UIPagination
-   id="simple-pagination"
-   :page-count="10"
-   :page="currentPage"
-   :simple="true"
-   @update:page="handlePageChange"
- />

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

Only Pages (No Per-Page Selection)

<template>
  <HLPagination
    id="pages-only"
    :current-page="currentPage"
    :total-pages="18"
    :show-per-page-drop-down="false"
    :pages-to-display="7"
    size="md"
    @update:page="handlePageChange"
  >
    <template #prev>Previous</template>
    <template #next>Next</template>
  </HLPagination>
</template>

Type Definitions

interface PerPageOption {
  key: number
  label: string
}

Best Practices

1. Always provide unique id props for accessibility
2. Use appropriate size based on context
3. Consider using collapsed mode for compact layouts
4. Show current range for better user context
5. Customize prev/next button text for clarity
6. Use consistent per-page options across app
7. Handle page changes appropriately
8. Consider mobile responsiveness
9. Implement proper loading states
10. Follow accessibility guidelines

Additional Notes

1. The component provides built-in responsive design
2. Supports both item-based and page-based calculations
3. Enhanced dropdown for per-page selection
4. Consistent styling with HighRise design system
5. Built-in accessibility features
6. Support for RTL layouts
7. Improved keyboard navigation
8. Better mobile support
9. Flexible layout options
10. Integration with other HighRise components