Authdog
Log In

Frontend guide

React Components

@authdog/react-elements draws the navbar, the profile, the menu, and the MFA code box.

It does not sign anyone in, hold a session, or decide access. You pass it the user and the callbacks. Your server decides whether the request is allowed.

Prerequisites

  • React 18 or 19, and a matching React DOM. The peer range is ^18.2.0 || ^19.0.0.
  • @authdog/react-elements. The console in this repo currently depends on 0.3.0.
  • A host app that already knows who the user is, and that owns navigation, logout, and account changes.
  • A backend, or your framework's server helpers, that authenticates and authorizes. These components will not do that for you.

Import the stylesheet once, at the application root:

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

If the navbar looks unstyled, this import is the first thing to check. Importing it again in a child route usually fights the first copy.

Implementation

The exports you can rely on are Navbar, UserProfile, UserDropdown, TOTPValidator, Button, ClientOnly, and PlaceholderAlert.

Navbar needs your nav items, branding, loading state, user, and navigation callbacks. identityHost and environmentId are required. Pass both from configuration you trust, the same values your server uses to validate the session. If you omit the user, the navbar can open hosted sign-in. That is a link. It does not create a session and it does not check one.

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}
    />
  )
}

Customize the menu with dropdownMenuItems and onDropdownMenuItemClick. onProfileSelected is deprecated. Leave it out of new code.

UserProfile needs loading, plus whatever callbacks you want for email verification and code confirmation. Those callbacks have to call your API. The component will not.

UserDropdown needs a trigger element and a user object. It renders a menu. It does not know whether that user is still signed in.

TOTPValidator takes one callback. The callback is the product. The component only collects six digits:

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

validateCodeOnServer has to check the code on a server that already knows the session. Returning true from the browser because the digits look numeric is not validation.

ClientOnly skips server rendering for a child that cannot run there. Button and PlaceholderAlert are ordinary UI. None of the three authenticate anyone.

Security considerations

  • Everything these components render is display data. A name on screen, or a callback that resolved, does not authorize the next request.
  • Take identityHost and environmentId from trusted configuration. Do not read them off an arbitrary query parameter and pass them through.
  • onLogout does nothing until your app clears the cookie or token your server actually checks. Clearing React state only changes the menu.
  • Profile edits and TOTP checks go to endpoints that validate the session and apply authorization.
  • There is no AuthdogProvider, SignIn, or SignUp in this package. If you need a session, use your framework integration, not another component from this kit.

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

The layout has no styles. styles.css is missing at the root, or your CSS overrides the package selectors. Import it once, next to the rest of your global CSS, and reload.

Sign-in opens the wrong host. identityHost or environmentId does not match the server that validates the session. Pass the same pair the server uses. A navbar pointed at staging will happily start a staging login inside a production app.

Logout changes the menu and the API still works. The callback cleared UI state and left the cookie. Clear the cookie or token your framework's server helper reads, then call the API again. You want a 401.

Next steps