Hooks

@tour-kit/ai ships its state and actions through React hooks. Components built on top of these hooks (see Components) are convenient defaults — every screen the package renders can also be built from scratch with the hooks below.

All hooks must be called inside an <AiChatProvider> unless noted otherwise.

useAiChat

Primary chat-state hook. Returns the message list, send/stop/reload actions, and panel open/close state.

import { useAiChat } from '@tour-kit/ai'

function CustomChat() {
  const { messages, status, sendMessage, isOpen, toggle } = useAiChat()

  return (
    <>
      <button onClick={toggle}>{isOpen ? 'Close' : 'Open'} chat</button>
      {isOpen && (
        <div>
          {messages.map((m) => <div key={m.id}>{m.content}</div>)}
          <button onClick={() => sendMessage({ text: 'Hello' })}>Send</button>
        </div>
      )}
    </>
  )
}

Return Value

useAiChatContext

Low-level access to the full provider context. Throws if no AiChatProvider is mounted above. Most consumers should reach for useAiChat instead — useAiChatContext is the unsafe escape hatch when you need raw context state (config, internal state machines, custom integrations).

import { useAiChatContext } from '@tour-kit/ai'

function ConfigDebugger() {
  const ctx = useAiChatContext()
  return <pre>{JSON.stringify(ctx.config, null, 2)}</pre>
}

Returns the full AiChatContextValue. See API Reference for the complete shape.

useSuggestions

Returns the merged static + dynamic suggestion list and helpers to refresh/select.

import { useSuggestions } from '@tour-kit/ai'

function CustomSuggestions() {
  const { suggestions, isLoading, isBusy, select } = useSuggestions()

  if (isLoading) return <Spinner />
  return suggestions.map((s) => (
    <button key={s} onClick={() => select(s)} disabled={isBusy}>
      {s}
    </button>
  ))
}

Return Value

useSuggestions works both inside and outside AiChatProvider — returns an empty state when no context.

useOptionalSuggestions (deprecated)

Alias for useSuggestions retained for backward compatibility. Will be removed in the next major version. Prefer useSuggestions.

useTourAssistant

Tour-aware extension of useAiChat. Adds the active tour, active step, and checklist progress to the assistant context, so the model can answer questions like "what should I do next?".

import { useTourAssistant } from '@tour-kit/ai'

function ContextualChat() {
  const { messages, sendMessage, isLoading, activeTourContext } = useTourAssistant()
  // activeTourContext.activeTour.currentStep is available for inline UI
  return /* ... */
}

Returns UseTourAssistantReturn, which extends UseAiChatReturn with isLoading: boolean and tour-context fields. See API Reference for the full shape.