Better Auth UI

The essential context provider that enables better-auth-ui components and hooks throughout your application.

The <AuthUIProvider /> wraps your application with authentication context, providing essential hooks, settings, and methods required by authentication-related components and hooks throughout your app.

Installation

If you are using the manual installation method, the AuthUIProvider is included in any of the core blocks (auth, org, user-button).

pnpm dlx shadcn@latest add https://stackproviders.github.io/better-auth-ui/r/auth.json

npx shadcn@latest add https://stackproviders.github.io/better-auth-ui/r/auth.json

yarn dlx shadcn@latest add https://stackproviders.github.io/better-auth-ui/r/auth.json

bun x shadcn@latest add https://stackproviders.github.io/better-auth-ui/r/auth.json

Usage

providers.tsx

"use client";

import { AuthUIProvider } from "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>
  );
}

Reference

The following props can be passed to the <AuthUIProvider /> component:

Prop	Type	Default
`Link?`	`any`	`<a>`
`replace?`	`((href: string) => void)`	`navigate`
`onSessionChange?`	`(() => void \| Promise<void>)`	-
`navigate?`	`((href: string) => void)`	`window.location.href`
`twoFactor?`	`("otp" \| "totp")[]`	`undefined`
`social?`	`SocialOptions`	-
`persistClient?`	`boolean`	`false`
`passkey?`	`boolean`	`false`
`optimistic?`	`boolean`	`false`
`oneTap?`	`boolean`	`false`
`nameRequired?`	`boolean`	`true`
`multiSession?`	`boolean`	`false`
`emailOTP?`	`boolean`	`false`
`magicLink?`	`boolean`	`false`
`gravatar?`	`boolean \| GravatarOptions`	-
`genericOAuth?`	`GenericOAuthOptions`	-
`freshAge?`	`number`	`60 * 60 * 24`
`emailVerification?`	`boolean`	-
`changeEmail?`	`boolean`	`true`
`redirectTo?`	`string`	`"/"`
`captcha?`	`CaptchaOptions`	-
`baseURL?`	`string`	-
`basePath?`	`string`	`"/auth"`
`apiKey?`	`boolean \| { prefix?: string \| undefined; metadata?: Record<string, unknown> \| undefined; }`	-
`additionalFields?`	`AdditionalFields`	-
`signUp?`	`boolean \| SignUpOptions`	`{ fields: ["name"] }`
`credentials?`	`boolean \| CredentialsOptions`	`{ forgotPassword: true }`
`organization?`	`boolean \| OrganizationOptions`	-
`mutators?`	`Partial<AuthMutators>`	-
`localization?`	`AuthLocalization`	`authLocalization`
`toast?`	`RenderToast`	`Sonner`
`viewPaths?`	`AuthViewPaths`	`authViewPaths`
`hooks?`	`Partial<AuthHooks>`	-
`deleteUser?`	`boolean \| DeleteUserOptions`	`undefined`
`avatar?`	`boolean \| Partial<AvatarOptions>`	`undefined`
`account?`	`boolean \| Partial<AccountOptions>`	`{ fields: ["image", "name"] }`
`authClient`	`AuthClient`	`Required`
`children`	`ReactNode`	-

Example

A minimal Next.js layout file using the AuthUIProvider:

"use client";

import { AuthUIProvider } from "better-auth-ui";
import { authClient } from "@/lib/auth-client";
import { useRouter } from "next/navigation";
import Link from "next/link";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  const router = useRouter();

  return (
    <html lang="en">
      <body>
        <AuthUIProvider
          authClient={authClient}
          navigate={router.push}
          replace={router.replace}
          onSessionChange={() => router.refresh()}
          social={{
            providers: ["github", "google", "facebook", "apple"],
          }}
          multiSession
          magicLink
          passkey
          avatar={{
            upload: async (file) => {
              const formData = new FormData();
              formData.append("avatar", file);

              const res = await fetch("/api/uploadAvatar", {
                method: "POST",
                body: formData,
              });
              const { data } = await res.json();

              return data.url;
            },
            delete: async (url) => {
              await fetch("/api/deleteAvatar", {
                method: "POST",
                headers: { "Content-Type": "application/json" },
                body: JSON.stringify({ url }),
              });
            },
            // Custom Image component for rendering avatar images
            // Useful for CDN optimization (Cloudinary, Imgix, ImgProxy, etc.)
            Image: Image, // Use Next.js Image component for avatars
          }}
          captcha={{
            provider: "google-recaptcha-v3",
            siteKey: "your-site-key",
          }}
          settings={{
            url: "/dashboard/settings",
          }}
          twoFactor={["otp", "totp"]}
          Link={Link}
        >
          {children}
        </AuthUIProvider>
      </body>
    </html>
  );
}

<AuthUIProvider />

Installation

Usage

Reference

Example

On this page