React Components

OviConnectProvider

The React provider that initializes the SDK and exposes session state to child hooks + components.

<OviConnectProvider> is the entry point for every React app using Oviato. It initializes the SDK with your appId, mounts the session store, and makes the useOviConnect hook work across the tree.

import { OviConnectProvider } from '@oviato/connect/client';
import '@oviato/connect/client.css';

<OviConnectProvider appId="your-app-id" theme="auto">
  <App />
</OviConnectProvider>

Place this as high in your tree as possible — above any component that calls useOviConnect() or renders <ConnectButton />. A common pattern is wrapping the whole <body> or the root <html> layout.

Where to mount it

Create a client-only Providers wrapper (required because the provider uses React context).

app/providers.tsx

'use client';

import { OviConnectProvider } from '@oviato/connect/client';
import '@oviato/connect/client.css';

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <OviConnectProvider appId="your-app-id" theme="auto">
      {children}
    </OviConnectProvider>
  );
}

app/layout.tsx

import { Providers } from './providers';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

pages/_app.tsx

import type { AppProps } from 'next/app';
import { OviConnectProvider } from '@oviato/connect/client';
import '@oviato/connect/client.css';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <OviConnectProvider appId="your-app-id" theme="auto">
      <Component {...pageProps} />
    </OviConnectProvider>
  );
}

src/main.tsx

import React from 'react';
import ReactDOM from 'react-dom/client';
import { OviConnectProvider } from '@oviato/connect/client';
import '@oviato/connect/client.css';
import App from './App';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <OviConnectProvider appId="your-app-id" theme="auto">
      <App />
    </OviConnectProvider>
  </React.StrictMode>,
);

Props

Prop	Type	Default	Notes
`appId`	`string`	—	Required. From the Developer Dashboard.
`theme`	`'light' \| 'dark' \| 'auto'`	`'auto'`	`'auto'` respects `prefers-color-scheme`.
`domain`	`string`	session-set	Override the domain the SDK registers under. Useful for custom subdomains.
`dns`	`string`	auto	Override the backend DNS. For staging or self-hosted deployments.
`type`	`'production' \| 'staging' \| 'development'`	auto	Forces a specific environment tier; normally detected from `appId`.
`accent_color`	`string`	dashboard	Hex color for UI accents. Overrides the dashboard setting.
`logo_url`	`string`	dashboard	Logo shown in the auth popup. Overrides the dashboard setting.

Do not pass network: to the provider. Earlier versions accepted a provider-level network, but that made per-action network overrides ambiguous. Specify the network on <ConnectButton>, <Connect>, and imperative calls like login, register, authenticate instead.

What happens on mount

The provider is a thin wrapper around initialize() from the core SDK. Everything useful flows through the Zustand session store — the provider just sets it up and keeps it alive for the component tree.

Client-side hydration runs → provider reads localStorage for a cached session.
initialize() is called with { appId, theme, ... } → backend app config is fetched + cached.
Session state becomes available via useOviConnect().
If there's a cached session, isLoading flips to false with session populated. Otherwise, session is null.

Dev-mode overrides

For local development against a staging backend, you can override the bridge + RPC origins via window globals:

// Before the provider mounts — e.g. in a useEffect in _app.tsx
if (process.env.NODE_ENV === 'development') {
  (window as any).__OVIATO_BRIDGE_ORIGIN__ = 'http://localhost:5173';
  (window as any).__OVIATO_RPC_ORIGIN__ = 'http://localhost:8787';
  (window as any).__OVI_FORCE_IFRAME__ = true; // popups unreliable in local dev
}

These are convenience hooks for local iteration — not a production config surface.

SSR safety

The provider is 'use client' — it never runs on the server. A server-rendered page will see session as undefined on first paint, then populate on client hydration. Use isLoading to avoid layout shift:

function MyComponent() {
  const { session, isLoading } = useOviConnect();
  if (isLoading) return <SkeletonPlaceholder />;
  return session ? <Dashboard /> : <LoginPage />;
}

Multiple providers

Don't nest. The provider uses React context + a global Zustand store. Nesting duplicates state but only the innermost wins — confusing failure modes.

Hooks — useOviConnect, useOviStore
Components — <Connect>, <ConnectButton>
Quickstart — end-to-end setup

React Components Overview

The React-only surface of @oviato/connect — provider, hooks, and drop-in UI components.

Using Hooks

React hooks for Oviato Connect - useOviConnect and useOviStore