BETTER-AUTH. UI
Advanced

Custom Account Settings

The @daveyplate/better-auth-ui library provides built-in account settings views accessible through the account configuration. By default, these views are located at /account/settings, /account/security, /account/api-keys, and /account/organizations.

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

  1. Move the built-in account views to a different base path (using account.basePath)
  2. Build your own account page layout using <AccountView /> component
  3. Build completely custom settings using individual components

Overview

You have three primary ways to customize the account settings experience:

  1. Move account views to a different path: Use account.basePath to relocate all built-in account views while keeping their functionality
  2. Use AccountView component: Use <AccountView /> to render the full account management UI with navigation
  3. Build custom layouts: Import individual settings components (AccountSettingsCards, SecuritySettingsCards, etc.) to create your own layouts

Quick Comparison

OptionUse CaseConfigurationResult
account.basePathKeep built-in account views but move to different pathaccount: { basePath: "/dashboard" }Account views at /dashboard/settings, /dashboard/security, etc.
<AccountView />Use the full account UI with navigationImport and use componentRenders complete account management with sidebar navigation
Individual componentsBuild custom layouts with specific componentsImport components directlyFull control over layout and functionality

Option 1: Moving Account Views to a Different Base Path

If you want to keep the built-in account functionality but move it to a different location (e.g., from /account/settings to /dashboard/settings), use the account.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()}
            account={{
                basePath: "/dashboard" // Account 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.
  • Account views move to: /dashboard/settings, /dashboard/security, /dashboard/api-keys, /dashboard/organizations
  • The <UserButton /> component automatically uses the new base path for the settings link

You can combine basePath with other account options:

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

Using AccountView with pathname

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

app/dashboard/[...account]/page.tsx
import { AccountView } from "@daveyplate/better-auth-ui"

export default function AccountPage({
    params
}: {
    params: { account: string[] }
}) {
    const pathname = `/dashboard/${params.account?.join("/") || "settings"}`

    return (
        <div className="mx-auto max-w-4xl py-12 px-4">
            <AccountView pathname={pathname} />
        </div>
    )
}

Option 2: Using the AccountView Component

The <AccountView /> component provides the complete account management UI with sidebar navigation. You can use it on any custom route:

app/dashboard/account/page.tsx
import { AccountView } from "@daveyplate/better-auth-ui"

export default function CustomAccountPage() {
    return (
        <div className="container mx-auto py-12 px-4">
            <AccountView />
        </div>
    )
}

The <AccountView /> component automatically:

  • Renders a sidebar navigation for switching between Settings, Security, API Keys, and Organizations
  • Displays the appropriate content based on the current view
  • Handles responsive layouts (drawer menu on mobile, sidebar on desktop)
  • Protects the page (redirects to sign-in if not authenticated)

Option 3: Building Custom Settings Layouts

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

Using Settings Card Components

You can use the pre-built card components to compose your own settings layouts:

  • <AccountSettingsCards /> - Displays all account-related settings (avatar, name, username, email, additional fields)
  • <SecuritySettingsCards /> - Displays security settings (password, sessions, two-factor, passkeys, delete account)
app/dashboard/settings/page.tsx
import { AccountSettingsCards, SecuritySettingsCards } from "@daveyplate/better-auth-ui"

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

You can customize the appearance using TailwindCSS classes through classNames props:

<AccountSettingsCards
    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:

ComponentDescription
<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"
        }
    }}
    account={{
        fields: ["image", "name", "age"] // Include custom fields in account settings
    }}
>
    {children}
</AuthUIProvider>

Handling Authentication for Account Pages

It's essential that your custom account/settings pages are protected and accessible only by authenticated users. You can use the <RedirectToSignIn /> and <SignedIn> components to ensure your pages are secured:

Example:

app/dashboard/settings/page.tsx
import {
    RedirectToSignIn,
    SignedIn,
    AccountSettingsCards
} from "@daveyplate/better-auth-ui"

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

            <SignedIn>
                <div className="container mx-auto py-12 px-4">
                    <AccountSettingsCards />
                </div>
            </SignedIn>
        </>
    )
}

Note: The <AccountView /> component already includes authentication protection, so you don't need to add <RedirectToSignIn /> when using it.

Custom Auth Paths

Previous Page

Additional Fields

Next Page