SuperinterfaceProvider
Use the
<SuperinterfaceProvider> component to provide context like query and
mutation functions to other Superinterface components and hooks.app.tsx
import { SuperinterfaceProvider, Thread } from '@superinterface/react'
export const App = () => (
<SuperinterfaceProvider>
<Thread />
</SuperinterfaceProvider>
)
Props
Here's a summary of the props available for the
<SuperinterfaceProvider> component:Good to know:
You can also use
setQueryDefaults and
setMutationDefaults from Tanstack Query
to define custom query and mutation functions instead of using default ones from Superinterface Cloud. See setQueryDefaults and setMutationDefaults for more information.
.baseUrl
app.tsx
import { SuperinterfaceProvider, Thread } from '@superinterface/react'
export const App = () => (
<SuperinterfaceProvider baseUrl="http://localhost:3000/api">
<Thread />
</SuperinterfaceProvider>
)
This sets the
baseUrl that will be used for query and mutation requests.variables
app.tsx
import { SuperinterfaceProvider, Thread } from '@superinterface/react'
export const App = () => (
<SuperinterfaceProvider variables={{ assistantId: 'asst_123' }}>
<Thread />
</SuperinterfaceProvider>
)
When you set
variables, these things happen:variables are merged into all child Superinterface query and mutation keys as the
second parameter (e.g. const [keyBase, { assistantId }] = queryKey and
const [keyBase, { assistantId }] = mutationKey). This allows you to use
variables in all child queryFn functions.variables are merged into all child Superinterface mutation variables. This
allows you to use variables in all child mutationFn functions.defaultOptions
app.tsx
import { SuperinterfaceProvider, Thread } from '@superinterface/react'
const threadId = 'thread_123'
export const App = () => (
<SuperinterfaceProvider
defaultOptions={{
queries: {
enabled: !!threadId,
},
mutations: {
onSuccess: () => console.log('Succeeded!'),
},
}}
>
<Thread />
</SuperinterfaceProvider>
)
defaultOptions work exactly as Tanstack Query defaultOptions.
This passes options to child Superinterface queries and mutations.threadIdStorageOptions
app.tsx
import { useMemo, useState } from 'react'
import { SuperinterfaceProvider, Thread } from '@superinterface/react'
export const App = () => {
const [threadId, setThreadId] = useState<string | null>(null)
const threadIdStorageOptions = useMemo(
() => ({
get: () => threadId,
set: ({ threadId }: { assistantId: string; threadId: string }) => {
setThreadId(threadId)
},
remove: () => {
setThreadId(null)
},
}),
[threadId],
)
return (
<SuperinterfaceProvider
variables={{ assistantId: 'asst_123' }}
threadIdStorageOptions={threadIdStorageOptions}
>
<Thread />
</SuperinterfaceProvider>
)
}
Override the default thread ID persistence by passing custom
threadIdStorageOptions. When you provide an assistantId but omit a
threadId, @superinterface/react calls get to reuse the last stored thread
ID for that assistant.After a new thread is created—typically when the first
message is sent—the library calls
set with the created thread metadata, and
flows like a reset action can call remove to clear it.For advanced scenarios with multiple assistants, you can still keep a
per-assistant map, for example by storing IDs in a ref or external store and
mapping the
get, set, and remove callbacks accordingly.Without overrides the provider chooses
cookieThreadIdStorageOptions, or
localStorageThreadIdStorageOptions when running inside an iframe. Use custom
storage to keep thread IDs in React state, synchronize them with your own
stores, or integrate with server state. See
Thread ID storage for built-in helpers.setQueryDefaults and setMutationDefaults
app.tsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { SuperinterfaceProvider, Thread } from '@superinterface/react'
const queryClient = new QueryClient({
defaultOptions: {
queries: {
staleTime: 10000,
},
},
})
queryClient.setMutationDefaults(['createMessage'], {
mutationFn: (variables) => {
console.log('Called createMessage')
},
})
queryClient.setMutationDefaults(
['createMessage', { assistantId: 'asst_123' }],
{
mutationFn: (variables) => {
console.log(`Called mutationFn this assistant: ${variables.assistantId}`)
},
},
)
export const App = () => (
<QueryClientProvider client={queryClient}>
<SuperinterfaceProvider>
<Thread />
</SuperinterfaceProvider>
</QueryClientProvider>
)
You can use
setQueryDefaults and
setMutationDefaults from Tanstack Query
to define custom query and mutation functions instead of using default ones from Superinterface Cloud.This allows you to use server actions from
Next.js.