useStore

useStore<TSchema, TContext, TSyncPayloadSchema>(options): Store<TSchema, TContext> & ReactApi

Defined in: react/src/useStore.ts:54

Returns a store instance augmented with hooks (store.useQuery() and store.useClientDocument()) for reactive queries.

Type Parameters

TSchema

TSchema extends LiveStoreSchema<DbSchema, EventDefRecord>

The schema type for the store

TContext

TContext = { }

TSyncPayloadSchema

TSyncPayloadSchema extends Schema<any, any, never> = Schema<JsonValue, JsonValue, never>

Parameters

options

RegistryStoreOptions<TSchema, TContext, TSyncPayloadSchema>

Returns

Store<TSchema, TContext> & ReactApi

The loaded store instance augmented with React hooks

Example

function Issue() {
  // Suspends until loaded or returns immediately if already loaded
  const issueStore = useStore(issueStoreOptions('abc123'))
  const [issue] = issueStore.useQuery(queryDb(tables.issue.select()))

  const toggleStatus = () =>
    issueStore.commit(
      issueEvents.issueStatusChanged({
        id: issue.id,
        status: issue.status === 'done' ? 'todo' : 'done',
      }),
    )

  const preloadParentIssue = (issueId: string) =>
    storeRegistry.preload({
      ...issueStoreOptions(issueId),
      unusedCacheTime: 10_000,
    })

  return (
    <>
      <h2>{issue.title}</h2>
      <button onClick={() => toggleStatus()}>Toggle Status</button>
      <button onMouseEnter={() => preloadParentIssue(issue.parentIssueId)}>Open Parent Issue</button>
    </>
  )
}

Remarks

• Suspends until the store is loaded.
• Store is cached by its storeId in the StoreRegistry. Multiple calls with the same storeId return the same store instance.
• Store is cached as long as it’s being used, and after unusedCacheTime expires (default 60_000 ms in browser, Infinity in non-browser)
• Default store options can be configured in StoreRegistry constructor.
• Store options are only applied when the store is loaded. Subsequent calls with different options will not affect the store if it’s already loaded and cached in the registry.

Throws

unknown - store loading error or if called outside <StoreRegistryProvider>