better-auth-ui

name: better-auth-ui description: >- Pre-built shadcn/ui authentication components for Better Auth. Use when implementing auth pages (sign in, sign up, forgot password, magic link), user buttons, account settings, organization management, or API key management with Better Auth. Trigger on "auth UI," "auth components," "sign in page," "sign up page," "user button," "settings page," "auth card," "AuthUIProvider," "better-auth-ui," "shadcn auth," "auth view," "organization switcher," "account settings," or "auth form." Package: @daveyplate/better-auth-ui. For backend auth config, see better-auth-complete. For testing auth UI, see dogfood-complete.

Better Auth UI

Pre-built shadcn/ui styled auth components for Next.js and React. Package: @daveyplate/better-auth-ui.

Always consult better-auth-ui.com for latest API and examples.

Quick Start

npm install @daveyplate/better-auth-ui

// providers.tsx
"use client"
import { AuthUIProvider } from "@daveyplate/better-auth-ui"
import { authClient } from "@/lib/auth-client"
import { useRouter } from "next/navigation"
import Link from "next/link"

export function Providers({ children }: { children: React.ReactNode }) {
  const router = useRouter()
  return (
    <AuthUIProvider
      authClient={authClient}
      navigate={router.push}
      replace={router.replace}
      onSessionChange={() => router.refresh()}
      Link={Link}
    >
      {children}
    </AuthUIProvider>
  )
}

// app/auth/[...pathname]/page.tsx
import { AuthView } from "@daveyplate/better-auth-ui"

export default async function AuthPage({ params }: { params: Promise<{ pathname: string }> }) {
  const { pathname } = await params
  return (
    <div className="flex grow items-center justify-center">
      <AuthView pathname={pathname} />
    </div>
  )
}

That gives you /auth/sign-in, /auth/sign-up, /auth/forgot-password, /auth/reset-password out of the box.

Activity-Based Reference Guide

Component Quick Reference

Auth Views (Pages)

User Controls

Account Settings

Individual Settings Cards

Conditional Rendering

AuthUIProvider Configuration

<AuthUIProvider
  authClient={authClient}           // Required: Better Auth client instance
  navigate={router.push}            // Required: navigation function
  replace={router.replace}          // Required: replace navigation
  onSessionChange={() => router.refresh()} // Required: session change handler
  Link={Link}                       // Required: link component

  // Auth behavior
  socialLayout="horizontal"         // "horizontal" | "vertical" | "auto"
  socialProviders={["google", "github"]} // Show specific providers
  enablePasskey={true}              // Enable passkey/WebAuthn
  magicLink={true}                  // Enable magic link sign-in
  emailOTP={true}                   // Enable email OTP sign-in
  phoneNumber={true}                // Enable phone number sign-in

  // View customization
  viewPaths={{ SIGN_IN: "login", SIGN_UP: "register" }}
  basePath="/auth"                  // Base path for auth views (default: "/auth")

  // Account settings
  account={{
    basePath: "/account",           // Base path for account views
    fields: ["image", "name"],      // Fields to show in settings
    viewPaths: { SETTINGS: "profile" }
  }}
  settings={{ fields: ["company", "age"] }}  // Fields in settings view
  signUp={{ fields: ["company"] }}          // Fields in sign-up form

  // Additional fields
  additionalFields={{
    company: { label: "Company", type: "string", required: true },
    age: { label: "Age", type: "number", required: false }
  }}

  // Organization
  organization={{
    logo: { upload: async (file) => url, size: 256, extension: "png" },
    customRoles: [{ role: "developer", label: "Developer" }]
  }}

  // API Keys
  apiKey={true}                     // or { prefix: "app_", metadata: {...} }

  // Localization
  localization={{ SIGN_IN: "Log In", SIGN_UP: "Create Account" }}
  localizeErrors={false}            // Use backend error messages directly

  // Styling
  classNames={{ card: { base: "border-primary/50" } }}

  // Callbacks
  onSignIn={() => console.log("signed in")}
  onSignOut={() => console.log("signed out")}
>
  {children}
</AuthUIProvider>

Plugin Compatibility

Testing Auth UI

Use dogfood-complete to explore and test auth UI components:

# Explore sign-in page
agent-browser --session test open http://localhost:3000/auth/sign-in
agent-browser --session test screenshot --annotate test-output/sign-in.png
agent-browser --session test snapshot -i

# Test sign-up flow
agent-browser --session test open http://localhost:3000/auth/sign-up
agent-browser --session test fill @e1 "Test User"
agent-browser --session test fill @e2 "test@example.com"
agent-browser --session test fill @e3 "password123"
agent-browser --session test click @e4  # Submit
agent-browser --session test wait --load networkidle

See testing-auth-ui.md for complete patterns.

Related Skills

• better-auth-complete — Backend auth configuration
• better-auth-test-utils — Test factories, getCookies, OTP capture
• dogfood-complete — QA + test generation pipeline
• playwright-best-practices — E2E test structure