A sophisticated chat-optimized component library with FastAPI backend and AI integration.
📖 Documentation • 🧩 Components • 🚀 Getting Started • ⚡ Features
HAX UI Registry is an enterprise-grade component library that combines the power of Shadcn/ui with specialized chat-optimized components. Built with modern React patterns, TypeScript, and FastAPI backend, it provides a comprehensive solution for building sophisticated chat interfaces with AI integration capabilities.
- 🔧 Dual-Registry System: Seamlessly use both standard Shadcn/ui and HAX components
- 💬 Chat-Optimized: Specialized components for chat interfaces with advanced features
- 🤖 AI Integration: Built-in support for Google Gemini API with BYOK architecture
- ⚡ FastAPI Backend: Modern async Python backend with automatic API documentation
- 🌊 Real-time Streaming: Server-Sent Events for real-time chat responses
- 📦 uv Package Management: Fast, modern Python dependency management
- ♿ Accessibility: WCAG-compliant components with ARIA support
- 🔒 Security: Built-in security scanning and vulnerability detection
- 🐳 Docker Ready: Production-ready containerization for easy deployment
- Node.js: >= 20.0.0
- Python: >= 3.11
- pnpm: >= 10.14.0
- uv: Fast Python package manager
- Git: For version control
-
Clone the repository:
git clone https://github.com/Qredence/hax-ui.git cd hax-ui -
Install frontend dependencies:
pnpm install
-
Setup backend with uv:
cd backend curl -LsSf https://astral.sh/uv/install.sh | sh # Install uv if needed ./start.sh # Creates .venv and starts FastAPI server
-
Start frontend (in another terminal):
pnpm dev
-
Access the application:
- Frontend: http://localhost:8080
- Backend API Docs: http://localhost:8000/api/v1/docs
- Health Check: http://localhost:8000/health
# Quick start with Docker Compose
docker-compose up -d
# Access at http://localhost:8080- Google Gemini API: Advanced AI chat with streaming responses
- BYOK Architecture: Bring Your Own Key for security
- Thought Processing: Visualize AI reasoning process
- Real-time Streaming: Instant response streaming via SSE
- Dual Registry: Use both Shadcn/ui and HAX components
- TailwindCSS: Utility-first styling with custom design tokens
- Consistent Variants: Unified design language across components
- Custom Themes: Easy theme customization and dark mode
- Type Safety: Full TypeScript frontend + Pydantic backend
- Security Headers: CORS, CSP, and other security measures
- Input Validation: Comprehensive request/response validation
- Error Handling: Graceful error handling and user feedback
- Hot Reload: Instant development feedback
- Component Registry: Install components via CLI
- API Documentation: Automatic OpenAPI docs generation
- Comprehensive Testing: Vitest (frontend) + pytest (backend)
Advanced chat input with thinking mode and auto-resize:
import { HaxChatInput } from '@/components/hax/chat/chat-input'
<HaxChatInput
input={input}
onInputChange={setInput}
onSubmit={sendMessage}
isLoading={isLoading}
thinkingMode={thinkingMode}
onToggleThinking={toggleThinking}
/>Rich message display with thought processing:
import { HaxChatMessage } from '@/components/hax/chat/chat-message'
<HaxChatMessage
message={{
id: '1',
content: 'Hello! How can I help?',
role: 'assistant',
timestamp: new Date(),
thoughts: 'User is greeting me, I should respond warmly'
}}
showActions={true}
/>Full conversation interface with auto-scroll:
import { HaxChatConversation } from '@/components/hax/chat/chat-conversation'
<HaxChatConversation
messages={messages}
onSendMessage={sendMessage}
isLoading={isLoading}
/>Chat-optimized button variants:
import { HaxButton } from '@/components/hax/ui/button'
<HaxButton variant="chat-send" size="chat-icon">
<ArrowUp size={16} />
</HaxButton>Variants: default, chat, chat-send, chat-thinking
Sizes: default, sm, lg, icon, chat-icon
# Frontend Development
pnpm dev # Start Vite dev server (port 8080)
pnpm build # Production build
pnpm test # Run Vitest tests
pnpm typecheck # TypeScript validation
# Backend Development (uses uv)
cd backend
./start.sh # Quick start (creates .venv automatically)
uv run pytest # Run tests
uv sync --dev # Install dependencies
# Full Stack
docker-compose up # Start entire stack├── client/ # React frontend
│ ├── components/hax/ # HAX component system
│ │ ├── ui/ # HAX UI components
│ │ ├── chat/ # Chat components
│ │ └── layout/ # Layout components
│ ├── services/ # API services
│ └── hooks/ # React hooks
├── backend/ # FastAPI Python backend
│ ├── app/
│ │ ├── api/v1/ # API endpoints
│ │ ├── services/ # Business logic
│ │ └── schemas/ # Pydantic models
│ └── .venv/ # Local virtual environment
├── hax-registry/ # Component registry definitions
└── docs/ # Documentation
- Backend API Documentation - FastAPI setup and API reference
- Deployment Guide - Production deployment instructions
- Component Documentation - Detailed component guides
- Development Guide - Development setup and workflows
# Production deployment
cp .env.production .env
docker-compose up -d# Backend
cd backend
uv sync --frozen --no-dev
uv run uvicorn app.main:app --host 0.0.0.0 --port 8000
# Frontend
pnpm build
# Serve dist/spa/ with your web serverSupported platforms:
- Railway - Auto-deploy from GitHub
- Vercel - Frontend deployment
- DigitalOcean - Full stack deployment
- AWS/Azure - Enterprise deployment
- Fork the repository
- Create feature branch:
git checkout -b feature/amazing-feature - Run tests:
pnpm test && cd backend && uv run pytest - Commit changes:
git commit -m 'Add amazing feature' - Push to branch:
git push origin feature/amazing-feature - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- Shadcn/ui - Incredible component system
- FastAPI - Modern Python web framework
- uv - Fast Python package management
- TailwindCSS - Utility-first CSS framework
- Google Gemini - Advanced AI capabilities
Built with ❤️ using HAX UI Registry