@better-auth-ui/heroui 1.6.0

package/src/components/settings/security/linked-accounts.tsx

@@ -0,0 +1,98 @@
+import { useAuth, useListAccounts } from "@better-auth-ui/react"
+import { Card, type CardProps, cn, Skeleton, toast } from "@heroui/react"
+import { LinkedAccount } from "./linked-account"
+
+export type LinkedAccountsProps = {
+  className?: string
+  variant?: CardProps["variant"]
+}
+
+/**
+ * Render a card showing linked social accounts and available social providers to link.
+ *
+ * Linked accounts (excluding the "credential" provider) are shown with an unlink control;
+ * available providers are shown with a link control. Button states and labels reflect
+ * ongoing link/unlink activity and use localization for provider-specific text.
+ *
+ * @returns A JSX element containing the linked accounts card
+ */
+export function LinkedAccounts({
+  className,
+  variant,
+  ...props
+}: LinkedAccountsProps & CardProps) {
+  const { localization, socialProviders } = useAuth()
+
+  const { data: accounts, isPending } = useListAccounts({
+    throwOnError: (error) => {
+      if (error.error) toast.danger(error.error.message)
+      return false
+    }
+  })
+
+  const linkedAccounts = accounts?.filter(
+    (account) => account.providerId !== "credential"
+  )
+
+  const allRows = [
+    ...(linkedAccounts?.map((account) => ({
+      key: account.id,
+      account,
+      provider: account.providerId
+    })) ?? []),
+    ...(socialProviders?.map((provider) => ({
+      key: provider,
+      account: undefined,
+      provider
+    })) ?? [])
+  ]
+
+  return (
+    <div>
+      <h2 className={cn("text-sm font-semibold mb-3")}>
+        {localization.settings.linkedAccounts}
+      </h2>
+
+      <Card className={cn(className)} variant={variant} {...props}>
+        <Card.Content className="gap-0">
+          {isPending
+            ? socialProviders?.map((provider, index) => (
+                <div key={provider}>
+                  {index > 0 && (
+                    <div className="border-b border-dashed -mx-4 md:-mx-6 my-4" />
+                  )}
+                  <AccountRowSkeleton />
+                </div>
+              ))
+            : allRows.map((row, index) => (
+                <div key={row.key}>
+                  {index > 0 && (
+                    <div className="border-b border-dashed -mx-4 md:-mx-6 my-4" />
+                  )}
+
+                  <LinkedAccount
+                    account={row.account}
+                    provider={row.provider}
+                  />
+                </div>
+              ))}
+        </Card.Content>
+      </Card>
+    </div>
+  )
+}
+
+function AccountRowSkeleton() {
+  return (
+    <div className="flex items-center justify-between">
+      <div className="flex items-center gap-3">
+        <Skeleton className="size-10 rounded-xl" />
+
+        <div className="flex flex-col gap-1">
+          <Skeleton className="h-4 w-20 rounded-lg" />
+          <Skeleton className="h-3 w-32 rounded-lg" />
+        </div>
+      </div>
+    </div>
+  )
+}

package/src/components/settings/security/security-settings.tsx

@@ -0,0 +1,43 @@
+import { useAuth } from "@better-auth-ui/react"
+import { type CardProps, cn } from "@heroui/react"
+import type { ComponentProps } from "react"
+
+import { ActiveSessions } from "./active-sessions"
+import { ChangePassword } from "./change-password"
+import { DangerZone } from "./danger-zone"
+import { LinkedAccounts } from "./linked-accounts"
+
+export type SecuritySettingsProps = {
+  className?: string
+  variant?: CardProps["variant"]
+}
+
+/**
+ * Renders the security settings layout including password management, linked accounts, and active sessions.
+ *
+ * ChangePassword is rendered when password authentication is enabled; LinkedAccounts is rendered when social providers are present.
+ * DangerZone is rendered when `deleteUser.enabled` is true in auth config.
+ *
+ * @param className - Optional additional CSS class names for the outer container.
+ * @param variant - Card variant forwarded to each security settings card.
+ * @returns The security settings container as a JSX element.
+ */
+export function SecuritySettings({
+  className,
+  variant,
+  ...props
+}: SecuritySettingsProps & ComponentProps<"div">) {
+  const { deleteUser, emailAndPassword, socialProviders } = useAuth()
+
+  return (
+    <div
+      className={cn("flex w-full flex-col gap-4 md:gap-6", className)}
+      {...props}
+    >
+      {emailAndPassword?.enabled && <ChangePassword variant={variant} />}
+      {!!socialProviders?.length && <LinkedAccounts variant={variant} />}
+      <ActiveSessions variant={variant} />
+      {deleteUser?.enabled && <DangerZone variant={variant} />}
+    </div>
+  )
+}

package/src/components/settings/settings.tsx

@@ -0,0 +1,96 @@
+import { useAuth, useAuthenticate } from "@better-auth-ui/react"
+import type { SettingsView } from "@better-auth-ui/react/core"
+import { type CardProps, cn, Tabs } from "@heroui/react"
+import { type ComponentProps, useMemo } from "react"
+
+import { AccountSettings } from "./account/account-settings"
+import { SecuritySettings } from "./security/security-settings"
+
+export type SettingsProps = {
+  className?: string
+  hideNav?: boolean
+  path?: string
+  variant?: CardProps["variant"]
+  /** @remarks `SettingsView` */
+  view?: SettingsView
+}
+
+/**
+ * Renders the settings UI and activates the appropriate settings view based on `view` or `path`.
+ *
+ * @param className - Additional CSS class names applied to the root container
+ * @param path - Route path used to resolve which settings view to activate when `view` is not provided
+ * @param view - Explicit settings view to activate, e.g. `"account"` or `"security"`
+ * @param hideNav - When `true`, hide the navigation tabs
+ * @param variant - Card variant forwarded to each settings section card
+ * @returns A DOM tree containing the responsive settings tabs and the currently selected settings panel
+ *
+ * @throws Error if neither `view` nor `path` is provided
+ */
+export function Settings({
+  className,
+  hideNav,
+  path,
+  variant,
+  view,
+  ...props
+}: SettingsProps & ComponentProps<"div">) {
+  const { basePaths, localization, viewPaths } = useAuth()
+  useAuthenticate()
+
+  if (!view && !path) {
+    throw new Error("[Better Auth UI] Either `view` or `path` must be provided")
+  }
+
+  const settingsPathViews = useMemo(
+    () =>
+      Object.fromEntries(
+        Object.entries(viewPaths.settings).map(([k, v]) => [v, k])
+      ) as Record<string, SettingsView>,
+    [viewPaths.settings]
+  )
+
+  const currentView = view || (path ? settingsPathViews[path] : undefined)
+
+  return (
+    <Tabs
+      className={cn(className)}
+      orientation="horizontal"
+      selectedKey={currentView}
+      {...props}
+    >
+      <Tabs.ListContainer>
+        <Tabs.List
+          aria-label={localization.settings.settings}
+          className="overflow-auto w-fit"
+        >
+          <Tabs.Tab
+            id="account"
+            href={`${basePaths.settings}/${viewPaths.settings.account}`}
+          >
+            {localization.settings.account}
+
+            <Tabs.Indicator />
+          </Tabs.Tab>
+
+          <Tabs.Tab
+            id="security"
+            href={`${basePaths.settings}/${viewPaths.settings.security}`}
+          >
+            {localization.settings.security}
+
+            <Tabs.Indicator />
+          </Tabs.Tab>
+        </Tabs.List>
+      </Tabs.ListContainer>
+
+      <Tabs.Panel id="account" className="px-0">
+        <AccountSettings variant={variant} />
+      </Tabs.Panel>
+
+      <Tabs.Panel id="security" className="px-0">
+        <SecuritySettings variant={variant} />
+      </Tabs.Panel>
+    </Tabs>
+  )
+}

package/src/components/user/switch-account-item.tsx

@@ -0,0 +1,39 @@
+import { useSetActiveSession } from "@better-auth-ui/react"
+import { Dropdown, Spinner, toast } from "@heroui/react"
+import type { Session, User } from "better-auth"
+import { UserView } from "./user-view"
+
+type DeviceSession = {
+  session: Session
+  user: User
+}
+
+export type SwitchAccountItemProps = {
+  deviceSession: DeviceSession
+}
+
+/**
+ * Render a dropdown item for switching to a different authenticated session.
+ *
+ * @param deviceSession - The device session to display and switch to when pressed
+ * @returns The switch account dropdown item as a JSX element
+ */
+export function SwitchAccountItem({ deviceSession }: SwitchAccountItemProps) {
+  const { mutate: setActiveSession, isPending } = useSetActiveSession({
+    onError: (error) => toast.danger(error.error?.message || error.message)
+  })
+
+  return (
+    <Dropdown.Item
+      className="px-2"
+      isDisabled={isPending}
+      onPress={() =>
+        setActiveSession({ sessionToken: deviceSession.session.token })
+      }
+    >
+      <UserView user={deviceSession.user} />
+
+      {isPending && <Spinner color="current" size="sm" className="ml-auto" />}
+    </Dropdown.Item>
+  )
+}

package/src/components/user/switch-account-menu.tsx

@@ -0,0 +1,64 @@
+import {
+  useAuth,
+  useListDeviceSessions,
+  useSession
+} from "@better-auth-ui/react"
+import { Check, CirclePlus } from "@gravity-ui/icons"
+import { Dropdown, Label, Separator, toast } from "@heroui/react"
+
+import { SwitchAccountItem } from "./switch-account-item"
+import { UserView } from "./user-view"
+
+/**
+ * Render the menu content for switching between multiple authenticated sessions.
+ *
+ * Shows the current session with a checkmark, lists other device sessions that can be activated,
+ * and provides an option to add a new account. This component should be rendered inside a
+ * Dropdown.SubmenuTrigger to defer the useListDeviceSessions query until the submenu is opened.
+ *
+ * @returns The switch account menu content as a JSX element
+ */
+export function SwitchAccountMenu() {
+  const { basePaths, viewPaths, localization } = useAuth()
+  const { data: session } = useSession()
+  const { data: deviceSessions, isPending } = useListDeviceSessions({
+    throwOnError: (error) => {
+      if (error.error) toast.danger(error.error.message)
+      return false
+    }
+  })
+
+  return (
+    <Dropdown.Popover className="min-w-40 md:min-w-56 max-w-[48svw]">
+      <Dropdown.Menu>
+        <Dropdown.Item className="px-2">
+          <UserView isPending={isPending} />
+
+          {!isPending && <Check className="ml-auto" />}
+        </Dropdown.Item>
+
+        {deviceSessions
+          ?.filter(
+            (deviceSession) => deviceSession.session.id !== session?.session?.id
+          )
+          .map((deviceSession) => (
+            <SwitchAccountItem
+              key={deviceSession.session.id}
+              deviceSession={deviceSession}
+            />
+          ))}
+
+        <Separator />
+
+        <Dropdown.Item
+          textValue={localization.auth.addAccount}
+          href={`${basePaths.auth}/${viewPaths.auth.signIn}`}
+        >
+          <CirclePlus className="text-muted" />
+
+          <Label>{localization.auth.addAccount}</Label>
+        </Dropdown.Item>
+      </Dropdown.Menu>
+    </Dropdown.Popover>
+  )
+}

package/src/components/user/user-avatar.tsx

@@ -0,0 +1,88 @@
+import { useSession } from "@better-auth-ui/react"
+import { Person } from "@gravity-ui/icons"
+import { Avatar, type AvatarProps, cn, Skeleton } from "@heroui/react"
+import type { User } from "better-auth"
+import type { ReactNode } from "react"
+
+export type UserAvatarProps = {
+  className?: string
+  fallback?: ReactNode
+  isPending?: boolean
+  /** @remarks `User` */
+  user?: User & { username?: string | null; displayUsername?: string | null }
+  size?: AvatarProps["size"]
+}
+
+/**
+ * Render a user avatar that shows the user's image, initials, or a custom fallback; displays a circular skeleton while the session (or explicit pending flag) is pending.
+ *
+ * @param className - Additional CSS classes applied to the outer avatar container
+ * @param fallback - Custom fallback content to render when no image or initials are available
+ * @param isPending - When true, force rendering of the loading skeleton (unless an explicit `user` prop is provided)
+ * @param user - Optional user object to display; when omitted the current session user is used if available
+ * @param size - Visual size of the avatar; one of `"sm"`, `"md"`, or `"lg"` (default: `"sm"`)
+ * @returns A React element that displays the user's avatar image, initials, or the provided fallback; renders a circular skeleton while loading
+ */
+export function UserAvatar({
+  className,
+  fallback,
+  isPending,
+  user,
+  size = "sm",
+  style,
+  ...props
+}: UserAvatarProps & AvatarProps) {
+  const { data: session, isPending: sessionPending } = useSession({
+    enabled: !user && !isPending
+  })
+
+  if ((isPending || sessionPending) && !user) {
+    return (
+      <Skeleton
+        className={cn(
+          "rounded-full",
+          size === "sm" ? "size-8" : size === "md" ? "size-10" : "size-12",
+          className
+        )}
+        style={style}
+      />
+    )
+  }
+
+  const resolvedUser = user ?? session?.user
+
+  const initials = (
+    resolvedUser?.username ||
+    resolvedUser?.name ||
+    resolvedUser?.email
+  )
+    ?.slice(0, 2)
+    .toUpperCase()
+
+  return (
+    <Avatar
+      size={size}
+      className={cn("rounded-full", className)}
+      style={style}
+      {...props}
+    >
+      <Avatar.Image
+        alt={
+          resolvedUser?.displayUsername ||
+          resolvedUser?.name ||
+          resolvedUser?.email
+        }
+        src={resolvedUser?.image ?? undefined}
+      />
+
+      <Avatar.Fallback
+        className={cn(
+          size === "lg" ? "text-xl" : size === "md" ? "text-base" : "text-sm"
+        )}
+        delayMs={resolvedUser?.image ? 600 : undefined}
+      >
+        {fallback || initials || <Person className="size-4" />}
+      </Avatar.Fallback>
+    </Avatar>
+  )
+}

package/src/components/user/user-button.tsx

@@ -0,0 +1,221 @@
+import { useAuth, useSession } from "@better-auth-ui/react"
+import {
+  ArrowRightFromSquare,
+  ArrowRightToSquare,
+  ChevronsExpandVertical,
+  Display,
+  Gear,
+  Moon,
+  PersonPlus,
+  Persons,
+  Sun
+} from "@gravity-ui/icons"
+import {
+  Button,
+  type ButtonProps,
+  cn,
+  Dropdown,
+  type DropdownPopoverProps,
+  Label,
+  Separator,
+  Tabs
+} from "@heroui/react"
+
+import { SwitchAccountMenu } from "./switch-account-menu"
+import { UserAvatar } from "./user-avatar"
+import { UserView } from "./user-view"
+
+export type UserButtonProps = {
+  className?: string
+  size?: "default" | "icon"
+  /**
+   * The placement of the element with respect to its anchor element.
+   * @default "bottom"
+   */
+  placement?: DropdownPopoverProps["placement"]
+  themeToggle?: boolean
+  variant?: ButtonProps["variant"]
+}
+
+/**
+ * Render a user account dropdown button that shows account actions, session switching, and theme controls.
+ *
+ * Renders either an icon-only trigger or a full button showing the current user state; its dropdown contains account settings, multi-session switching (when enabled), theme selection (when enabled), and sign-in/sign-out flows depending on authentication state.
+ *
+ * @param className - Additional CSS classes applied to the trigger element
+ * @param placement - Dropdown popover placement (e.g., "bottom", "top-start", "bottom-end")
+ * @param size - "icon" renders an avatar-only trigger; "default" renders a button with label and chevron
+ * @param variant - Button visual variant passed to the underlying Button component
+ * @param themeToggle - When true and theming is available, show theme selection controls in the menu
+ * @returns The user button and its dropdown menu as a JSX element
+ */
+export function UserButton({
+  className,
+  placement = "bottom",
+  size = "default",
+  variant = "ghost",
+  themeToggle = true
+}: UserButtonProps) {
+  const {
+    basePaths,
+    viewPaths,
+    localization,
+    multiSession,
+    appearance: { theme, setTheme, themes }
+  } = useAuth()
+
+  const { data: session, isPending: sessionPending } = useSession()
+
+  return (
+    <Dropdown>
+      {size === "icon" ? (
+        <Dropdown.Trigger className={cn("rounded-full", className)}>
+          <UserAvatar />
+        </Dropdown.Trigger>
+      ) : (
+        <Button
+          variant={variant}
+          className={cn(
+            "h-auto font-normal justify-start px-3 py-2 text-left",
+            className
+          )}
+        >
+          {session || sessionPending ? (
+            <UserView isPending={sessionPending} />
+          ) : (
+            <>
+              <UserAvatar />
+
+              <p className="text-sm font-medium">{localization.auth.account}</p>
+            </>
+          )}
+
+          <ChevronsExpandVertical className="ml-auto size-3.5" />
+        </Button>
+      )}
+
+      <Dropdown.Popover
+        placement={placement}
+        className="min-w-40 md:min-w-56 max-w-[48svw]"
+      >
+        {session && (
+          <div className="px-3 pt-3 pb-1">
+            <UserView />
+          </div>
+        )}
+
+        <Dropdown.Menu>
+          {session ? (
+            <>
+              <Dropdown.Item
+                textValue={localization.settings.settings}
+                href={`${basePaths.settings}/${viewPaths.settings.account}`}
+              >
+                <Gear className="text-muted" />
+
+                <Label>{localization.settings.settings}</Label>
+              </Dropdown.Item>
+
+              {multiSession && (
+                <Dropdown.SubmenuTrigger>
+                  <Dropdown.Item textValue={localization.auth.switchAccount}>
+                    <Persons className="text-muted" />
+
+                    <Label>{localization.auth.switchAccount}</Label>
+
+                    <Dropdown.SubmenuIndicator />
+                  </Dropdown.Item>
+
+                  <Dropdown.Popover className="min-w-40 md:min-w-56 max-w-[48svw]">
+                    <SwitchAccountMenu />
+                  </Dropdown.Popover>
+                </Dropdown.SubmenuTrigger>
+              )}
+
+              {themeToggle && theme && setTheme && !!themes?.length && (
+                <Dropdown.Item className="py-1 pe-2">
+                  <Label>{localization.settings.theme}</Label>
+
+                  <Tabs
+                    className="ml-auto"
+                    selectedKey={theme}
+                    onSelectionChange={(key) => setTheme(key as string)}
+                  >
+                    <Tabs.ListContainer>
+                      <Tabs.List
+                        aria-label={localization.settings.theme}
+                        className="*:h-5 *:w-5 *:p-0"
+                      >
+                        {themes.includes("system") && (
+                          <Tabs.Tab
+                            id="system"
+                            aria-label={localization.settings.system}
+                          >
+                            <Display className="size-3" />
+
+                            <Tabs.Indicator />
+                          </Tabs.Tab>
+                        )}
+                        {themes.includes("light") && (
+                          <Tabs.Tab
+                            id="light"
+                            aria-label={localization.settings.light}
+                          >
+                            <Sun className="size-3" />
+
+                            <Tabs.Indicator />
+                          </Tabs.Tab>
+                        )}
+                        {themes.includes("dark") && (
+                          <Tabs.Tab
+                            id="dark"
+                            aria-label={localization.settings.dark}
+                          >
+                            <Moon className="size-3" />
+
+                            <Tabs.Indicator />
+                          </Tabs.Tab>
+                        )}
+                      </Tabs.List>
+                    </Tabs.ListContainer>
+                  </Tabs>
+                </Dropdown.Item>
+              )}
+
+              <Separator />
+
+              <Dropdown.Item
+                textValue={localization.auth.signOut}
+                href={`${basePaths.auth}/${viewPaths.auth.signOut}`}
+              >
+                <ArrowRightFromSquare className="text-muted" />
+
+                <Label>{localization.auth.signOut}</Label>
+              </Dropdown.Item>
+            </>
+          ) : (
+            <>
+              <Dropdown.Item
+                textValue={localization.auth.signIn}
+                href={`${basePaths.auth}/${viewPaths.auth.signIn}`}
+              >
+                <ArrowRightToSquare className="text-muted" />
+
+                <Label>{localization.auth.signIn}</Label>
+              </Dropdown.Item>
+
+              <Dropdown.Item
+                textValue={localization.auth.signUp}
+                href={`${basePaths.auth}/${viewPaths.auth.signUp}`}
+              >
+                <PersonPlus className="text-muted" />
+
+                <Label>{localization.auth.signUp}</Label>
+              </Dropdown.Item>
+            </>
+          )}
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  )
+}