Authdog

Frontend guide

React Components

@authdog/react-elements is a presentational UI kit: navigation, profile, dropdown, MFA-input, and utility components. It is not an auth provider, session manager, or access-control layer. Supply identity data and callbacks from your host app, and enforce permissions on a trusted server.

Prerequisites

  • React 18 or 19 and matching React DOM (^18.2.0 || ^19.0.0 peer range).
  • @authdog/react-elements (this repo's console currently depends on 0.3.0).
  • A host application that already resolves identity and owns navigation, logout, and account-management requests.
  • A trusted backend or framework server integration for authentication and authorization.

Import the stylesheet once at your application root:

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

Implementation

The verified top-level exports are Navbar, UserProfile, UserDropdown, TOTPValidator, Button, ClientOnly, and PlaceholderAlert.

Navbar accepts navigation items, branding, loading state, user data, navigation callbacks, identityHost, and environmentId, both required. When no user is supplied it can open hosted sign-in, but it doesn't establish or validate a session itself:

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

export function AppNavbar(props: {
  user: unknown
  isLoading: boolean
  identityHost: string
  environmentId: string
  onNavigate: (href: string) => void
  onLogout: () => void
}) {
  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}
      onLogout={props.onLogout}
    />
  )
}

Use dropdownMenuItems and onDropdownMenuItemClick for menu customization, onProfileSelected is deprecated. UserProfile requires loading plus optional callbacks for email verification and code confirmation, these are application-supplied operations. UserDropdown requires a trigger element and a user object. TOTPValidator accepts one required callback:

<TOTPValidator onValidate={async (code) => validateCodeOnServer(code)} />

That callback must perform real validation elsewhere, the component only collects the code. ClientOnly skips server rendering for a component; Button and PlaceholderAlert are general UI utilities.

Security considerations

  • Treat every value rendered by these components as presentation input, a displayed user or successful client callback doesn't prove a request is authorized.
  • Pass identityHost and environmentId from trusted configuration, never from arbitrary request parameters.
  • Implement logout in the host integration, a callback alone does nothing unless your app clears browser state and server cookies.
  • Perform profile mutations and TOTP validation through trusted endpoints that validate the session and apply authorization.
  • No AuthdogProvider, SignIn, or SignUp component exists in this package.

Validation checklist

  • React and React DOM satisfy package peer ranges.
  • Stylesheet is imported once.
  • Navbar receives explicit user, loading, identity-host, environment, and callback props.
  • TOTPValidator.onValidate performs server-backed validation.
  • Logout callback clears all session locations used by the host framework.
  • Server rejects unauthenticated and unauthorized requests regardless of rendered UI.

Troubleshooting

Missing styles: styles.css wasn't imported at the application root, or app CSS overrides package selectors.

Navbar opens the wrong hosted destination: inspect identityHost and environmentId, keep both aligned with the server-side session validator.

Logout changes the menu but protected API calls still work: the callback cleared only UI state, clear the framework's actual token or cookie too.

Next steps