Authdog
Frontend guide

React Components

@authdog/react-elements is a presentational UI kit for React applications. It provides navigation, profile, dropdown, MFA-input, and utility components. It does not provide an authentication provider, session management, a sign-in flow, or access control. Supply identity data and callbacks from your host application, then validate sessions and enforce permissions on a trusted server.

Prerequisites

  • React 18 or 19 and matching React DOM. Package metadata declares ^18.2.0 || ^19.0.0 peer ranges.
  • @authdog/react-elements; this repository’s console currently depends on version 0.3.0.
  • A host application that already resolves identity and owns navigation, logout, and any account-management requests.
  • A trusted backend or framework server integration for authentication and authorization.

Import the package stylesheet once at your application root:

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

The package also exports global.css, but application code should choose one deliberate styling integration and test it against existing global styles.

Implementation

The verified top-level exports are:

  • Navbar
  • UserProfile
  • UserDropdown
  • TOTPValidator
  • Button
  • ClientOnly
  • PlaceholderAlert

Navbar accepts navigation items, branding, loading state, user data, navigation callbacks, dropdown configuration, logout handling, identityHost, and environmentId. Both identity location values are required by its current type definition. When no user is supplied, the component can use those values to open hosted sign-in, but the component itself does not establish or validate a session.

Keep data and behavior explicit:

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}
      onLogout={props.onLogout}
    />
  )
}

For new menu customization, use dropdownMenuItems and onDropdownMenuItemClick. The current type declaration marks onProfileSelected as deprecated.

UserProfile requires loading and accepts user data plus optional callbacks for requesting email verification, verifying an email code, and adding an email. These callbacks are application-supplied operations; the component renders interaction and reports results.

UserDropdown requires a trigger element and user object. It can invoke account-management and sign-out callbacks or render additional links. TOTPValidator accepts exactly one required operation:

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

That callback must perform real validation elsewhere. The component only collects the code and invokes the callback.

Use ClientOnly when a component must avoid server rendering. Button and PlaceholderAlert are general UI utilities rather than authentication boundaries.

Security considerations

Treat every value rendered by these components as presentation input. A displayed user, hidden menu item, disabled navigation link, or successful client callback does not prove a request is authorized.

Pass identityHost and environmentId from trusted configuration derived from the intended Authdog environment. Do not let arbitrary request parameters choose the identity destination.

Implement logout in the host integration. A callback named onLogout or onSignout does nothing unless your application clears its browser state and, where applicable, server cookies. Follow the selected framework SDK’s documented logout behavior.

Perform profile mutations, email verification, TOTP validation, and protected navigation through trusted endpoints. Those endpoints must validate the session on every protected request and apply authorization after authentication.

Do not invent or mount an AuthdogProvider from @authdog/react-elements; no provider is exported. Do not claim SignIn or SignUp components exist in this package; they are not among its verified exports.

Validation checklist

  • React and React DOM satisfy package peer ranges.
  • Stylesheet is imported once.
  • No provider or session behavior is expected from @authdog/react-elements.
  • Navbar receives explicit user, loading, identity-host, environment, and callback props.
  • Deprecated onProfileSelected is avoided in new code.
  • UserProfile mutation callbacks call trusted endpoints.
  • 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.
  • Component states work for loading, anonymous, authenticated, and error cases.

Troubleshooting

Missing styles usually means styles.css was not imported at the application root or application CSS overrides package selectors.

If Navbar opens the wrong hosted destination, inspect identityHost and environmentId. Keep both aligned with the environment used by the server-side session validator.

If user data never appears, debug the host framework or backend resolver. React Elements does not fetch or validate a session.

If logout changes the menu but protected API calls still work, the callback cleared only UI state. Clear the framework’s actual token or cookie and keep server validation enabled.

Next steps