Provider Setup

The NavieoProvider is the core of Navieo. It manages the chat widget, tour state, and communication with Navieo's API. It works out of the box with zero configuration.

Zero-Config Usage

import { NavieoProvider } from "@navieo/react";

function App() {
  return (
    <NavieoProvider>
      {children}
    </NavieoProvider>
  );
}

The SDK automatically:

Detects the current route from window.location.pathname (and polls for SPA navigation changes)
Handles navigation via window.location.href (full page reload)
Connects to Navieo's API using your publishable key from NEXT_PUBLIC_NAVIEO_PUBLISHABLE_KEY

Next.js Convenience Wrapper

For Next.js applications, use NavieoNextProvider which uses usePathname() and useRouter().push() for seamless SPA navigation:

"use client";

import { NavieoNextProvider } from "@navieo/react/next";

export function Providers({ children }) {
  return (
    <NavieoNextProvider>
      {children}
    </NavieoNextProvider>
  );
}

Props Reference

NavieoProvider

All props are optional. The provider works with zero configuration.

Prop	Type	Default	Description
`currentRoute`	`string`	Auto-detected	Current pathname. Auto-detected from `window.location.pathname` and updated on SPA navigation. Override only if your framework uses non-standard routing.
`onNavigate`	`(route: string) => void`	`window.location.href`	Called when a tour needs to navigate to a different route. Pass `router.push` for SPA navigation without full page reloads.
`appId`	`string`	Resolved from API key	Application identifier. The backend resolves this from your API key — you almost never need to set this.
`suggestions`	`Array<{ label: string; tag?: string }>`	—	Suggestion chips shown in the empty chat state.
`renderChat`	`boolean`	`true`	Whether to render the built-in ChatWidget. Set to `false` to build a fully custom UI using the `useNavieo` hook.
`showWidget`	`boolean`	`true`	Whether to show the widget on the current page. Useful for hiding the widget on specific routes (e.g., login pages).
`theme`	`NavieoTheme`	`"light"`	Theme configuration. Pass `"dark"`, `"light"`, or a custom theme object. See Themes.
`publishableKey`	`string`	Env var	Publishable API key. If omitted, reads from `NEXT_PUBLIC_NAVIEO_PUBLISHABLE_KEY` env var.
`apiBaseUrl`	`string`	`https://api.navieo.io/api`	Base URL for the Navieo API. Override for local development or self-hosted deployments.

NavieoNextProvider

Same props as NavieoProvider, minus currentRoute and onNavigate (handled automatically via Next.js hooks).

Suggestion Chips

Provide suggestion chips to guide users on what to ask:

<NavieoProvider
  suggestions={[
    { label: "How do I create a project?" },
    { label: "Where are my settings?", tag: "Popular" },
    { label: "How do I invite team members?", tag: "New" },
  ]}
>
  {children}
</NavieoProvider>

Chips appear in the empty chat state. The optional tag prop adds a colored badge.

Chat Modes

The built-in chat widget includes a mode selector with two modes:

Mode	Behavior
Ask	Text Q&A about the app. Returns answers without visual tours.
Guide	Step-by-step visual walkthroughs that highlight UI elements. This is the default mode.

Users switch modes via the dropdown in the chat input area. The selected mode persists across page navigation via sessionStorage.

You can also control the mode programmatically:

const { chatMode, setChatMode } = useNavieo();

setChatMode("ask");   // Text answers only
setChatMode("guide"); // Visual walkthroughs

Using the Hook

Access Navieo state and controls from any child component:

import { useNavieo } from "@navieo/react";

function MyComponent() {
  const {
    // Chat state
    isChatOpen,
    openChat,
    closeChat,
    toggleChat,
    chatHistory,
    suggestions,

    // Chat mode
    chatMode,        // "ask" | "guide"
    setChatMode,

    // Tour state
    tourState,       // "idle" | "loading" | "active" | "error"
    startTour,       // (query: string) => Promise<void>
    steps,           // TourStep[]
    currentStepIndex,
    currentStep,
    nextStep,
    prevStep,
    endTour,
  } = useNavieo();

  return (
    <button onClick={() => startTour("How do I export data?")}>
      Show me how to export
    </button>
  );
}

For single-page apps, pass your router's push function to avoid full page reloads during tours:

// React Router
import { useNavigate } from "react-router-dom";

function App() {
  const navigate = useNavigate();
  return (
    <NavieoProvider onNavigate={(route) => navigate(route)}>
      <YourApp />
    </NavieoProvider>
  );
}

If you don't pass onNavigate, Navieo falls back to window.location.href which works but causes a full page reload.