useLoadMore

useLoadMore is used for implementing load more / infinite scroll scenarios: load the first page of data, then continuously append subsequent data through buttons or scroll bars.

Basic Usage

useLoadMore Click Button Mode

Return Values

const result = useLoadMore<TData>(service, options)

Field	Type	Description
current	Ref<number>	Current page
pageSize	Ref<number>	Items per page
total	Ref<number>	Total items count
totalPages	Ref<number>	Total pages
data	ShallowRef<TData | undefined>	Concatenated array or raw page payload
loading	Ref<boolean>	Loading first page
refreshing	Ref<boolean>	Refreshing list
loadingMore	Ref<boolean>	Appending page items
error	ShallowRef<unknown>	Request error
params	Ref<unknown[]>	Additional request arguments
noMore	Ref<boolean>	Whether all pages have been fetched
canLoadMore	Ref<boolean>	True if load more is ready
loadMore()	—	Load next page and append items
reload()	—	Reset list and start from initial page
refresh()	—	Refresh list based on current page
pagination	—	Utility helpers (compatible with usePagination interface)

Options

The first argument to useLoadMore(service, options) is the request function service(page, pageSize, ...args), and the second is the options object:

interface UseLoadMoreOptions<TData, TParams extends unknown[]> {
  initialPage?: number // Initial page, default 1
  pageSize?: number // Items per page, default 10
  isLoadMore?: boolean // Whether to allow load more, default true
  threshold?: number // Infinite scroll trigger threshold (reserved)
  loadMoreService?: (page: number, pageSize: number) => Promise<RequestResponse<TData>> // Optional custom loading endpoint
  onSuccess?: (data: TData, params: TParams) => void
  onError?: (error: unknown, params: TParams) => void
  onFinally?: (params: TParams) => void
  manual?: boolean // Whether to manually trigger the first load
  defaultParams?: TParams // Extra request parameters besides page and pageSize
}

Combine with Pagination Methods (Prevent Page Drift)

When combining an infinite scroll container with specific pagination or page jump logic (e.g. calling pagination.loadPage(n)), replacing the list data (shrinking the long list to a single page list) might immediately trigger the container's scroll event due to changes in DOM dimensions or scroll position. This can lead to an unexpected loadMore() call and cause page drift (e.g., drifting to load page n + 1 right after jumping to page n).

To address this issue:

1. Built-in Cooldown Guard: useLoadMore has a built-in 100ms cooldown guard for reload / refresh / loadPage. Within 100ms after a refresh/page switch finishes, any loadMore triggered automatically by scroll events will be ignored.
2. Component-level Reset: When executing jump operations like loadPage, it is recommended to explicitly reset the scroll position of the scroll container to the top (el.scrollTop = 0) to completely avoid browser layout-triggered scrolling.

The following example demonstrates infinite scroll load-more along with safe programmatic pagination via goToPage.

Infinite Scroll & Safe Page Jumps

Relationship with usePagination

• usePagination: Suitable for scenarios with clear pagination controls (page number switching)
• useLoadMore: Suitable for "waterfall / infinite scroll" scenarios (continuously append)

The pagination return values of both are basically compatible, you can switch implementation methods when needed.