Better Auth UI

The default authentication components provided by @daveyplate/better-auth-ui include built-in settings pages accessible under the same base path as your auth views (e.g., /auth/settings, /auth/security, etc.).

However, for advanced use cases, you may want to:

Move the built-in settings views to a different base path (using settings.basePath)
Replace the settings with a completely custom implementation (using settings.url)
Build your own settings page using individual components

Overview

You have three primary ways to customize the settings experience:

Move settings to a different path: Use settings.basePath to relocate all built-in settings views while keeping their functionality
Replace with custom settings: Use settings.url to redirect to your completely custom settings implementation
Build custom layouts: Import individual settings components to create your own layouts

Quick Comparison

Option	Use Case	Configuration	Result
`settings.basePath`	Keep built-in settings but move to different path	`settings: { basePath: "/dashboard" }`	Settings at `/dashboard/settings`, `/dashboard/security`, etc.
`settings.url`	Replace with completely custom settings	`settings: { url: "/my-settings" }`	All settings routes redirect to `/my-settings`
Individual components	Build custom layouts with specific components	Import components directly	Full control over layout and functionality

Option 1: Moving Settings to a Different Base Path

If you want to keep the built-in settings functionality but move it to a different location (e.g., from /auth/settings to /dashboard/settings), use the settings.basePath option:

app/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()}
            settings={{
                basePath: "/dashboard" // Settings views will be at /dashboard/settings, /dashboard/security, etc.
            }}
            Link={Link}
        >
            {children}
        </AuthUIProvider>
    )
}

With this configuration:

Auth views remain at: /auth/sign-in, /auth/sign-up, etc.
Settings views move to: /dashboard/settings, /dashboard/security, /dashboard/api-keys, /dashboard/organization, etc.
The <UserButton /> and <SettingsCards /> components automatically use the new base path

You can combine basePath with other settings options:

settings={{
    basePath: "/dashboard",
    fields: ["image", "name", "age"] // Specify which fields to show
}}

### Using SettingsCards with pathname

When using `settings.basePath`, you can pass the `pathname` prop to `<SettingsCards />` to automatically determine the current view:

```tsx title="app/dashboard/[...settings]/page.tsx"
import { SettingsCards } from "@daveyplate/better-auth-ui"

export default function SettingsPage({ 
    params 
}: { 
    params: { settings: string[] } 
}) {
    const pathname = `/dashboard/${params.settings?.join("/") || "settings"}`
    
    return (
        <div className="mx-auto max-w-4xl py-12 px-4">
            <SettingsCards pathname={pathname} />
        </div>
    )
}

Option 2: Completely Custom Settings Page

To replace the built-in settings with your own custom implementation, use settings.url:

app/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()}
            settings={{
                url: "/my-custom-settings" // Redirects to your custom settings page
            }}
            Link={Link}
        >
            {children}
        </AuthUIProvider>
    )
}

Important: When settings.url is set, all built-in settings routes will redirect to your custom URL. You're responsible for implementing the entire settings functionality.

Option 3: Building Custom Settings Layouts

For maximum control, you can build your own settings page layouts using individual components.

Using Individual Settings Components

The easiest way to get started is using the <SettingsCards /> component, which automatically handles displaying all enabled settings. This includes avatar, email, username, password, linked social providers, session management, delete account, and custom additional fields you've provided.

app/dashboard/settings/page.tsx

import { SettingsCards } from "@daveyplate/better-auth-ui"

export default function UserSettingsPage() {
    return (
        <div className="mx-auto max-w-xl py-12 px-4">
            <SettingsCards />
        </div>
    )
}

You can customize the appearance using TailwindCSS classes through classNames props as documented in SettingsCards documentation:

<SettingsCards 
    className="mx-auto max-w-xl"
    classNames={{
        card: {
            base: "border-primary/50",
            header: "bg-primary/10",
            content: "bg-background",
            footer: "bg-primary/10",
            button: "bg-primary hover:bg-primary/80",
            input: "bg-transparent placeholder-muted-foreground/50"
        }
    }}
/>

Individually Using Settings Components

For finer-grained control, selectively import the components you want:

Component	Description
`<UpdateAvatarCard />`	User avatar management
`<UpdateNameCard />`	Update user's name
`<UpdateUsernameCard />`	Manage username (if applicable/username set via plugin)
`<ChangeEmailCard />`	Changing the user's email address
`<ChangePasswordCard />`	Allow user to securely update password
`<ProvidersCard />`	Linking/Unlinking social provider accounts
`<SessionsCard />`	Active session management
`<DeleteAccountCard />`	Deleting the user account securely
`<UpdateFieldCard />`	Add or update additional custom user fields

Here's a complete example demonstrating an individually composed user settings page:

app/dashboard/settings/page.tsx

import {
    UpdateAvatarCard,
    UpdateNameCard,
    UpdateUsernameCard,
    ChangeEmailCard,
    ChangePasswordCard,
    ProvidersCard,
    SessionsCard,
    DeleteAccountCard,
    UpdateFieldCard
} from "@daveyplate/better-auth-ui"

export default function CustomSettingsPage() {
    return (
        <div className="flex flex-col gap-6 max-w-xl mx-auto py-12 px-4">
            <UpdateAvatarCard />

            <UpdateNameCard />

            <UpdateUsernameCard />

            <ChangeEmailCard />

            <ChangePasswordCard />

            <ProvidersCard />

            <SessionsCard />

            <DeleteAccountCard />

            <UpdateFieldCard
                field="age"
                label="Age"
                description="Update your age"
                placeholder="Enter your current age"
                type="number"
            />
        </div>
    )
}

This example assumes additionalFields are configured via your <AuthUIProvider>:

app/providers.tsx

<AuthUIProvider
    authClient={authClient}
    additionalFields={{
        age: {
            label: "Age",
            placeholder: "Your age",
            description: "Enter your age",
            required: false,
            type: "number"
        }
    }}
    settings={{
        fields: ["age"],
        url: "/dashboard/settings"
    }}
>
    {children}
</AuthUIProvider>

Handling Authentication for Settings Page

It's essential that your custom settings page is protected and accessible only by authenticated users. There's a built-in helper useAuthenticate to ensure your settings pages are secured:

Example:

app/dashboard/settings/page.tsx

import {
    RedirectToSignIn,
    SignedIn,
    SettingsCards
} from "@daveyplate/better-auth-ui"

export default function CustomSettingsPage() {
    return (
        <>
            <RedirectToSignIn />
            
            <SignedIn>
                <SettingsCards />
            </SignedIn>
        </>
    )
}

Custom Settings

On this page