react

---
name: react
description: Add authdog's presentational UI (navbar, user profile, dropdown, TOTP input) to a React 18+ app with @authdog/react-elements. This is a UI-only kit; it does not provide a session, provider, or access control. Use when the user asks to add authdog UI components to a React app.
---

# authdog for React (Elements)

`@authdog/react-elements` is a presentational UI kit for React 18+: navbar, user profile, dropdown, and TOTP input. It does not provide a session, provider, sign-in flow, or access control. Pair it with [Next.js](../nextjs/SKILL.md), [Remix](../remix/SKILL.md), or your own [backend](../express/SKILL.md).

## When to use this skill

The user wants to add authdog's UI components (navbar, profile menu, TOTP prompt) to a React app. This skill is **UI only** — it does not authenticate anyone. If the user wants the full sign-in flow, point them to a framework skill (Next.js, Remix, etc.) or a backend skill.

## What you need from the user first

1. Their authdog **public key** (`pk_...`) — components like `Navbar` open hosted sign-in using `identityHost` and `environmentId`.
2. The validated identity data and navigation/logout callbacks from the host app — these components render identity and invoke callbacks only; they do not validate sessions or enforce access.

## Steps

### 1. Install

```bash
npm install @authdog/react-elements
```

Peer dependencies are `react` and `react-dom` 18 or 19.

### 2. Import the stylesheet once at your app root

```tsx
import "@authdog/react-elements/styles.css"
```

### 3. Use the components

Declare every dependency explicitly. This example receives validated identity data and navigation/logout callbacks from its host app:

```tsx
import { Navbar } from "@authdog/react-elements"

type AppNavbarProps = {
  user: unknown
  isLoading: boolean
  identityHost: string
  environmentId: string
  onNavigate: (href: string) => void
  onLogout: () => void
}

export function AppNavbar(props: AppNavbarProps) {
  return (
    <Navbar
      logoText="ACME Corp"
      items={[{ title: "Dashboard", href: "/dashboard" }]}
      user={props.user}
      isLoading={props.isLoading}
      identityHost={props.identityHost}
      environmentId={props.environmentId}
      onNavItemClick={props.onNavigate}
      onProfileSelected={() => props.onNavigate("/profile")}
      onLogout={props.onLogout}
    />
  )
}
```

### 4. Available components

- `Navbar`: app navigation with a user menu; requires `identityHost` and `environmentId`
- `UserProfile`: renders the signed-in user's profile; `loading` is required
- `UserDropdown`: the account menu on its own
- `Button`, `ClientOnly` (SSR guard), `PlaceholderAlert`
- `TOTPValidator`: `{ onValidate: (code: string) => Promise }` for MFA prompts

## Gotchas

- **No session here**: `react-elements` does not provide `useUser`/`useAuth` or any provider. Bring identity from a framework SDK or your own backend.
- **`Navbar` opens hosted sign-in when no user is supplied**: pass `identityHost` and `environmentId` from a trusted, validated public-key configuration.
- **Validate sessions and enforce access server-side**: these components render identity and invoke callbacks only.

## Next steps

- [Component reference](https://www.authdog.com/docs/components): every component and prop in depth.
- [Next.js](https://www.authdog.com/docs/frameworks/nextjs): the most common pairing for these elements.
- [Account portal](https://www.authdog.com/docs/account-portal): the zero-config hosted alternative to building your own UI.

More agent context in authdog/agent-skills

31 other files this repository gives its agents.