v2.0.0

Release Notes - v2.0.0

🎉 Better Auth UI v2.0 is here! This major release brings powerful organization management and a cleaner API. While there are breaking changes, we've made migration straightforward with clear examples below.

⚠️ Breaking Changes

Component Changes

• UserButton - No longer defaults size to "icon". You must explicitly set size="icon" if you want the icon-only variant.
• Icon Colors - noColorIcons prop has been removed. colorIcons now defaults to undefined for automatic theme-based coloring (colored when light, black & white when dark). You can set it to true or false to force color or no color icons for both themes.

API Changes

• Props Reorganization - All AuthUIProvider props are now logically grouped for better developer experience
• Uppercase Constants - All view paths and localization keys now use UPPERCASE naming
• Deprecated Props - Old prop names still work with console warnings but will be removed in a future release

✨ What's New

🏢 Full Organization Support

Build multi-tenant applications with ease! The new organization features include:

• Organization Management - Create organizations with custom branding (logos, names)
• Team Collaboration - Invite members, manage roles, and control permissions
• Smart Organization Switching - Seamless context switching between organizations
• Built-in Security - Role-based access control out of the box

// Enable organizations in your app
<AuthUIProvider
  authClient={authClient}
  organization={{
    logo: {
      upload: async (file) => {
        // Your upload logic here
        const formData = new FormData()
        formData.append("logo", file)
        const res = await fetch("/api/upload", { 
          method: "POST", 
          body: formData 
        })
        const { url } = await res.json()
        return url
      }
    },
    // Default roles: "member", "admin", "owner" 
    customRoles: ["editor", "viewer"] // Add your own custom roles
  }}
>

🎨 Better Developer Experience

• Cleaner API - Props are now logically grouped for better IntelliSense
• Improved TypeScript Support - Better type safety throughout
• Consistent Naming - All constants now use UPPERCASE for clarity

🚀 Quick Start Migration

1. Update Your View Paths

View path constants are now UPPERCASE when used in your route configuration:

// Before
import { authViewPaths } from "@daveyplate/better-auth-ui/server"

export function generateStaticParams() {
    return Object.values(authViewPaths).map((pathname) => ({ pathname }))
}

// After - same import, but the values are now UPPERCASE
import { authViewPaths } from "@daveyplate/better-auth-ui/server"

export function generateStaticParams() {
    return Object.values(authViewPaths).map((pathname) => ({ pathname }))
    // Returns: ["SIGN_IN", "SIGN_UP", "SETTINGS", ...] instead of ["signIn", "signUp", "settings", ...]
}

2. Update Your AuthUIProvider

Props are now better organized into logical groups:

// Before - flat structure
<AuthUIProvider
  authClient={authClient}
  uploadAvatar={uploadFunction}
  avatarSize={256}
  avatarExtension="webp"
  providers={["github", "google"]}
  otherProviders={["custom-oauth"]}
  signInSocial="optional"
  confirmPassword={true}
  forgotPassword={true}
  passwordValidation={validationRules}
  rememberMe={true}
  username={true}
  signUpFields={["name", "company"]}
  settingsURL="/dashboard/settings"
  settingsFields={["name", "company"]}
  deleteAccountVerification="password"
  apiKeys={true}
  noColorIcons={true}
>

// After - grouped structure
<AuthUIProvider
  authClient={authClient}
  avatar={{
    upload: uploadFunction,
    size: 256,
    extension: "webp"
  }}
  social={{
    providers: ["github", "google"],
    signIn: "optional"
  }}
  genericOAuth={{
    providers: ["custom-oauth"],
    signIn: customOAuthSignIn // optional custom function
  }}
  credentials={{
    confirmPassword: true,
    forgotPassword: true,
    passwordValidation: validationRules,
    rememberMe: true,
    username: true
  }}
  signUp={{
    fields: ["name", "company"]
  }}
  settings={{
    url: "/dashboard/settings",
    fields: ["name", "company"]
  }}
  deleteUser={{
    verification: "password"
  }}
  apiKey={true} // Note: renamed from apiKeys
  colorIcons={false} // Replaces noColorIcons
>

3. Update Code Using View Path Constants

If you're using the view path constants in your code, update to UPPERCASE:

// Before
const signInUrl = `/auth/${authViewPaths.signIn}`        // Results in "/auth/sign-in"
const settingsUrl = `/auth/${authViewPaths.settings}`    // Results in "/auth/settings"

// After
const signInUrl = `/auth/${authViewPaths.SIGN_IN}`       // Still results in "/auth/sign-in"
const settingsUrl = `/auth/${authViewPaths.SETTINGS}`    // Still results in "/auth/settings"

// Note: The actual URL paths remain kebab-case (sign-in, settings, etc.)
// Only the constant names changed to UPPERCASE

📋 Complete Migration Guide

AuthUIProvider Props Migration

Click to see all prop migrations

Old Prop	New Location	Notes
uploadAvatar	avatar.upload
avatarExtension	avatar.extension
avatarSize	avatar.size
settingsFields	settings.fields
settingsURL	settings.url
deleteAccountVerification	deleteUser.verification
providers	social.providers
otherProviders	genericOAuth.providers
signInSocial	social.signIn
confirmPassword	credentials.confirmPassword
forgotPassword	credentials.forgotPassword
passwordValidation	credentials.passwordValidation
rememberMe	credentials.rememberMe
username	credentials.username
signUpFields	signUp.fields
apiKeys	apiKey	Renamed from plural to singular
noColorIcons	-	Removed. Use colorIcons={false} instead
colorIcons	colorIcons	Now defaults to undefined (auto theme-based)
-	genericOAuth.signIn	New: Custom OAuth sign-in function
-	organization	New: Organization management features

View Paths Migration

All view path constants are now UPPERCASE:

// Old → New
viewPaths.signIn → viewPaths.SIGN_IN
viewPaths.signUp → viewPaths.SIGN_UP
viewPaths.settings → viewPaths.SETTINGS
viewPaths.forgotPassword → viewPaths.FORGOT_PASSWORD
// ... and so on

Localization Keys Migration

If you're using custom localization, update your keys to UPPERCASE:

// Before
localization={{
  email: "Email Address",
  password: "Password",
  signIn: "Sign In"
}}

// After
localization={{
  EMAIL: "Email Address",
  PASSWORD: "Password",
  SIGN_IN: "Sign In"
}}

🎯 Real-World Examples

Enable Organizations

// Basic setup (includes default roles: member, admin, owner)
<AuthUIProvider
  authClient={authClient}
  organization={true}
>

// Advanced setup with custom roles and logo upload
<AuthUIProvider
  authClient={authClient}
  organization={{
    logo: {
      upload: async (file) => {
        // Your upload logic
        const formData = new FormData()
        formData.append("logo", file)
        const res = await fetch("/api/upload-logo", { 
          method: "POST", 
          body: formData 
        })
        const { url } = await res.json()
        return url
      },
      size: 256
    },
    // Keep default roles and add custom ones
    customRoles: ["editor", "viewer", "moderator"]
  }}
>

Configure Authentication

<AuthUIProvider
  authClient={authClient}
  // Social login configuration
  social={{
    providers: ["github", "google", "discord"],
    signIn: "optional" // or "required"
  }}
  // Password requirements
  credentials={{
    passwordValidation: {
      minLength: 8,
      requireUppercase: true,
      requireNumbers: true
    },
    confirmPassword: true
  }}
  // Sign up customization
  signUp={{
    fields: ["name", "company", "role"]
  }}
>

💡 Pro Tips

1. Deprecation Warnings - The old props still work but show console warnings. Update at your own pace! They will be removed in a future update.
2. UserButton Size - Remember to explicitly set size="icon" if you were relying on the default icon-only behavior.

🔄 Component Updates

UserButton

The <UserButton> component no longer defaults to icon size:

// Before - automatically rendered as icon
<UserButton />

// After - specify size explicitly
<UserButton size="icon" />  // For icon-only
<UserButton size="sm" />    // For small button with name
<UserButton />              // Default size with name

🆘 Need Help?

• Check out our documentation

🐛 Bug Fixes & Improvements

• Fixed passkey icon (now shows fingerprint instead of key)
• Improved mobile responsive design for settings
• Better error handling throughout
• Enhanced TypeScript support with better prop grouping
• Improved theme-based icon coloring system

---

Thank you for using Better Auth UI! We're excited to see what you build with these new features. 🚀

v1.7.0

Better Auth UI v1.7.0 - API Keys Feature

We're excited to announce the release of Better Auth UI v1.7.0, which introduces a complete API key management system for your applications.

🔑 New Feature: API Keys

This release adds full API key management capabilities to Better Auth UI, allowing your users to create, view, and manage API keys for programmatic access to your services.

Key Features

• Create API Keys: Users can generate new API keys with custom names
• Expiration Settings: Set expiration periods or create non-expiring keys
• Secure Display: One-time secure display of newly created keys with copy functionality
• Key Management: View and manage existing keys from the user settings area
• Revocation: Easily revoke API keys when they're no longer needed

🚀 Getting Started with API Keys

To enable API keys in your application:

// 1. Configure your AuthUIProvider with API keys enabled
<AuthUIProvider
  authClient={authClient}
  apiKeys // Enable basic API keys
  // Or with additional configuration:
  // apiKeys={{
  //   prefix: "myapp", // Custom prefix for API keys
  //   metadata: { environment: "production" } // Add metadata to keys
  // }}
>
  {children}
</AuthUIProvider>

// 2. Manually Add the API Keys card to your settings page
import { APIKeysCard } from "@daveyplate/better-auth-ui";

function SettingsPage() {
  return (
    <div>
      <h1>Account Settings</h1>
      {/* Other setting cards */}
      <APIKeysCard />
    </div>
  );
}

## 🛠️ Implementation Details

API keys include:
- Unique ID and name
- Secure key format with visible prefix
- Optional expiration dates
- Creation and update timestamps

## 🔐 Security Best Practices

- API keys are only shown once at creation time
- Keys can be easily revoked if compromised
- Consider setting expiration periods for sensitive access

---

As always, if you encounter any issues or have feedback, please let us know by opening an issue on GitHub. We appreciate your support!

v1.6.0

Better Auth UI 1.6.0 brings Captcha support!

You can simply pass the "captcha" option to the AuthUIProvider, for example:

captcha={{
    provider: "google-recaptcha-v3-checkbox",
    siteKey: process.env.NEXT_PUBLIC_RECAPTCHA_SITE_KEY!,
    hideBadge: false
}}

v1.5.0

This update contains a huge overhaul of the forms using React Hook Form & zod:

https://ui.shadcn.com/docs/components/form

Every auth form & settings form now has client side validation as well as shadcn styled error handling. Full support for localization for all errors as well. This also includes more gracefully preserving forms (e.g., sign up) on failure.

Another fix contained in this patch is using transitions for onSessionChange callbacks, this works great with Next.js when you have to call router.refresh to clear middleware cache. You don't need to call router.refresh() on page mount any longer to beat race conditions, simply just call it onSessionChange and the logins will wait for the useTransition hook to finish before routing to the redirectTo on success. This should fix any issues with redirects that may have occurred in certain setups.

v1.4.3

Two Factor Authentication is here!

After setting it up in your auth.tsx, just pass the twoFactor prop to the AuthUIProvider to enable it in the UI:

<AuthUIProvider twoFactor={["otp", "totp"]}>

It will default to the method that is first in the array. You can use either OTP, TOTP, or both.

v1.4.0

Tons of code cleanup.

settingsUrl has been renamed to settingsURL
InstantDB support: https://better-auth-ui.com/data/instantdb

v1.3.0

Breaking Changes

• [AuthUIProvider] Rename LinkComponent prop to Link
• [AuthUIProvider] Rename defaultRedirectTo prop to redirectTo

New Features

• [AuthUIProvider] Custom OAuth providers - otherProviders prop
• [AuthUIProvider] Custom Toasts - toast prop
• [AuthUIProvider] Confirm Password - confirmPassword prop
• [UserAvatar] Fix flickering when cached (New AvatarPrimitive)

v1.2.17

Features:

• PasskeysCard
• UserButton additionalLinks prop
• Fix authClient types issue
• Support latest better-auth-tanstack package (v1.2.30)

v1.2.8

Alright I think it's time to announce better-auth-ui v1.2! It supports better-auth v1.2 out of the box and has been updated to support the latest shadcn/ui components with TailwindCSS v4.

I've also updated the package to include a lot more features including UserAvatar, UserButton, Settings Cards, and more!

You can find the WIP (mostly finished) documentation here: https://better-auth-ui.com/

Demo: https://newtech.dev/auth/sign-in

I'd love to hear any feedback you have! Feel free to drop a DM or comment here.

Note There are a lot of breaking changes from the old version of better-auth-ui, so if you are using the old version I recommend reading the entire Getting Started section (Requirements & Installation) to update to the latest version. Future versions will have minimal breaking changes.

v1.0.0

Initial release! More to come soon...

npm install @daveyplate/better-auth-ui