> This page location: Backend > Neon Auth > Reference > UI Components
> Full Neon documentation index: https://neon.com/docs/llms.txt

> Summary: Step-by-step guide for integrating Neon Auth UI components using `@neondatabase/neon-js`, including installation, provider setup, and configuration of common props for customization.

# UI Components Reference

Quick reference for Neon Auth UI components

**Note: Beta**

The **Neon Auth with Better Auth** is in Beta. Share your feedback on [Discord](https://discord.gg/92vNTzKDGp) or via the [Neon Console](https://console.neon.tech/app/projects?modal=feedback).

Quick reference for Neon Auth UI components from `@neondatabase/auth-ui`. These components are built with [Better Auth UI](https://legacy.better-auth-ui.com/) and work with Neon Auth.

**Note: Migrating from older imports**

Older releases re-exported the UI from `@neondatabase/auth/react/ui` and `@neondatabase/neon-js/auth/react/ui`. Those entrypoints are deprecated and will be removed in the next major version. Install `@neondatabase/auth-ui` directly and run the codemod to update existing imports:

```bash
npx -p @neondatabase/auth neon-auth-codemod --write <path>
```

## Installation

```bash
npm install @neondatabase/neon-js@latest @neondatabase/auth-ui
```

## 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

```tsx
import { NeonAuthUIProvider } from '@neondatabase/auth-ui';
import '@neondatabase/auth-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 (for example, 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 }}`                 |
| `magicLink`                  | `boolean`                | Enable passwordless magic link sign-in option                            | `magicLink`                                              |

### Enable OAuth Providers

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

```tsx
import { NeonAuthUIProvider } from '@neondatabase/auth-ui';
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 OAuth credentials in the Neon Console (**branch → Auth**) and register provider redirect URIs (see [OAuth setup](https://neon.com/docs/auth/guides/setup-oauth#production-setup)).

### React Router Integration

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

```tsx
import { NeonAuthUIProvider } from '@neondatabase/auth-ui';
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:**

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

**Custom sign-up fields:**

```tsx
<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](https://legacy.better-auth-ui.com/components/auth-view) |

`<AuthView>` accepts both `path` and `pathname`. Use `path` for a bare view name (for example, `"sign-in"`). Use `pathname` for a full URL path (for example, `"/auth/sign-in"`); the component extracts the last segment automatically.

**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](https://legacy.better-auth-ui.com/components/user-button)                 |
| `<UserAvatar>`       | Profile picture with Gravatar support | `user`, `size`         | [user-avatar](https://legacy.better-auth-ui.com/components/user-avatar)                 |
| `<SignedIn>`         | Conditional rendering when signed in  | `children`, `fallback` | [signed-in](https://legacy.better-auth-ui.com/components/signed-in)                     |
| `<SignedOut>`        | Conditional rendering when signed out | `children`, `fallback` | [signed-out](https://legacy.better-auth-ui.com/components/signed-out)                   |
| `<RedirectToSignIn>` | Redirect helper to sign-in page       | `redirectTo`           | [redirect-to-sign-in](https://legacy.better-auth-ui.com/components/redirect-to-sign-in) |
| `<RedirectToSignUp>` | Redirect helper to sign-up page       | `redirectTo`           | [redirect-to-sign-up](https://legacy.better-auth-ui.com/components/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:

```typescript
// In your root layout or app entry point
import '@neondatabase/auth-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:

```css
/* In your main CSS file (for example, globals.css) */
@import 'tailwindcss';
@import '@neondatabase/auth-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](https://legacy.better-auth-ui.com/components/auth-view#styling).

## Example Usage

### Basic Auth Flow

```tsx
import { AuthView } from '@neondatabase/auth-ui';
import '@neondatabase/auth-ui/css';

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

### Next.js App Router

For Next.js App Router, use a catch-all route to handle all auth views. Create `app/auth/[path]/page.tsx`:

```tsx
import { AuthView } from '@neondatabase/auth-ui';
import { authViewPaths } from '@neondatabase/auth-ui/server';

export const dynamicParams = false;

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

export default async function AuthPage({
  params,
}: {
  params: Promise<{ path: string }>;
}) {
  const { path } = await params;

  return (
    <main className="flex min-h-screen items-center justify-center p-4">
      <AuthView path={path} />
    </main>
  );
}
```

### User Menu

```tsx
import { UserButton } from '@neondatabase/auth-ui';
import { authClient } from './auth';

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

### Protected Route

```tsx
import { SignedIn, SignedOut, RedirectToSignIn } from '@neondatabase/auth-ui';

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

## Next Steps

- See the [neon-js examples](https://github.com/neondatabase/neon-js/tree/main/examples) for runnable apps that use these components
- Check the [Neon TypeScript SDK](https://neon.com/docs/reference/javascript-sdk) for programmatic auth methods

---

## Related docs (Reference)

- [Neon TypeScript SDK](https://neon.com/docs/reference/javascript-sdk)
- [Next.js Server SDK](https://neon.com/docs/auth/reference/nextjs-server)