Better Auth UI: the complete Next.js + shadcn guide (2026)

If you searched for Better Auth UI, you are usually past the "which auth library?" debate. You already want Better Auth for sessions, OAuth, and plugins - and you do not want to hand-build every sign-in, sign-up, reset-password, and settings screen from scratch.

This guide covers what Better Auth UI is, how it differs from Better Auth itself, how to install and integrate it in Next.js App Router, which components and plugins matter in production, and when a starter kit is the better use of your time.

What is Better Auth UI?

Better Auth UI is a UI layer for Better Auth: drop-in React (and Solid) components for sign-in, sign-up, password recovery, account settings, user menus, email templates, and plugin-backed flows like magic links, passkeys, organizations, and API keys. It is maintained at better-auth-ui.com with source on GitHub.

The library is Better Auth native. It is not a generic auth kit bolted onto Clerk, Auth.js, or Supabase Auth. That focus is why people search "better auth ui" and "better auth shadcn": they want components that already speak Better Auth's client API.

Three UI stacks ship from the same project. Shared React data hooks live under @better-auth-ui/react (queries, mutations, ensureSession, useAuthenticate), so UI variants share one auth data layer.

Better Auth vs Better Auth UI (do not confuse them)

Search results mix these two names. Treat them as a backend + UI pair: Better Auth owns sessions and plugins; Better Auth UI owns forms, settings, and account chrome. You still configure secrets, schema, email, and OAuth yourself (or inherit them from a starter).

Better Auth alone does not give you finished screens. Better Auth UI alone does not replace a configured auth instance, database, or email provider. You need both - or a starter that already wires both.

Who should use Better Auth UI?

Use Better Auth UI when you already chose Better Auth and need production auth screens fast on shadcn or HeroUI. Skip it when auth is the product (bespoke identity UI), you are on another auth vendor, or you also need billing, orgs, admin, and mobile this month.

Prerequisites before you install Better Auth UI

Official docs assume these are already working. Without a live Better Auth server, email, and OAuth apps, polished forms still fail in production.

How to install Better Auth UI (shadcn path)

The fastest path for most Next.js teams is the registry install. Use the smaller registries for a thin first commit; use all.json when you want plugins and email templates immediately.

npx shadcn@latest add https://better-auth-ui.com/r/auth.json

npx shadcn@latest add https://better-auth-ui.com/r/auth.json
npx shadcn@latest add https://better-auth-ui.com/r/settings.json https://better-auth-ui.com/r/user-button.json

npx shadcn@latest add https://better-auth-ui.com/r/all.json

HeroUI users install packages instead of the registry - see HeroUI quick start. Always prefer the current docs over older @daveyplate/better-auth-ui READMEs when APIs diverge.

Next.js App Router setup (AuthProvider + routes)

The official Next.js integration follows one pattern: shared React Query client → AuthProvider → dynamic /auth/[path] and /settings/[path] routes → session guards. After wiring, your tree looks like this:

Step-by-step wiring

import { QueryClient } from "@tanstack/react-query";

function makeQueryClient() {
  return new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 5_000,
      },
    },
  });
}

let browserQueryClient: QueryClient | undefined;

export function getQueryClient() {
  if (typeof window === "undefined") {
    return makeQueryClient();
  }

  browserQueryClient ??= makeQueryClient();
  return browserQueryClient;
}

"use client";

import { QueryClientProvider } from "@tanstack/react-query";
import Link from "next/link";
import { useRouter } from "next/navigation";
import type { ReactNode } from "react";

import { authClient } from "@/lib/auth-client";
import { getQueryClient } from "@/lib/query-client";
import { AuthProvider } from "@/components/auth/auth-provider";
import { Toaster } from "@/components/ui/sonner";

export function Providers({ children }: { children: ReactNode }) {
  const router = useRouter();
  const queryClient = getQueryClient();

  return (
    <QueryClientProvider client={queryClient}>
      <AuthProvider
        authClient={authClient}
        redirectTo="/settings/account"
        socialProviders={["google", "github"]}
        navigate={({ to, replace }) =>
          replace ? router.replace(to) : router.push(to)
        }
        Link={Link}
      >
        {children}
        <Toaster />
      </AuthProvider>
    </QueryClientProvider>
  );
}

import { viewPaths } from "@better-auth-ui/core";
import { notFound } from "next/navigation";

import { Auth } from "@/components/auth/auth";

export default async function AuthPage({
  params,
}: {
  params: Promise<{ path: string }>;
}) {
  const { path } = await params;

  if (!Object.values(viewPaths.auth).includes(path)) {
    notFound();
  }

  return (
    <div className="my-auto flex justify-center p-4 md:p-6">
      <Auth path={path} />
    </div>
  );
}

import { viewPaths } from "@better-auth-ui/core";
import { ensureSession } from "@better-auth-ui/react/server";
import { dehydrate, HydrationBoundary } from "@tanstack/react-query";
import { headers } from "next/headers";
import { notFound, redirect } from "next/navigation";

import { Settings } from "@/components/auth/settings/settings";
import { auth } from "@/lib/auth";
import { getQueryClient } from "@/lib/query-client";

export default async function SettingsPage({
  params,
}: {
  params: Promise<{ path: string }>;
}) {
  const { path } = await params;

  if (!Object.values(viewPaths.settings).includes(path)) {
    notFound();
  }

  const queryClient = getQueryClient();
  const session = await ensureSession(queryClient, auth, {
    headers: await headers(),
  });

  if (!session) {
    redirect(
      `/auth/sign-in?redirectTo=${encodeURIComponent(`/settings/${path}`)}`,
    );
  }

  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
      <div className="mx-auto w-full max-w-3xl p-4 md:p-6">
        <Settings path={path} />
      </div>
    </HydrationBoundary>
  );
}

Protecting routes with Better Auth UI

You need two layers for production SaaS dashboards: a server check so HTML never streams to anonymous users, and a client hook so sessions that die mid-visit still redirect. Official docs recommend SSR guard + useAuthenticate together.

import { ensureSession } from "@better-auth-ui/react/server";
import { dehydrate, HydrationBoundary } from "@tanstack/react-query";
import { headers } from "next/headers";
import { redirect } from "next/navigation";

import { auth } from "@/lib/auth";
import { getQueryClient } from "@/lib/query-client";

export default async function Dashboard() {
  const queryClient = getQueryClient();
  const session = await ensureSession(queryClient, auth, {
    headers: await headers(),
  });

  if (!session) {
    redirect("/auth/sign-in?redirectTo=/dashboard");
  }

  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
      <h1>Hello, {session.user.email}</h1>
    </HydrationBoundary>
  );
}

"use client";

import { useAuth, useAuthenticate } from "@better-auth-ui/react";

export function DashboardClient() {
  const { authClient } = useAuth();
  const { data: session } = useAuthenticate(authClient);

  if (!session) {
    return null; // hook redirects; show a spinner while it settles
  }

  return <p>{session.user.email}</p>;
}

Better Auth UI components worth knowing

From the project llms.txt / docs index, the shadcn surface covers auth views, account chrome, settings, and email templates. Enable only what your Better Auth server already supports - a passkey button with no passkey plugin is a support ticket waiting to happen.

Plugins that expand the Better Auth UI surface

Better Auth UI plugins mirror Better Auth capabilities. Wire plugins on the server (Better Auth) and in AuthProvider (UI). Mismatched plugin lists are a top source of "button does nothing" bugs.

Customization: own the code, keep the behavior

Because the shadcn path copies components into your repo, customization is normal product work. Prefer provider props and plugins over forking mutation logic so upstream registry updates stay mergeable.

Better Auth UI vs DIY shadcn forms vs a SaaS starter

This is the decision most "better auth ui" searchers are actually making. Pick Better Auth UI when auth screens are the bottleneck. Pick a starter when auth is one of ten blockers. Pick DIY when auth is the product.

See TurboStarter's auth overview and user flow for password, magic link, OTP, passkeys, OAuth, and 2FA views that ship with the kit.

Production checklist for Better Auth UI

Use this before you call auth "done":

For a broader Next.js hardening pass after auth UI lands, read the Next.js security checklist.

Common Better Auth UI mistakes

1. Installing UI before Better Auth works - prove signIn.email against your API first
2. Client-only route protection - scrapers and prefetch still hit RSC payloads; guard on the server
3. Shared QueryClient on the server - session cache leaks across users under load
4. Legacy package docs on a new install - AuthUIProvider tutorials may not match current AuthProvider + registry files
5. Enabling social buttons without provider credentials - empty OAuth config fails late, in the redirect
6. Forgetting redirectTo - users bounce to / after login instead of the page they wanted
7. Treating auth UI as the whole SaaS - you still need billing webhooks, org invites, and admin tools

Related reading

Frequently asked questions

Conclusion

Better Auth UI is the missing presentation layer for Better Auth: shadcn-owned (or HeroUI/Solid) components for the auth and account flows every SaaS ships. Install the registry, wrap AuthProvider, add dynamic auth and settings routes, and protect dashboards with ensureSession plus useAuthenticate.

If your goal is only clean auth screens on an existing Next.js app, start with the official Better Auth UI docs. If your goal is a production SaaS - auth UI plus billing, organizations, admin, and a monorepo you can grow into mobile - skip wiring ten libraries and start from TurboStarter.