@ai-guide/react
v0.15.14
Published
React components for AI Guide.
Maintainers
skirianovReadme
@ai-guide/react
AI-powered UI guidance component for React applications. Help your users navigate your application with natural language queries.
✨ SSR-Safe - Fully compatible with Next.js, Remix, and other SSR frameworks with zero configuration.
Installation
npm install @ai-guide/react
# or
pnpm add @ai-guide/react
# or
yarn add @ai-guide/reactQuick Start
Next.js App Router (SSR-Safe)
// app/layout.tsx
import { AiGuide } from '@ai-guide/react';
import '@ai-guide/react/styles.css';
export default function RootLayout({ children }) {
return (
<html>
<body>
{children}
<AiGuide projectId="your-project-id" />
</body>
</html>
);
}Next.js Pages Router
// pages/_app.tsx
import { AiGuide } from '@ai-guide/react';
import '@ai-guide/react/styles.css';
export default function App({ Component, pageProps }) {
return (
<>
<Component {...pageProps} />
<AiGuide projectId="your-project-id" />
</>
);
}Vite / Create React App
import { AiGuide } from '@ai-guide/react';
import '@ai-guide/react/styles.css';
function App() {
return (
<>
<YourApplication />
<AiGuide projectId="your-project-id" />
</>
);
}Features
- ✨ Natural language interface for user guidance
- 🎯 Real-time element highlighting with Shadow Realm isolation
- 📝 Step-by-step interactive instructions
- 🔒 Built-in safety validation and confidence scoring
- 🌐 100% SSR-safe - Works with Next.js, Remix, Gatsby, etc.
- 🎨 Complete z-index isolation (no conflicts)
- 🪝 React hooks for programmatic control
- 🔄 Version handshake protocol (prevents stale builds)
- 🚀 Lazy loaded for optimal performance
Usage
Basic Setup
Add the AiGuide component to your application (it renders a floating help bubble):
import { AiGuide } from '@ai-guide/react';
function App() {
return (
<>
<YourApplication />
<AiGuide
projectId="your-project-id"
apiUrl="https://your-backend.com/api/guide"
/>
</>
);
}The component is automatically SSR-safe - no additional configuration needed!
Programmatic Usage with Hooks
import { useAiGuide } from '@ai-guide/react';
function MyComponent() {
const { guide, isLoading, error } = useAiGuide();
const handleHelp = async () => {
await guide('How do I export my data?');
};
return (
<button onClick={handleHelp} disabled={isLoading}>
{isLoading ? 'Loading...' : 'Get Help'}
</button>
);
}Tagging Elements
Add data-aid attributes to make elements easily discoverable:
<button data-aid="submit-form">Submit</button>
<input data-aid="email-input" type="email" />
<div data-aid="export-menu">Export Options</div>API
AiGuide Props
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| projectId | string | required | Your AI Guide project ID |
| apiUrl | string | optional | Custom backend API endpoint |
| useShadowDOM | boolean | false | Enable Shadow DOM for complete CSS isolation |
useAiGuide Hook
Returns an object with:
guide(query: string)- Start a guidance flow with a natural language queryisLoading: boolean- Whether a guidance request is in progresserror: Error | null- Any error that occurredcurrentStep: number- Current step index in the guidance flowtotalSteps: number- Total number of stepsreset()- Reset the guidance state
Example Queries
Users can ask questions like:
- "How do I submit the contact form?"
- "Where is the export button?"
- "How do I enable email notifications?"
- "Show me how to delete my account"
SSR Compatibility
This package is 100% SSR-safe out of the box. It uses:
- React.lazy() for code splitting
- Client-side only rendering
- Runtime guards for browser APIs
See SSR Safety Documentation for details.
Requirements
- React 18.0.0 or higher (React 19 supported)
- Node.js 18.0.0 or higher
Related Packages
@ai-guide/types- Shared types and schemas
License
MIT