Better Auth UI: Plug & Play Shadcn/UI Components

3.2.27 · active · verified Wed Apr 22

better-auth-ui is a comprehensive React component library providing plug-and-play authentication UIs built on `shadcn/ui` for the `better-auth` ecosystem. Currently at version 3.2.27, it delivers a suite of pre-built, highly customizable components covering common authentication flows such as sign-in, sign-up, password recovery, user profile management, and settings. The library aims to streamline the development of secure and aesthetically pleasing authentication interfaces by leveraging `shadcn/ui` for styling, `react-hook-form` for form management, and `@tanstack/react-query` for data fetching. It ships with full TypeScript support, ensuring type safety and a robust developer experience. While a specific release cadence isn't detailed, the consistent versioning indicates active development, focusing on integration with `better-auth` to empower developers to 'Own Your Auth' with minimal setup.

Common errors

```
TypeError: Cannot read properties of undefined (reading 'register')
```
cause `react-hook-form` context is missing or a component is used outside its intended form context.

fix Ensure form components are correctly rendered within a `<form>` element managed by `react-hook-form` and that you have `react-hook-form` installed at a compatible version.
```
Error: AuthUIProvider context is missing. Please make sure to wrap your application with <AuthUIProvider>.
```
cause The `AuthUIProvider` component was not rendered in the parent tree of the `better-auth-ui` component.

fix Add `<AuthUIProvider>` to your application's root layout or entry point, ensuring it wraps all components that utilize `better-auth-ui`.
```
Module not found: Can't resolve 'better-auth-ui'
```
cause The `better-auth-ui` package is not installed or incorrectly referenced in your project.

fix Run `npm install better-auth-ui` or `pnpm add better-auth-ui` to install the package. Verify the import path is correct.
```
TS2307: Cannot find module 'better-auth-ui' or its corresponding type declarations.
```
cause TypeScript cannot find the type definitions for the `better-auth-ui` package.

fix Ensure `better-auth-ui` is installed, as it ships with its own types. Check your `tsconfig.json` for proper `moduleResolution` and `path` configurations if issues persist.

Warnings

breaking Upgrading `better-auth` or `@tanstack/react-query` to a new major version might introduce breaking changes that require corresponding updates to `better-auth-ui` or its configuration.
Fix: Always check the release notes for `better-auth-ui` and its core peer dependencies before major version upgrades. Ensure all peer dependencies are compatible versions.
gotcha Incorrect or incomplete Tailwind CSS configuration will lead to unstyled or improperly styled components, as `better-auth-ui` relies heavily on `shadcn/ui`'s utility-first styling approach.
Fix: Follow the `shadcn/ui` installation guide to properly configure `tailwind.config.js` with correct content paths, prefixes, and design tokens for your project.
gotcha Failure to wrap your application with the `AuthUIProvider` will result in components not functioning correctly or throwing errors related to missing context.
Fix: Ensure `AuthUIProvider` is placed high enough in your component tree, typically in your root layout or entry file, to provide context to all `better-auth-ui` components.
gotcha Missing or incompatible peer dependencies (e.g., `react-hook-form`, `zod`, various `@radix-ui` packages) can cause runtime errors or build failures.
Fix: Carefully review the `peerDependencies` listed in `package.json` and ensure all required packages are installed at compatible versions in your project.
breaking Version 3 significantly refactored component APIs and internal structures to better align with `better-auth` v1.5.2+ and modern React practices. Direct imports or props from v2 might no longer be valid.
Fix: Consult the official documentation (better-auth-ui.com) and migration guides (if available) for specific changes when upgrading from `better-auth-ui` v2.x to v3.x.

Install

npm install better-auth-ui npm
yarn add better-auth-ui yarn
pnpm add better-auth-ui pnpm

Imports

AuthUIProvider
wrong:
```
const { AuthUIProvider } = require('better-auth-ui');
```
correct:
```
import { AuthUIProvider } from 'better-auth-ui';
```
The primary context provider required to wrap your application for all components to function. ESM is the standard import method.
SignInCard
wrong:
```
import SignInCard from 'better-auth-ui';
```
correct:
```
import { SignInCard } from 'better-auth-ui';
```
A named export providing the complete sign-in UI component. Ensure named import for all components.
SignUpCard
```
import { SignUpCard } from 'better-auth-ui';
```
Similar to SignInCard, this is a named export for the sign-up UI component.
UserButton
```
import { UserButton } from 'better-auth-ui';
```
Provides a user dropdown/profile button, also a named export.

Quickstart

Demonstrates wrapping an application with AuthUIProvider and rendering the SignInCard component, typically in a dedicated login page.

import { AuthUIProvider, SignInCard } from "better-auth-ui";
import React from 'react';

// In your main layout file, e.g., src/app/layout.tsx (for Next.js App Router)
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <AuthUIProvider>
          {children}
        </AuthUIProvider>
      </body>
    </html>
  );
}

// In a page component, e.g., src/app/login/page.tsx
export function LoginPage() {
  return (
    <div className="flex min-h-screen items-center justify-center p-4">
      <SignInCard />
    </div>
  );
}

view raw JSON →