0
Fork 0
mirror of https://github.com/TanStack/query.git synced 2026-11-16 22:50:20 +00:00
query/docs/framework/lit/installation.md
Wonsuk Choi d88ba6ec46
docs(lit): remove '@tanstack/query-core' and 'lit' from the install commands to install only '@tanstack/lit-query' (#12209)
* docs(lit): remove '@tanstack/query-core' from the install commands since 'lit-query' already depends on it

* docs(lit): remove 'lit' from the install commands since apps using Lit Query already have it
2026-11-01 00:39:26 +09:00

3.3 KiB

id title
installation Installation

IMPORTANT: The Lit adapter is currently experimental and v0.1. Pin exact versions if you need extra release stability while the API is early.

Install Lit Query:

npm i @tanstack/lit-query

or

pnpm add @tanstack/lit-query

or

yarn add @tanstack/lit-query

or

bun add @tanstack/lit-query

Requirements

Lit Query is intended for Lit 2.8 and newer, including Lit 3. It uses Lit reactive controllers and Lit context, so query consumers should be ReactiveControllerHost instances such as LitElement.

The snippets in these docs declare reactive properties with static properties and initialize them as class fields. Class fields that use the native [[Define]] semantics shadow the accessors Lit uses to detect changes, so with TypeScript set useDefineForClassFields to false, as the runnable examples do. See Avoiding issues with class fields in the Lit docs for more details.

{
  "compilerOptions": {
    "useDefineForClassFields": false
  }
}

TanStack Query is optimized for modern browsers:

Chrome >= 91
Firefox >= 90
Edge >= 91
Safari >= 15
iOS >= 15
Opera >= 77

Provider Setup

Create a QueryClient, provide it with QueryClientProvider, and register your custom element. The package exports the provider class but does not call customElements.define for you.

Subclass Pattern

import { QueryClient, QueryClientProvider } from '@tanstack/lit-query'

const queryClient = new QueryClient()

class AppQueryProvider extends QueryClientProvider {
  constructor() {
    super()
    this.client = queryClient
  }
}

customElements.define('app-query-provider', AppQueryProvider)
<app-query-provider>
  <todos-view></todos-view>
</app-query-provider>

Direct Provider Element

You can register the provider class directly and bind its client property from a Lit template. The dot is important: .client=${queryClient} is a property binding, not an HTML attribute.

import { LitElement, html } from 'lit'
import { QueryClient, QueryClientProvider } from '@tanstack/lit-query'

const queryClient = new QueryClient()

customElements.define('query-client-provider', QueryClientProvider)

class AppRoot extends LitElement {
  render() {
    return html`
      <query-client-provider .client=${queryClient}>
        <todos-view></todos-view>
      </query-client-provider>
    `
  }
}

If a connected provider has no client, it throws. See the generated QueryClientProvider reference for the full contract.

Render Roots

The snippets in these docs use Lit's default shadow DOM. Lit Query controllers and QueryClientProvider work with shadow DOM and light DOM because they use the host lifecycle and Lit context, not global selectors.

Some runnable examples override createRenderRoot() and return this so their demo markup stays in light DOM for shared page styles and test selectors. That override is not required for Lit Query. Use light DOM only when your app has a separate reason to expose a component's internal markup to global CSS, tests, or non-shadow-DOM integration code.

Devtools Status

Lit Devtools are not available yet. This is a current adapter limitation, not an installation step.