# @svelte-lean/query/paged

> createPaged() and tablePaging(): server-paged lists, their page state and the DataTable props.

Page: https://svelte-lean.vercel.app/query/api/paged · Markdown: https://svelte-lean.vercel.app/query/api/paged.md · Index: https://svelte-lean.vercel.app/llms.txt

createPaged(): a server-paged list on a page() endpoint. The page resets on a filter change, is clamped to the last page, keeps the previous rows while the next load, and spreads into \<DataTable manual\>.

## Import

`import`

```ts
import { createPaged, tablePaging } from '@svelte-lean/query/paged';
```

## Usage

`members.svelte`

```svelte
<script lang="ts">
	import { createPaged } from '@svelte-lean/query/paged';
	import { listMembers } from '$api/members';

	let filters = $state({ search: '' });
	// A filter change resets the page to 1; the previous rows stay while the next page loads.
	const list = createPaged(listMembers, () => filters, { perPage: 25, prefetch: 'next' });
</script>

<input type="search" aria-label="Search members" bind:value={filters.search} />
<ul aria-busy={list.loading}>
	{#each list.rows as member (member.id)}<li>{member.name}</li>{/each}
</ul>
<button disabled={list.page <= 1} onclick={() => list.setPage(list.page - 1)}>Previous</button>
<span>Page {list.page} of {list.lastPage}</span>
<button disabled={list.page >= list.lastPage} onclick={() => list.setPage(list.page + 1)}
	>Next</button
>
```

## Size

Production Vite builds of a small consumer entry, Svelte external. A marginal row is the bytes the entry adds over the row it names.

| Build | Over | gzip | brotli | Budget (gzip) |
| --- | --- | --- | --- | --- |
| `paged (marginal)` | `query` | 1234 B | 1109 B | 1400 B |

Read from `packages/query/artifacts/size.json`. Every entry and its method: [Performance](https://svelte-lean.vercel.app/query/performance.md).

## Functions

The binding and the adapter to DataTable state.

### Exports

Runtime exports of the entry.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `createPaged` | `(endpoint: QueryEndpoint<P, Page<T>>, filters: () => P \| undefined \| null, options?: PagedOptions) => PagedResult<T>` | – | A query of the current page; page params come from the profile's pageParams. |
| # `tablePaging` | `(state: () => { pageIndex, pageSize }) => { page, perPage }` | – | Keep the page and the page size in DataTable state: pass the result into the options. |

## Options

PagedOptions, the third argument of createPaged().

### PagedOptions

page and perPage are numbers, or values owned elsewhere (Controlled).

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `page` | `number \| Controlled<number>` | `1` | The page, 1-based. |
| # `perPage` | `number \| Controlled<number>` | `20` | The page size. |
| # `when` | `boolean \| (() => boolean)` | – | A state condition: pauses fetching and polling, keeps data. |
| # `keepPrevious` | `boolean` | `true` | Keep the previous rows while the next page loads. |
| # `poll` | `PollOption \| (() => PollOption)` | – | Polling of the current page's entry only. |
| # `fresh` | `Duration` | – | Per-use freshness. |
| # `prefetch` | `'next' \| 'neighbours' \| false` | `false` | Prefetch the next page, or both neighbours, after a settled answer. |

### Controlled

A value owned elsewhere (DataTable state, the URL).

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `get` | `() => T` | – | Read the value. |
| # `set` | `(value: T) => void` | – | Write the value. |

## Result

PagedResult extends QueryState\<Page\<T\>\> (data, error, loading, refreshing, busy, blocked, info, refetch) with the page state.

### PagedResult

The fields of QueryState, plus these.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `rows` | `T[]` | – | The rows; an empty array while there is no data. |
| # `total` | `number` | – | 0 while there is no data; a lower bound when estimated. |
| # `page` | `number` | – | The effective page, 1-based. |
| # `perPage` | `number` | – | The page size. |
| # `lastPage` | `number` | – | The last page, at least 1. |
| # `estimated` | `boolean` | – | The server sent a bare list without a paginator. |
| # `setPage` | `(page: number) => void` | – | Go to a page. |
| # `setPerPage` | `(perPage: number) => void` | – | Change the page size; resets the page to 1. |
| # `table` | `PagedTableProps<T>` | – | Props for \<DataTable manual\>: spread them. |

### PagedTableProps

list.table: one object whose getters each read their own signal.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `manual` | `true` | – | Server mode of DataTable. |
| # `data` | `T[]` | – | The rows of the page. |
| # `rowCount` | `number \| undefined` | – | undefined when the total is unknown. |
| # `pageCount` | `number` | – | The last page. |
| # `loading` | `boolean` | – | The user waits for this page. |
| # `fetching` | `boolean` | – | Any fetch of the page (DataTable’s prop name; busy on the list). |
| # `refreshing` | `boolean` | – | A quiet refresh: a thin line, the rows stay. |

## Guide

How to use it, with examples: [Lists](https://svelte-lean.vercel.app/query/lists.md). All entry points: [Svelte Lean Query](https://svelte-lean.vercel.app/query.md).