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: 12/31/2025
Document 2
This is the description for document 2
Modified: 10/17/2025
Document 3
This is the description for document 3
Modified: 10/6/2025
Document 4
This is the description for document 4
Modified: 11/22/2025
Document 5
This is the description for document 5
Modified: 1/1/2026
Document 6
This is the description for document 6
Modified: 11/5/2025
Document 7
This is the description for document 7
Modified: 12/2/2025
Document 8
This is the description for document 8
Modified: 12/5/2025
Custom Empty State
No documents found
Get started by creating your first document.
Different Page Sizes
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. |
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 text for the items counter. |
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