createMutationController

function createMutationController<TData, TError, TVariables, TOnMutateResult>(
   host: ReactiveControllerHost,
   options: Accessor<CreateMutationOptions<TData, TError, TVariables, TOnMutateResult>>,
queryClient?: QueryClient): MutationResultAccessor<TData, TError, TVariables, TOnMutateResult>;

Defined in: packages/lit-query/src/createMutationController.ts:325

Creates a Lit reactive controller that subscribes the host to a mutation.

The returned accessor is callable and also exposes current, mutate, mutateAsync, reset, and destroy. When options is a function, it is re-read during host updates so mutation options can follow reactive host state.

If queryClient is omitted, the controller resolves the client from the nearest connected QueryClientProvider.

Type Parameters#

TData#

TData = unknown

TError#

TError = Error

TVariables#

TVariables = void

TOnMutateResult#

TOnMutateResult = unknown

Parameters#

host#

ReactiveControllerHost

The Lit reactive controller host that owns the mutation subscription.

options#

Accessor<CreateMutationOptions<TData, TError, TVariables, TOnMutateResult>>

Mutation observer options, or a getter that returns options.

options properties#

Built from MutationObserverOptions. See the type above for what it changes.

queryClient?#

QueryClient

Optional explicit query client. Provide this for controllers that should not resolve a client from Lit context.

Returns#

MutationResultAccessor<TData, TError, TVariables, TOnMutateResult>

An accessor for the latest mutation result with mutation helper methods.

Example#

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

class AddTodoForm extends LitElement {
  private readonly addTodo = createMutationController(this, {
    mutationFn: (title: string) =>
      fetch('/api/todos', { method: 'POST', body: JSON.stringify({ title }) }),
  })

  render() {
    const mutation = this.addTodo()

    return html`
      <button ?disabled=${mutation.isPending} @click=${() => this.addTodo.mutate('Ship docs')}>
        Add todo
      </button>
    `
  }
}