Hooks API

GuideKit provides focused hooks that subscribe to specific store slices, minimizing re-renders.

useGuideKitStatus

Tracks SDK readiness, agent state, and errors.


const { isReady, agentState, error } = useGuideKitStatus();

Re-renders: Only when status, agentState, or error changes.

Agent State

agentState is a discriminated union:


type AgentState =
  | { status: 'idle' }
  | { status: 'listening'; durationMs: number }
  | { status: 'processing'; transcript: string }
  | { status: 'speaking'; utterance: string }
  | { status: 'error'; error: GuideKitError };

Example


function StatusIndicator() {
  const { isReady, agentState } = useGuideKitStatus();
 
  if (!isReady) return <div>Loading...</div>;
 
  switch (agentState.status) {
    case 'listening':
      return <div>Listening...</div>;
    case 'processing':
      return <div>Thinking about: {agentState.transcript}</div>;
    case 'speaking':
      return <div>Speaking: {agentState.utterance}</div>;
    case 'error':
      return <div>Error: {agentState.error.message}</div>;
    default:
      return <div>Ready</div>;
  }
}

useGuideKitVoice

Controls voice input and text messaging.


const {
  isListening,
  isSpeaking,
  startListening,
  stopListening,
  sendText,
} = useGuideKitVoice();

Re-renders: Only when voice state (isListening, isSpeaking) changes.

Example


function ChatInput() {
  const { sendText, isListening, startListening, stopListening } = useGuideKitVoice();
  const [text, setText] = useState('');
 
  const handleSend = async () => {
    if (!text.trim()) return;
    const response = await sendText(text);
    setText('');
  };
 
  return (
    <div>
      <input value={text} onChange={(e) => setText(e.target.value)} />
      <button onClick={handleSend}>Send</button>
      <button onClick={isListening ? stopListening : startListening}>
        {isListening ? 'Stop' : 'Mic'}
      </button>
    </div>
  );
}

useGuideKitActions

Provides visual guidance functions. Never re-renders (stable function references).


const {
  highlight,
  dismissHighlight,
  scrollToSection,
  startTour,
  navigate,
} = useGuideKitActions();

Example


function TourButton() {
  const { startTour } = useGuideKitActions();
 
  return (
    <button onClick={() => startTour(['hero', 'features', 'pricing'], 'manual')}>
      Start Tour
    </button>
  );
}

highlight()


highlight({
  sectionId: 'pricing',     // Target by section ID
  selector: '#pricing-card', // Or by CSS selector
  tooltip: 'Check out our plans!',
  position: 'top',          // 'top' | 'bottom' | 'left' | 'right' | 'auto'
});

scrollToSection()


scrollToSection('features', 80); // offset for sticky header

useGuideKitContext

Sets page context and registers custom actions. Never re-renders.


const { setPageContext, registerAction } = useGuideKitContext();

Custom Actions


useEffect(() => {
  registerAction('addToCart', {
    description: 'Add a product to the shopping cart',
    parameters: { productId: 'string', quantity: 'number' },
    handler: async ({ productId, quantity }) => {
      await cart.add(productId, quantity);
      return { success: true };
    },
  });
}, [registerAction]);

Page Context


useEffect(() => {
  setPageContext({
    currentUser: user.name,
    subscription: user.plan,
    cartItems: cart.items.length,
  });
}, [user, cart, setPageContext]);

useGuideKitStream

Subscribes to the streaming text slice. Use for displaying real-time LLM output.


const { isStreaming, streamingText, sendTextStream } = useGuideKitStream();

Re-renders: Only when streaming state or text changes.

Example


function StreamingChat() {
  const { isStreaming, streamingText, sendTextStream } = useGuideKitStream();
  const [input, setInput] = useState('');
 
  const handleSend = () => {
    if (!input.trim()) return;
    const { stream, done } = sendTextStream(input);
    setInput('');
  };
 
  return (
    <div>
      <input value={input} onChange={(e) => setInput(e.target.value)} />
      <button onClick={handleSend} disabled={isStreaming}>Send</button>
      {isStreaming && <p>{streamingText}</p>}
    </div>
  );
}

useGuideKitConsent

Manages privacy consent for headless or custom UIs. Persists consent in localStorage per GuideKit instance.


const { hasConsent, grantConsent, revokeConsent } = useGuideKitConsent({
  consentRequired: true,
  instanceId: 'default', // optional, matches GuideKitProvider instanceId
});

When consentRequired is false (default), hasConsent starts as true. When true, the user must call grantConsent() before sending messages or enabling voice.

Re-renders: Only when consent state changes.

See Custom UI (Headless) for a full consent dialog pattern.

useGuideKit (Combined)

Subscribes to all store slices. Use only for prototyping — prefer focused hooks in production.


const {
  isReady, agentState, error,
  isListening, isSpeaking, startListening, stopListening, sendText,
  highlight, dismissHighlight, scrollToSection, startTour, navigate,
  setPageContext, registerAction,
  isStreaming, streamingText, sendTextStream,
} = useGuideKit();

Hook Re-render Behavior

Hook	Re-renders when
`useGuideKitStatus`	Status, agentState, or error changes
`useGuideKitVoice`	Voice state (isListening, isSpeaking) changes
`useGuideKitActions`	Never (stable refs)
`useGuideKitStream`	Streaming state or text changes
`useGuideKitContext`	Never (stable refs)
`useGuideKitConsent`	Consent state changes
`useGuideKit`	Any slice changes