React SDK Guide (@authsetu/react)

Installation

For standard React single-page applications (Vite, Create React App, React Router):

bash

bun add @authsetu/react
# or
npm install @authsetu/react

Tip

If you are building a Next.js application, install @authsetu/nextjs instead. It automatically bundles @authsetu/react and re-exports all React components, hooks, and control guards.

---

Components Overview

1. UI Components

: Pre-built login card with email/password, magic link, and social auth support.

: Customer registration card with input validation and password policy feedback.

: Dropdown button displaying avatar, user details, organization switcher trigger, and logout action.

: Complete user account settings modal/view.

: Dropdown to switch active organization context.

: Modal form to create a new multi-tenant organization.

: Restricts children based on subscription tier feature flags.

tsx

import { UserButton, OrganizationSwitcher, PlanGuard } from "@authsetu/react";

export function DashboardHeader() {
  return (
    <header className="flex items-center justify-between p-4 border-b">
      <OrganizationSwitcher />
      
      <PlanGuard feature="customDomain" fallback={<span>Upgrade to Pro for Custom Domains</span>}>
        <button>Configure Domain</button>
      </PlanGuard>

      <UserButton />
    </header>
  );
}

---

2. Control Flow Components

Control UI visibility based on authentication state, permissions, or roles:

tsx

import { SignedIn, SignedOut, Protect } from "@authsetu/react";

export function Navigation() {
  return (
    <nav>
      <SignedOut>
        <a href="/sign-in">Sign In</a>
        <a href="/sign-up">Get Started</a>
      </SignedOut>

      <SignedIn>
        <a href="/dashboard">Dashboard</a>

        <Protect permission="org:admin" fallback={<p>Admin access required</p>}>
          <a href="/settings/billing">Billing Settings</a>
        </Protect>
      </SignedIn>
    </nav>
  );
}

---

3. Custom Hooks Reference

| Hook | Returns | Description |
| :--- | :--- | :--- |
| useAuth() | { userId, sessionId, getToken, isLoaded, isSignedIn } | Core authentication state and helper methods. |
| useUser() | { user, isLoaded } | Current authenticated user object. |
| useSession() | { session, isLoaded } | Active device session details. |
| useOrganization() | { organization, membership, isLoaded } | Current active organization data. |
| usePermission(perm) | boolean | Checks if user has a specific permission string. |
| usePlanGuard(feature)| { hasAccess, isUsageLimitExceeded } | Evaluates feature access against plan limits. |

Hook Usage Example

tsx

import { useAuth, useUser, usePermission } from "@authsetu/react";

export function UserDashboard() {
  const { user, isLoaded } = useUser();
  const { getToken, logout } = useAuth();
  const canDeleteUsers = usePermission("users:delete");

  if (!isLoaded) return <div>Loading user profile...</div>;

  const handleApiCall = async () => {
    const token = await getToken();
    await fetch("/api/data", {
      headers: { Authorization: `Bearer ${token}` },
    });
  };

  return (
    <div>
      <h1>Welcome back, {user?.firstName}!</h1>
      {canDeleteUsers && <button className="btn-danger">Delete Users</button>}
      <button onClick={logout}>Sign Out</button>
    </div>
  );
}

---

4. Router Guards

Protect client routes in React Router apps using AuthGuard or ProtectedRoute:

tsx

import { ProtectedRoute } from "@authsetu/react";
import { BrowserRouter, Routes, Route } from "react-router-dom";

export function AppRoutes() {
  return (
    <BrowserRouter>
      <Routes>
        <Route path="/public" element={<PublicPage />} />
        
        <Route
          path="/dashboard"
          element={
            <ProtectedRoute redirectUrl="/sign-in">
              <DashboardPage />
            </ProtectedRoute>
          }
        />
      </Routes>
    </BrowserRouter>
  );
}