Paginated Items
Explore interactive examples and all component variations in our Storybook.
The PaginatedItems component provides a flexible pagination solution for large datasets. Built with performance in mind, it handles data slicing, page navigation, and loading states automatically. Perfect for user lists, product catalogs, search results, and any interface displaying large collections of items.
Basic Usage
Product Grid Layout
Loading States
Document 1
This is the description for document 1
Modified: 2/27/2026
Document 2
This is the description for document 2
Modified: 2/5/2026
Document 3
This is the description for document 3
Modified: 2/3/2026
Document 4
This is the description for document 4
Modified: 1/22/2026
Document 5
This is the description for document 5
Modified: 12/12/2025
Document 6
This is the description for document 6
Modified: 2/20/2026
Document 7
This is the description for document 7
Modified: 1/25/2026
Document 8
This is the description for document 8
Modified: 12/4/2025
Custom Empty State
No documents found
Get started by creating your first document.
Different Page Sizes
Server-side Pagination
When items come from an API page-by-page, pass the serverPagination prop. The data prop must contain only the current page's items; the component renders them as-is and delegates navigation to your callback.
Localization
Pass the labels prop to override any text rendered by the component. The emptyState prop (accepts a ReactNode) takes priority over labels.noItemsFound when both are set.
Properties
PaginatedItems<Entry>
| Property | Type | Default | Description |
|---|---|---|---|
data | Entry[] | [] | Array of items to paginate and display. |
perPage | number | 50 | Number of items to display per page. |
initialPage | number | 1 | Initial page number to display. |
itemsContainerClass | string | '' | CSS classes for the items container. |
children | (item: Entry, index: number) => ReactNode | - | Function to render each item. |
emptyState | ReactNode | Default empty message | Custom component to show when no items exist. Takes priority over labels.noItemsFound. |
isLoading | boolean | false | Whether to show loading state. |
loadingVariant | 'loader' | 'skeleton' | 'loader' | Type of loading indicator to show. |
showItemsCounter | boolean | true | Whether to show the items counter. |
counterText | string | - | Custom pagination counter text. Takes priority over labels.paginationCounter. |
labels | PaginatedItemsLabels | - | Override any text rendered by the component. All fields are optional. |
serverPagination | PaginatedItemsServerPagination | - | Delegates pagination to the caller. When provided, data must contain only the current page's items. |
PaginatedItemsLabels
| Field | Default | Description |
|---|---|---|
noItemsFound | 'No item found!' | Text in the default empty state. Ignored when emptyState prop is set. |
paginationCounter | 'Showing {{startIndex}} to {{endIndex}} of {{totalItems}} results' | Pagination counter template. Supports {{startIndex}}, {{endIndex}}, {{totalItems}}. Superseded by counterText when both are set. |
PaginatedItemsServerPagination
| Property | Type | Description |
|---|---|---|
totalItems | number | Total number of items on the server. |
totalPages | number | Total number of pages on the server. |
currentPage | number | Current active page (controlled externally). |
onPageChange | (page: number) => void | Called when the user navigates to a different page. |
Entry Type Constraint
Entry extends { id?: string }
Items should have an optional id property for optimal rendering performance.
Loading States
The component supports two loading variants:
- Loader - Shows a centered spinner
- Skeleton - Shows placeholder skeleton elements
Pagination Features
- Automatic Pagination - Handles data slicing and page calculation
- Navigation Controls - Previous/next buttons and page indicators
- Items Counter - Shows current range and total items
- Responsive Design - Works well on mobile and desktop
- State Management - Maintains current page across data changes
Accessibility
The PaginatedItems component includes accessibility features:
- Keyboard Navigation - Full keyboard support for pagination controls
- Screen Reader Support - Proper ARIA labels and announcements
- Focus Management - Clear focus indicators on interactive elements
- Loading States - Announces loading status to screen readers
- Page Information - Current page and total items announced
Common Use Cases
The PaginatedItems component is perfect for:
- User Management - Display and navigate through user lists
- Product Catalogs - Browse products with pagination
- Search Results - Paginate through search results
- Document Libraries - Navigate document collections
- Data Tables - Alternative to traditional table pagination
- Content Feeds - Display content with pagination
- Admin Dashboards - Manage large datasets efficiently
- E-commerce - Product listings with pagination
Best Practices
- Performance - Use appropriate page sizes for your data and UI
- Loading States - Always provide loading feedback for async data
- Empty States - Create meaningful empty state messages
- Responsive Design - Test pagination on different screen sizes
- Data Management - Handle data updates and page resets properly
- Accessibility - Test with keyboard navigation and screen readers
- Visual Consistency - Maintain consistent item layouts
- Error Handling - Handle pagination errors gracefully