Provider Setup

The NavieoProvider is the core of Navieo. It manages widget configuration, assistant questions, live guidance and authored-tour playback. Use the compatible published versions listed in API & Authentication.

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)
Loads app configuration and authored tours using the 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

Provider props are optional, but a valid publishable key and reachable compatible backend are still required. Next.js can supply the key through its public environment variable; other bundlers should pass it explicitly.

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; tourSlug?: string }>`	—	Suggestion chips. Provide `tourSlug` to launch a saved authored tour; otherwise the label is an assistant request.
`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.
`userId`	`string`	—	Optional opaque identifier sent for authored-tour event attribution and impression lookup. Not authentication or guidance permission; avoid sensitive personal data.
`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).

Live guidance options

These options are supported in React SDK 3.0.0. Check release compatibility before using them.

Prop	Default	Meaning
`enableDynamicNavigation`	`true`	Allow live guidance when app policy also permits it. `false` keeps informational answers.
`liveLabels`	`false`	Opt into eligible request-only labels; requires independent app consent.
`enableAuthoring`	`true`	Permit the separately loaded authoring module when a valid signed session is supplied.

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

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <NavieoNextProvider enableDynamicNavigation={false}>
      {children}
    </NavieoNextProvider>
  );
}

Omit enableDynamicNavigation to use default-on guidance in a compatible release. App permission still wins, and disabling it across server workers can take up to five minutes. This is not a security-revocation control. Read Live Guidance & Privacy before enabling live labels; guidance does not require them.

startTour(query) sends an assistant question; it does not directly play an authored tour or guarantee a navigation offer. playTour(slug) remains the authored-tour API.

Suggestion Chips

Provide suggestion chips that launch saved authored tours:

<NavieoProvider
  suggestions={[
    { label: "Create a project", tourSlug: "create-project" },
    { label: "Open settings", tag: "Popular", tourSlug: "settings-overview" },
    { label: "Invite team members", tag: "New", tourSlug: "invite-members" },
  ]}
>
  {children}
</NavieoProvider>

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

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,

    // Tour state
    tourState,       // "idle" | "loading" | "active" | "error"
    playTour,        // (slug: string) => Promise<boolean> for authored tours
    steps,           // TourStep[]
    currentStepIndex,
    currentStep,
    nextStep,
    prevStep,
    endTour,
  } = useNavieo();

  return (
    <>
      <button onClick={() => playTour("export-data")}>Play the authored export tour</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.