# Queue

**`sonic-queue`** loads a paginated API in batches and renders each batch as an internal [List](/core/components/functional/list). Choose it over `sonic-list` for long or endless lists; the key attributes are `dataProviderExpression` · `limit` · `dataFilterProvider`.

## Lazy load

`dataProviderExpression` is the request path: `$offset` and `$limit` are replaced for each batch. The first batch starts at `offset` (default `0`) with `limit` rows (default `5`, at most `15`). The next batch loads when the end of the list scrolls into view, and the queue stops at the first empty batch. Put the queue in a box with a fixed height and `overflow-y-auto`, then scroll inside it.

<docs-lit-demo for="docs-queue-geo-demo"></docs-lit-demo>

Rows come from the `.items` callback, as on [List](/core/components/functional/list); `.noItems` and `.skeleton` work the same way. Without `$offset` in the expression, the queue sends one request and behaves like a list. Set `noLazyload` to load every batch in a row without waiting for the scroll.

## Filters

`dataFilterProvider` names a form store (`formDataProvider`). Each non-empty field is added to the query string; when a field changes, the queue drops the loaded batches and reloads from the first offset, after a `filterTimeoutMs` debounce (default `400`). Search a city, an airport or a flight number.

<docs-lit-demo for="docs-queue-users-demo"></docs-lit-demo>

To keep some form fields out of the request, list their names in `filteredFields`, separated by spaces.

## API reference

| Attribute | Values | Description |
|-----------|--------|-------------|
| `dataProviderExpression` | string (default: closest ancestor `dataProvider`) | Request path; `$offset` and `$limit` are replaced for each batch |
| `serviceURL` | string | API base URL; inherited from the closest ancestor |
| `key` | string | Response property that holds the rows |
| `limit` | number (default `5`, max `15`) | Rows per batch |
| `offset` | number (default `0`) | Offset of the first batch |
| `idKey` | string (default `id`) | Row property used as identity |
| `dataFilterProvider` | string | Form store whose fields are added to the query; inherited from the closest ancestor |
| `filteredFields` | space-separated names | Form fields not sent to the API |
| `filterTimeoutMs` | number (default `400`) | Debounce before reloading after a filter change |
| `noLazyload` | boolean | Loads all batches without waiting for the scroll |
| `lazyBoundsRatio` | number (default `1`) | Lazy-load margin, as a multiple of the viewport size |
| `loader` | `inline` · `fixed` (default `inline`) | Loader shown while a batch loads |
| `cache` | `RequestCache` (default `default`) | Fetch cache mode |
| `invalidateOnPageShow` | boolean | Reloads batches when the page is restored from the back/forward cache |
| `localStorage` | `disabled` · `enabled` (default `disabled`) | Forwarded to each batch list |
| `debug` | boolean | Shows a live inspector of each batch list's data |

| Property | Type | Description |
|----------|------|-------------|
| `items` | `ListItems` | Row renderer |
| `noItems` | `ListItems` | Rendered when the first batch is empty |
| `skeleton` | `ListItems` | Rendered while a batch loads |
| `itemPropertyMap` | object | Forwarded to each batch list |

The queue publisher exposes `resultCount`, the number of rows loaded so far.

No slots. `<template>` children are used as row templates for hosts without Lit; see [HTML integration](/docs/misc/html-integration).