@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

``bash
npm install @hanzo/react


or

pnpm add @hanzo/react

or

yarn add @hanzo/react
`

Quick Start

`tsx
import { HanzoProvider, useMessage } from '@hanzo/react'

function App() {
return (



)
}

function ChatInterface() {
const { sendMessage, isLoading, lastMessage } = useMessage()

const handleSubmit = async (text: string) => {
const response = await sendMessage(text)
console.log('AI Response:', response)
}

return (



)
}
`

Core Concepts

$3

The root component that provides Hanzo context to your app:

`tsx
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)}
>


`

$3

Register components that AI can dynamically render:

`tsx
const components = [
{
name: 'weather-card',
component: WeatherCard,
description: 'Display weather information',
parameters: z.object({
city: z.string(),
temperature: z.number(),
conditions: z.string()
})
}
]


{/ AI can now render WeatherCard in responses /}

`

$3

Send messages and handle responses:

`tsx
// Basic messaging
const { sendMessage, isLoading, error } = useMessage()

// Streaming responses
const { streamMessage, currentMessage, progress } = useStreaming()

// Thread management
const { threads, activeThread, createThread, switchThread } = useThread()
`

$3

Add tools that AI can execute:

`tsx
const tools = [
{
name: 'calculator',
description: 'Perform calculations',
parameters: z.object({
expression: z.string()
}),
execute: async ({ expression }) => {
return { result: eval(expression) }
}
}
]


{/ AI can now use the calculator tool /}

`

Available Hooks

$3


- useHanzo() - Access complete Hanzo context
- useMessage() - Send messages and manage state
- useStreaming() - Stream AI responses in real-time
- useThread() - Manage conversation threads

$3

- useComponent() - Dynamically register/render components
- useTool() - Execute and manage AI tools
- useGenerativeUI() - Generate UI components on the fly

$3

- useSuggestions() - Provide intelligent suggestions
- useModelConfig() - Configure and switch AI models
- useAttachments() - Handle file attachments
- useAuth() - Manage user authentication
- useMCP() - Model Context Protocol integration

Examples

$3

`tsx
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 (



)
}
`

$3

`tsx
// Define a custom visualization component
function DataChart({ data, type }) {
return
}

// 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



`

$3

`tsx
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 }
}
}
]


{/ AI can now fetch data and save to database /}

`

TypeScript

Full TypeScript support with type definitions:

`tsx
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

$3

| 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 |

$3

Most hooks accept configuration options:

`tsx
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

BSD-3-Clause © Hanzo AI, Inc.

Support

- Documentation: https://ui.hanzo.ai/docs/hanzo-react
- GitHub: https://github.com/hanzoai/ui
- Discord: https://discord.gg/hanzo