react-web-llm-hooks

A Scalable, High-Performance React Hook for Running LLMs Directly in the Browser

react-web-llm-hooks is a lightweight and powerful React hook that brings Large Language Models directly to your browser. Built on top of @mlc-ai/web-llm, it enables you to integrate AI capabilities into React applications without any backend server—everything runs locally in the user's browser.

Why react-web-llm-hooks?

Feature	Description
🚀 Zero-Server Architecture	No API calls, no server costs, no latency. All inference happens in the browser.
📦 Scalable by Design	Modular hook API that grows with your application—from simple chatbots to complex AI features.
⚡ High Performance	Leverages WebGPU for accelerated inference. Optimized for modern browsers.
🔌 Framework Agnostic	Works seamlessly with any React setup—Next.js, Vite, Remix, CRA, and more.
🔒 Privacy First	User data never leaves their device. Perfect for privacy-sensitive applications.
🎯 Production Ready	TypeScript support out of the box, battle-tested patterns, clean API surface.

Quick Start

Installation

npm install @mlc-ai/web-llm react-web-llm-hooks
# or
yarn add @mlc-ai/web-llm react-web-llm-hooks

Basic Usage

import { useWebLLM } from 'react-web-llm-hooks';

function ChatComponent() {
  const { isReady, status, response, send } = useWebLLM();

  const handleSend = () => {
    send('Hello, world!');
  };

  if (!isReady) {
    return <div>Loading model... {status}</div>;
  }

  return (
    <div>
      <p>Response: {response}</p>
      <button onClick={handleSend}>Send Message</button>
    </div>
  );
}

Configuration Options

const { send } = useWebLLM({
  model: 'Qwen2.5-1.5B-Instruct-q4f32_1-MLC', // Default model
  temperature: 0.7,
  maxTokens: 1024,
});

API Reference

useWebLLM(options?)

The primary hook for integrating WebLLM into your React components.

Options

Option	Type	Default	Description
model	string	'Qwen2.5-1.5B-Instruct-q4f32_1-MLC'	The LLM model to load. See supported models.
temperature	number	0.7	Controls randomness in output generation. Lower values = more focused.
maxTokens	number	1024	Maximum number of tokens to generate.
progressCallback	function	undefined	Callback for model loading progress.

Returns

Property	Type	Description
isReady	boolean	Whether the model has finished loading.
status	string	Current loading status or error message.
response	string	The latest generated response.
send(message: string)	function	Send a message and get a response.

Architecture

┌─────────────────────────────────────────────────────────┐
│                    Your React App                        │
├─────────────────────────────────────────────────────────┤
│              react-web-llm-hooks                         │
│  ┌─────────────────────────────────────────────────────┐│
│  │                   useWebLLM Hook                     ││
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ││
│  │  │  Engine     │  │   State     │  │   Utils     │  ││
│  │  │  Manager    │→│  Management  │→│  & Helpers  │  ││
│  │  └─────────────┘  └─────────────┘  └─────────────┘  ││
│  └─────────────────────────────────────────────────────┘│
├─────────────────────────────────────────────────────────┤
│                   @mlc-ai/web-llm                        │
│         (WebGPU-powered LLM inference engine)            │
├─────────────────────────────────────────────────────────┤
│                      WebGPU                              │
│         (Browser-native GPU acceleration)                │
└─────────────────────────────────────────────────────────┘

Supported Models

Model	Size	Memory	Performance
Qwen2.5-1.5B-Instruct	1.5B	~2GB VRAM	⚡ Fast
Qwen2.5-3B-Instruct	3B	~4GB VRAM	⚡ Fast
Llama-3.2-3B-Instruct	3B	~4GB VRAM	⚡ Fast
Gemma-2-2B-it	2B	~3GB VRAM	⚡ Fast

View all supported models →

Browser Compatibility

• Chrome 113+ (with WebGPU support)
• Edge 113+
• Firefox (WebGPU in development)
• Safari 17+ (WebGPU support)

Note: WebGPU must be enabled in your browser settings.

Contributing

We welcome contributions! Whether you're fixing bugs, adding features, or improving documentation—your help makes this project better.

Getting Started

1. Fork the repository on GitHub
2. Clone your fork locally:

   git clone https://github.com/YOUR_USERNAME/react-web-llm-hooks.git
   cd react-web-llm-hooks

3. Install dependencies:

   npm install

4. Start the development server:

   npm run dev

5. Create a feature branch:

   git checkout -b feature/amazing-new-feature

6. Make your changes and commit:

   git commit -m "Add amazing new feature"

7. Push and open a Pull Request:

   git push origin feature/amazing-new-feature

Areas for Contribution

• 📝 Documentation - Improve guides, add examples, fix typos
• 🐛 Bug Fixes - Find and fix issues in the codebase
• ✨ New Features - Add model support, configuration options
• 🎨 Examples - Create demo apps, integration guides
• ⚡ Performance - Optimize inference, reduce memory usage
• 🧪 Testing - Add unit tests, integration tests

Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.

Roadmap

• Multiple model support with dynamic switching
• Streaming responses support
• Conversation history management
• Custom system prompts
• Plugin system for preprocessing/postprocessing
• React Native support
• Comprehensive test suite
• Demo application with multiple use cases

License

MIT License - see LICENSE for details.

Acknowledgments

• @mlc-ai/web-llm - The amazing engine that powers this project
• Vite - Next-generation frontend tooling
• Tailwind CSS - Utility-first CSS framework

Star History

If you find this project useful, please consider giving it a ⭐️ star on GitHub! It helps others discover the project and motivates continued development.

---

Questions? Issues? Feature requests?

Open an issue on GitHub—we'd love to hear from you!