snapshot of https://github.com/TanStack/query.git (main, 2026-09-16; blobs > 131072B omitted)

docs/framework/lit/guides/query-invalidation.md

@@ -0,0 +1,83 @@
+---
+id: query-invalidation
+title: Query Invalidation
+---
+
+Waiting for queries to become stale is not always enough. After a mutation succeeds, you often know that related cached data is out of date. Use `queryClient.invalidateQueries` to mark matching queries stale and refetch active observers.
+
+```ts
+queryClient.invalidateQueries()
+
+queryClient.invalidateQueries({
+  queryKey: ['todos'],
+})
+```
+
+When a query is invalidated:
+
+- It is marked stale, overriding any `staleTime`
+- If a matching query is active in a controller, it can refetch in the background
+
+## Invalidation from Mutations
+
+```ts
+private readonly addTodo = createMutationController(this, {
+  mutationFn: addTodo,
+  onSuccess: async () => {
+    await queryClient.invalidateQueries({ queryKey: ['todos'] })
+  },
+})
+```
+
+Use this pattern when the mutation result tells you related cached data is stale. The [Pagination example](../examples/pagination) shows invalidation after project mutations.
+
+## Query Matching
+
+Match a group of queries by prefix:
+
+```ts
+queryClient.invalidateQueries({ queryKey: ['projects'] })
+```
+
+Both of these query keys match:
+
+```ts
+const projectsListKey = ['projects']
+const projectsPageKey = ['projects', 1, 250, false]
+```
+
+Use a more specific key when only one slice should be invalidated:
+
+```ts
+queryClient.invalidateQueries({
+  queryKey: ['projects', this.page],
+})
+```
+
+Use `exact: true` to match only the exact key:
+
+```ts
+queryClient.invalidateQueries({
+  queryKey: ['projects'],
+  exact: true,
+})
+```
+
+## Manual Cache Updates
+
+Invalidation is usually simpler than normalized cache updates. When you do need immediate UI updates, combine targeted cache writes with invalidation:
+
+```ts
+queryClient.setQueryData<TodosResponse>(['todos'], (existing) => {
+  if (!existing) return existing
+
+  return {
+    ...existing,
+    items: [...existing.items, createdTodo],
+  }
+})
+
+await queryClient.invalidateQueries({ queryKey: ['todos'] })
+```
+
+For rollback with optimistic updates, see the mutation guide and the [Pagination example](../examples/pagination).