@navieo/react
v1.7.0
Published
AI-powered contextual site guide SDK for React
Maintainers
navieo-orgReadme
@navieo/react
Navieo's drop-in React SDK — chat widget that answers questions about your app (ask mode) and plays pre-authored, interactive UI tours via Driver.js.
Stage 1 product reality: The widget is currently ask-only. Dynamic LLM-generated tours are dormant behind the
GUIDE_MODE_ENABLEDbackend flag and will return in Stage 3. Suggestion chips with atourSlugfield play pre-authored tours deterministically viaplayTour(slug). Seenavieo/docs/01-product-stage-1.md.
Install
pnpm add @navieo/react
# or: npm i @navieo/react / yarn add @navieo/react@navieo/core and @navieo/types come transitively — you don't install them directly.
Quick start
Next.js (recommended)
// app/layout.tsx
import { NavieoNextProvider } from "@navieo/react/next";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
<NavieoNextProvider
apiKey={process.env.NEXT_PUBLIC_NAVIEO_PUBLISHABLE_KEY!}
apiBaseUrl="https://api.navieo.io/api"
suggestions={[
// tourSlug → plays an authored tour deterministically (no LLM call)
{ label: "Walk me through requesting time off", tourSlug: "request-time-off" },
// no tourSlug → sends label as a free-form ask query
{ label: "What's the PTO policy?", tag: "Popular" },
]}
>
{children}
</NavieoNextProvider>
</body>
</html>
);
}The Next.js wrapper handles route detection + router.push navigation automatically.
Any React app
import { NavieoProvider } from "@navieo/react";
import { useLocation, useNavigate } from "react-router-dom";
function App() {
const location = useLocation();
const navigate = useNavigate();
return (
<NavieoProvider
apiKey={import.meta.env.VITE_NAVIEO_KEY}
currentRoute={location.pathname}
onNavigate={(route) => navigate(route)}
suggestions={[{ label: "How do I…", tourSlug: "my-tour" }]}
>
<YourApp />
</NavieoProvider>
);
}Public exports
| Export | Description |
|---|---|
| NavieoProvider | Context provider — chat state, tour state, authoring mode |
| NavieoNextProvider (from @navieo/react/next) | Next.js wrapper — auto wires usePathname + useRouter |
| ChatWidget | Floating chat widget. Auto-mounted by NavieoProvider; export available for custom placement |
| useNavieo | Hook returning { chatHistory, sendMessage, playTour, tourState, openWidget, closeWidget } |
| useTourRenderer | Lower-level hook for custom tour rendering (advanced) |
| darkTheme, lightTheme, themes, resolveTheme | Theme tokens + helper for custom theme prop |
| logger (re-export from @navieo/core) | Browser-side logger respecting logLevel prop |
Full type signatures: import type { NavieoProviderProps, NavieoTheme, NavieoResolvedTheme } from "@navieo/react".
Key props on NavieoProvider
| Prop | Required | Purpose |
|---|---|---|
| apiKey | yes | Publishable key — nv_p… — generated in the Navieo dashboard |
| apiBaseUrl | optional | Defaults to https://api.navieo.io/api. Override for self-hosted or dev backend |
| currentRoute | yes (non-Next) | Current path; Next wrapper sets this automatically |
| onNavigate | yes (non-Next) | Programmatic nav for tours that span pages |
| suggestions | optional | Chat empty-state chips. tourSlug → authored tour. No slug → ask query |
| theme | optional | "dark" \| "light" or a NavieoTheme object |
| logLevel | optional | "silent" \| "error" \| "warn" \| "info" \| "debug" (default "warn") |
Authored tour playback (Stage 1 entry points)
- Suggestion chip with
tourSlug— clicked in chat widget empty state playTour(slug)fromuseNavieo()— programmatic launch (e.g. button onclick)- Deep link — visit
?tour=<slug>or#navieo-tour=<slug>— slug consumed on mount, URL cleaned
All three resolve through the same playTour path: fetch from /api/tour/:slug (API-key auth), validate steps, hand off to the Driver.js renderer.
Requirements
- React 18 or 19 (peer)
- React-DOM 18 or 19 (peer)
- Next.js 14+ (optional peer — only required when using
@navieo/react/next) - Node 20+ (Node 24+ tested) for tooling
- A Navieo backend (defaults to hosted
api.navieo.io)
Architecture
The internal module map, Driver.js overlay rules, memoization split, and dormant Stage 3 boundaries live in navieo-sdk/ARCHITECTURE.md. The full SDK guide is in the platform repo at navieo/docs/05-sdk.md.
License
Proprietary.