${project.name}
`)} + `, + )} + + + ` + } +} +``` + +## Page Parameters + +`initialPageParam` is required. `getNextPageParam` decides whether another page exists and what value should be passed as `pageParam` to the next query function call. + +```ts +createInfiniteQueryController(this, { + queryKey: ['projects'], + queryFn: ({ pageParam }) => fetchProjectsPage(pageParam), + initialPageParam: 1, + getNextPageParam: (lastPage) => + lastPage.hasMore ? lastPage.page + 1 : undefined, +}) +``` + +Returning `undefined` or `null` means there is no next page. + +## Avoid Overlapping Fetches + +There is one ongoing fetch for an infinite query cache entry. If you call `fetchNextPage` while a background refetch is running, you can overwrite data. Disable the button or check `!query.isFetching` before loading more: + +```ts +if (query.hasNextPage && !query.isFetching) { + this.projects.fetchNextPage() +} +``` + +## Paginated Alternative + +If your UI shows one page at a time, a normal query with a page in the key can be a better fit. The [Pagination example](../examples/pagination) uses `createQueryController`, `placeholderData: keepPreviousData`, prefetching, and mutations to demonstrate that pattern. diff --git a/docs/framework/lit/guides/mutations.md b/docs/framework/lit/guides/mutations.md new file mode 100644 index 00000000000..8e5c3fdfa42 --- /dev/null +++ b/docs/framework/lit/guides/mutations.md @@ -0,0 +1,166 @@ +--- +id: mutations +title: Mutations +--- + +Unlike queries, mutations are used to create, update, delete, or otherwise perform server side effects. In Lit, use [`createMutationController`](../reference/functions/createMutationController.md). + +```ts +import { LitElement, html } from 'lit' +import { + QueryClient, + QueryClientProvider, + createMutationController, + createQueryController, +} from '@tanstack/lit-query' + +const queryClient = new QueryClient() + +class AppQueryProvider extends QueryClientProvider { + constructor() { + super() + this.client = queryClient + } +} + +customElements.define('app-query-provider', AppQueryProvider) + +class TodosView extends LitElement { + private readonly todos = createQueryController(this, { + queryKey: ['todos'], + queryFn: fetchTodos, + }) + + private readonly addTodo = createMutationController(this, { + mutationFn: createTodo, + onSuccess: async () => { + await queryClient.invalidateQueries({ queryKey: ['todos'] }) + }, + }) + + render() { + const query = this.todos() + const mutation = this.addTodo() + const todos = query.data ?? [] + + return html` + ${mutation.isError ? html`${mutation.error.message}
` : null} + ${mutation.isSuccess ? html`Todo added
` : null} + + + +Total projects: ${dashboard.projects.length}
+Active users: ${dashboard.activeUsers}
+ ` +} +``` + +Having the same query key more than once in the `queries` array can cause those entries to share cached data. Deduplicate repeated keys first if each rendered row needs independent query state. diff --git a/docs/framework/lit/guides/queries.md b/docs/framework/lit/guides/queries.md new file mode 100644 index 00000000000..592cdcfd029 --- /dev/null +++ b/docs/framework/lit/guides/queries.md @@ -0,0 +1,141 @@ +--- +id: queries +title: Queries +--- + +New to Lit Query? Start with [Installation](../installation.md) and [Quick Start](../quick-start.md) before wiring query controllers into your elements. + +## Query Basics + +A query is a declarative dependency on an asynchronous source of data tied to a unique key. Use queries for reading server state. If a function creates, updates, or deletes server data, use a [mutation](./mutations.md) instead. + +In Lit, subscribe to a query with [`createQueryController`](../reference/functions/createQueryController.md): + +```ts +import { LitElement, html } from 'lit' +import { createQueryController } from '@tanstack/lit-query' + +class TodosView extends LitElement { + private readonly todos = createQueryController(this, { + queryKey: ['todos'], + queryFn: fetchTodos, + }) + + render() { + const query = this.todos() + + if (query.isPending) return html`Loading...` + if (query.isError) return html`Error: ${query.error.message}` + + return html` +${query.data.description}
+ ${query.data.stargazers_count} stars + ` + } +} + +customElements.define('repo-stats', RepoStats) +``` + +Render the provider above your query consumers: + +```html +Projects: ${dashboard.projects.length}
` + } +} +``` diff --git a/docs/framework/lit/reference/functions/createQueryController.md b/docs/framework/lit/reference/functions/createQueryController.md new file mode 100644 index 00000000000..11e52770bbd --- /dev/null +++ b/docs/framework/lit/reference/functions/createQueryController.md @@ -0,0 +1,97 @@ +--- +id: createQueryController +title: createQueryController +--- + +# Function: createQueryController() + +```ts +function createQueryController+ Status: ${query.status} +
+ + + ${query.isPending + ? html`Loading...
` + : null} + ${query.isError + ? html`Error: ${String(query.error)}
` + : null} + ++ Exercises the same consumer across missing-provider and provider + switching flows. +
+Verifies integration between Lit, query-core, and this adapter.
+ ++ Query: ${query.status} +
++ Mutation: ${mutation.status} +
+ + + + + ++ Pagination + mutation demo with optimistic favorite toggles, + invalidation, and deterministic server failures. +
+ +${String(query.error)}
` + : null} + ${this.resetError + ? html`${this.resetError}
` + : null} + +Loading...
+Loading...
+Error
+${query.error?.message}
+${query.isFetching ? 'Refreshing' : 'Ready'}
+${query.data.message}
++ Request count: ${query.data.requestCount} +
+Served at: ${query.data.servedAt}
+ +