useNativeAI

React hook for on-device Native AI completion and streaming.

Overview

The useNativeAI hook provides conversation state management, real-time streaming responses, and structured prompt querying using Google Chrome's built-in Gemini Nano model. It automatically manages adapter initialization, session state, token context tracking, and follow-up query parsing.

Installation

NPM

pnpm

Yarn

Bun

npm install npx shadcn@latest add @paceui/native-ai-use-native-ai

Usage

Here is an example of using useNativeAI in a custom component:

CustomChat.tsx

import { useState } from "react";
import { useNativeAI } from "@/hooks/native-ai/use-native-ai";

export function CustomChat() {
  const [input, setInput] = useState("");
  const { filteredMessages, isLoading, sendMessage, contextInfo, lastAnswers } = useNativeAI({
      initialSystemPrompt: "You are a helpful coding assistant.",
  });

  const handleSend = async () => {
      if (!input.trim()) return;
      const text = input;
      setInput("");
      await sendMessage({
          message: { role: "user", content: text }
      });
  };

  return (
      <div>
          <div className="messages">
              {filteredMessages.map((msg, i) => (
                  <div key={i} className={"message " + msg.role}>
                      <strong>{msg.role}: </strong> {msg.content}
                  </div>
              ))}
          </div>
          {contextInfo && (
              <div className="token-usage">
                  Token Usage: {contextInfo.used} / {contextInfo.window}
              </div>
          )}
          <input
              value={input}
              onChange={(e) => setInput(e.target.value)}
              disabled={isLoading}
          />
          <button onClick={handleSend} disabled={isLoading}>
              {isLoading ? "Generating..." : "Send"}
          </button>
      </div>
  );
}

API Reference

Parameters

Option	Type	Description	Default
`initialSystemPrompt`	`string`	The system prompt to initialize the model with.	`"You are a helpful, concise AI assistant."`
`eagerLoaded`	`boolean`	If true, initializes the AI model on mount.	`true`
`autoCancelOnNextPrompt`	`boolean`	If true, automatically cancels any active main message stream or side tasks when a new prompt arrives.	`true`

Returns

Property	Type	Description
`messages`	`Message[]`	Complete conversation history including system messages.
`filteredMessages`	`Message[]`	Clean user/assistant messages suitable for UI rendering.
`isLoading`	`boolean`	`true` if the model is currently generating a main chat response.
`isTaskLoading`	`(taskId?: string) => boolean`	Returns true if side tasks (or specific `taskId`) are evaluating.
`loadingTasks`	`Record<string, boolean>`	Map of active loading tasks by task ID.
`getTaskResult`	`(taskId: string) => TaskResult \| undefined`	Helper to retrieve parsed task results by task ID.
`clearTaskResults`	`(taskId?: string) => void`	Helper to clear all or specific task results.
`isInitializing`	`boolean`	`true` if the local model adapter is initializing.
`status`	`"loading" \| "ready" \| "lazy"`	Current status of the AI engine adapter.
`sendMessage`	`(args: { message: Message; tasks?: Task[] }) => Promise<void>`	Sends a message and optionally evaluates batch side tasks.
`stop`	`() => Promise<void>`	Aborts and stops active response generation and side tasks.
`stopStream`	`() => Promise<void>`	Alias for `stop()`.
`resetChat`	`() => Promise<void>`	Resets conversation state back to initial system prompt.
`reset`	`() => Promise<void>`	Alias for `resetChat()`.
`taskResults`	`TaskResult[]`	Results generated from background side tasks.
`contextInfo`	`{ used: number; window: number } \| null`	Information about current token usage and model context window.

Types

types.ts

export type UseNativeAIProps = UseNativeAICoreProps & {
  autoCancelOnNextPrompt?: boolean;
};

export type Message = {
  role: "system" | "user" | "assistant";
  content: string;
  custom?: boolean;
};

export type Task = {
  id: string;
  type: "single" | "multiple";
  prompt: string;
};

export type TaskResult = {
  id: string;
  value: string[] | string;
};

useBrowserSupport