UI Components Reference

Beta

The Neon Auth with Better Auth is in Beta. Share your feedback on Discord or via the Neon Console.

Quick reference for Neon Auth UI components from @neondatabase/neon-js. These components are built with Better Auth UI and work with Neon Auth.

Installation

npm install @neondatabase/neon-js

Provider Setup

Wrap your app with NeonAuthUIProvider to enable the UI components. The provider accepts configuration props that control which features are available.

Basic Setup

import { NeonAuthUIProvider } from '@neondatabase/neon-js/auth/react';
import '@neondatabase/neon-js/ui/css';
import { authClient } from './auth';

function App() {
  return (
    <NeonAuthUIProvider authClient={authClient}>{/* Your app components */}</NeonAuthUIProvider>
  );
}

Common Props

Prop	Type	Description	Example
`authClient`	`NeonAuthPublicApi`	Required. Your Neon Auth client instance	`authClient={authClient}`
`social.providers`	`SocialProvider[]`	Array of OAuth providers to enable (e.g., Google, GitHub, Vercel)	`social={{ providers: ['google', 'github', 'vercel'] }}`
`navigate`	`(href: string) => void`	Navigation function for React Router	`navigate={navigate}`
`Link`	`ComponentType`	Custom Link component for routing	`Link={RouterLink}`
`localization`	`AuthLocalization`	Customize text labels throughout the UI	See example below
`avatar`	`AvatarOptions`	Avatar upload and display configuration	`avatar={{ size: 256, extension: 'webp' }}`
`additionalFields`	`AdditionalFields`	Custom fields for sign-up and account settings	See example below
`credentials.forgotPassword`	`boolean`	Enable forgot password flow	`credentials={{ forgotPassword: true }}`

Enable OAuth Providers

To enable Google sign-in (or other OAuth providers), add the social prop to the provider:

import { NeonAuthUIProvider } from '@neondatabase/neon-js/auth/react';
import { authClient } from './auth';

function App() {
  return (
    <NeonAuthUIProvider
      authClient={authClient}
      social={{
        providers: ['google', 'github', 'vercel'], // Enable Google, GitHub, and Vercel sign-in
      }}
    >
      {/* Your app */}
    </NeonAuthUIProvider>
  );
}

Note: Google OAuth works with shared credentials for development. GitHub OAuth requires custom credentials. The social.providers prop controls which provider buttons are displayed in the UI. For production, configure your own OAuth credentials in the Neon Console (Settings → Auth). See the OAuth setup guide for details.

React Router Integration

If using React Router, pass the navigate function and a custom Link component:

import { NeonAuthUIProvider } from '@neondatabase/neon-js/auth/react';
import { useNavigate, Link as RouterLink } from 'react-router-dom';
import { authClient } from './auth';

function App() {
  const navigate = useNavigate();

  return (
    <NeonAuthUIProvider
      authClient={authClient}
      navigate={navigate}
      Link={RouterLink}
      social={{
        providers: ['google', 'github', 'vercel'],
      }}
    >
      {/* Your app */}
    </NeonAuthUIProvider>
  );
}

Customization Examples

Custom localization:

<NeonAuthUIProvider
  authClient={authClient}
  localization={{
    SIGN_IN: 'Welcome Back',
    SIGN_UP: 'Create Account',
    FORGOT_PASSWORD: 'Forgot Password?',
  }}
>

Custom sign-up fields:

<NeonAuthUIProvider
  authClient={authClient}
  additionalFields={{
    company: {
      label: 'Company',
      placeholder: 'Your company name',
      type: 'string',
      required: false,
    },
  }}
  signUp={{
    fields: ['name', 'company'],
  }}
>

For complete prop documentation, see the TypeScript types exported from @neondatabase/neon-js/auth/react.

Core Components

Authentication Components

Component	Purpose	Key Props	Docs
`<AuthView>`	All-in-one auth UI with sign-in and sign-up forms	`pathname`	auth-view

Form Components: <SignUpForm>, <SignInForm>, <ForgotPasswordForm>, <ResetPasswordForm>, and <AuthCallback> are also available. <AuthView> includes sign-in and sign-up functionality with a "create account" link to switch between forms. Use the form components separately if you need more control over layout.

OAuth Provider Buttons: OAuth provider buttons (Google, GitHub, Vercel, etc.) appear automatically in <AuthView> when configured via the social.providers prop. OAuth buttons do not appear in standalone <SignInForm> or <SignUpForm> components.

User Management Components

Component	Purpose	Key Props	Docs
`<UserButton>`	User menu dropdown with avatar	-	user-button
`<UserAvatar>`	Profile picture with Gravatar support	`user`, `size`	user-avatar
`<SignedIn>`	Conditional rendering when signed in	`children`, `fallback`	signed-in
`<SignedOut>`	Conditional rendering when signed out	`children`, `fallback`	signed-out
`<RedirectToSignIn>`	Redirect helper to sign-in page	`redirectTo`	redirect-to-sign-in
`<RedirectToSignUp>`	Redirect helper to sign-up page	`redirectTo`	redirect-to-sign-up

Styling

Choose the import method based on your project setup:

Without Tailwind CSS

If your project doesn't use Tailwind CSS, import the pre-built CSS bundle:

// In your root layout or app entry point
import '@neondatabase/neon-js/ui/css';

This includes all necessary styles (~47KB minified) with no additional configuration required.

With Tailwind CSS v4

If your project already uses Tailwind CSS v4, import the Tailwind-ready CSS to avoid duplicate styles:

/* In your main CSS file (e.g., globals.css) */
@import 'tailwindcss';
@import '@neondatabase/neon-js/ui/tailwind';

This imports only the theme variables. Your Tailwind build generates the utility classes.

warning

Never import both paths. This causes duplicate styles.

For customization options, see Styling details within each Better Auth UI component docs page. Example: Auth View styling.

Example Usage

Basic Auth Flow

import { AuthView } from '@neondatabase/neon-js/auth/react/ui';
import '@neondatabase/neon-js/ui/css';

function App() {
  return <AuthView pathname="sign-in" />;
}

import { UserButton } from '@neondatabase/neon-js/auth/react/ui';
import { authClient } from './auth';

function Header() {
  return (
    <header>
      <UserButton authClient={authClient} />
    </header>
  );
}

Protected Route

import { SignedIn, SignedOut, RedirectToSignIn } from '@neondatabase/neon-js/auth/react/ui';

function Dashboard() {
  return (
    <>
      <SignedIn>
        <h1>Dashboard</h1>
      </SignedIn>
      <SignedOut>
        <RedirectToSignIn />
      </SignedOut>
    </>
  );
}

Next Steps

See React with Neon Auth UI for a complete example
Check the Neon Auth & Data API TypeScript SDKs for programmatic auth methods

UI Components Reference

Beta

Installation

Provider Setup

Basic Setup

Common Props

Enable OAuth Providers

React Router Integration

Customization Examples

Core Components

Authentication Components

User Management Components

Styling

Without Tailwind CSS

With Tailwind CSS v4

warning

Example Usage

Basic Auth Flow

User Menu

Protected Route

Next Steps

On this page