mirror of
https://github.com/hanzoai/ui.git
synced 2026-11-20 20:07:34 +00:00
@hanzo/react
React package for building AI-powered applications with generative UI, where users interact through natural language.
Features
- 🤖 Generative UI - Dynamically render React components in AI responses
- 🔄 Real-time Streaming - Stream AI responses with progress tracking
- 💬 Message Threads - Manage conversation history and context
- 🛠️ Tool Calling - Let AI execute functions during conversations
- 🔌 Model Context Protocol - MCP integration for enhanced AI capabilities
- 🎨 Component Registry - Register custom components for AI to use
- 🔐 Authentication - Built-in auth support for user management
- 📎 File Attachments - Handle images, documents, and other files
- 💡 Smart Suggestions - Provide contextual suggestions to users
- ⚡ TypeScript Support - Full type safety and IntelliSense
Installation
npm install @hanzo/react
# or
pnpm add @hanzo/react
# or
yarn add @hanzo/react
Quick Start
import { HanzoProvider, useMessage } from '@hanzo/react'
function App() {
return (
<HanzoProvider apiKey={process.env.HANZO_API_KEY}>
<ChatInterface />
</HanzoProvider>
)
}
function ChatInterface() {
const { sendMessage, isLoading, lastMessage } = useMessage()
const handleSubmit = async (text: string) => {
const response = await sendMessage(text)
console.log('AI Response:', response)
}
return (
<div>
<input onKeyDown={(e) => {
if (e.key === 'Enter') {
handleSubmit(e.currentTarget.value)
}
}} />
{isLoading && <p>Loading...</p>}
{lastMessage && <div>{lastMessage.content}</div>}
</div>
)
}
Core Concepts
HanzoProvider
The root component that provides Hanzo context to your app:
<HanzoProvider
apiKey="your-api-key"
apiUrl="https://api.hanzo.ai/v1"
model="gpt-4-turbo-preview"
components={[/* your components */]}
tools={[/* your tools */]}
enableStreaming={true}
enableMCP={true}
onMessage={(message) => console.log('New message:', message)}
onError={(error) => console.error('Error:', error)}
>
<YourApp />
</HanzoProvider>
Generative UI Components
Register components that AI can dynamically render:
const components = [
{
name: 'weather-card',
component: WeatherCard,
description: 'Display weather information',
parameters: z.object({
city: z.string(),
temperature: z.number(),
conditions: z.string()
})
}
]
<HanzoProvider components={components}>
{/* AI can now render WeatherCard in responses */}
</HanzoProvider>
Message Hooks
Send messages and handle responses:
// Basic messaging
const { sendMessage, isLoading, error } = useMessage()
// Streaming responses
const { streamMessage, currentMessage, progress } = useStreaming()
Tool Calling
Add tools that AI can execute:
const tools = [
{
name: 'calculator',
description: 'Perform calculations',
parameters: z.object({
expression: z.string()
}),
execute: async ({ expression }) => {
return { result: eval(expression) }
}
}
]
<HanzoProvider tools={tools}>
{/* AI can now use the calculator tool */}
</HanzoProvider>
Available Hooks
useHanzo()- Access complete Hanzo contextuseMessage()- Send messages and manage stateuseStreaming()- Stream AI responses in real-time
Planned: useThread, useComponent, useTool, useGenerativeUI, useSuggestions, useModelConfig, useAttachments, useAuth, and useMCP are not implemented yet.
Examples
Chat Application
import { HanzoProvider, useMessage, useStreaming } from '@hanzo/react'
function ChatApp() {
const [messages, setMessages] = useState([])
const { sendMessage } = useMessage()
const { streamMessage, currentMessage, isStreaming } = useStreaming()
const handleSend = async (text: string) => {
// Add user message
setMessages(prev => [...prev, { role: 'user', content: text }])
// Stream AI response
await streamMessage(text)
// Add AI message when complete
setMessages(prev => [...prev, {
role: 'assistant',
content: currentMessage
}])
}
return (
<div>
{messages.map((msg, i) => (
<div key={i} className={msg.role}>
{msg.content}
</div>
))}
{isStreaming && <div>{currentMessage}</div>}
</div>
)
}
Custom Components
// Define a custom visualization component
function DataChart({ data, type }) {
return <Chart data={data} type={type} />
}
// Register it with Hanzo
const components = [
{
name: 'data-chart',
component: DataChart,
description: 'Visualize data in a chart',
parameters: z.object({
data: z.array(z.number()),
type: z.enum(['bar', 'line', 'pie'])
})
}
]
// Use in your app
<HanzoProvider components={components}>
<ChatInterface />
</HanzoProvider>
Tool Integration
const tools = [
{
name: 'fetchData',
description: 'Fetch data from API',
parameters: z.object({
endpoint: z.string().url()
}),
execute: async ({ endpoint }) => {
const response = await fetch(endpoint)
return response.json()
}
},
{
name: 'saveToDatabase',
description: 'Save data to database',
parameters: z.object({
collection: z.string(),
data: z.any()
}),
execute: async ({ collection, data }) => {
await db.collection(collection).insert(data)
return { success: true }
}
}
]
<HanzoProvider tools={tools}>
{/* AI can now fetch data and save to database */}
</HanzoProvider>
TypeScript
Full TypeScript support with type definitions:
import type {
HanzoComponent,
HanzoTool,
Message,
Thread
} from '@hanzo/react'
const component: HanzoComponent = {
name: 'my-component',
component: MyComponent,
description: 'A typed component',
parameters: z.object({
title: z.string(),
count: z.number()
})
}
const tool: HanzoTool = {
name: 'my-tool',
description: 'A typed tool',
parameters: z.object({
input: z.string()
}),
execute: async ({ input }) => {
return { processed: input.toUpperCase() }
}
}
API Reference
HanzoProvider Props
| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
apiKey |
string |
Yes | - | Your Hanzo API key |
apiUrl |
string |
No | https://api.hanzo.ai/v1 |
API endpoint URL |
model |
string |
No | gpt-4-turbo-preview |
AI model to use |
components |
HanzoComponent[] |
No | [] |
Registered components |
tools |
HanzoTool[] |
No | [] |
Available tools |
initialMessages |
Message[] |
No | [] |
Initial conversation |
enableStreaming |
boolean |
No | true |
Enable streaming |
enableMCP |
boolean |
No | false |
Enable MCP |
onMessage |
(message: Message) => void |
No | - | Message callback |
onError |
(error: Error) => void |
No | - | Error callback |
Hook Options
Most hooks accept configuration options:
const { sendMessage } = useMessage({
threadId: 'custom-thread',
onSuccess: (message) => console.log('Sent:', message),
onError: (error) => console.error('Error:', error),
autoRetry: true,
maxRetries: 3,
retryDelay: 1000
})
const { streamMessage } = useStreaming({
onChunk: (chunk) => console.log('Chunk:', chunk),
onComplete: (message) => console.log('Complete:', message),
bufferSize: 5,
throttleMs: 100
})
License
MIT © Hanzo AI, Inc. — see LICENSE.md. HIP-0137 (hanzoai/hips).
Support
- Documentation: https://ui.hanzo.ai/docs/hanzo-react
- GitHub: https://github.com/hanzoai/ui
- Discord: https://discord.gg/CJCyAsm9Vr