# Neon Auth UI - Next.js App Router
Complete UI setup guide for Neon Auth in Next.js App Router applications.
---
## Quick Setup
### 1. Import CSS
**If using Tailwind:**
```css
/* In app/globals.css */
@import '@neondatabase/auth/ui/tailwind';
```
**If NOT using Tailwind:**
```typescript
// In app/layout.tsx
import "@neondatabase/auth/ui/css";
```
**Warning:** Never import both - causes 94KB of duplicate styles.
### 2. Create Provider
Create `app/auth-provider.tsx`:
```tsx
"use client";
import { NeonAuthUIProvider } from "@neondatabase/auth/react/ui";
import { authClient } from "@/lib/auth/client";
import { useRouter } from "next/navigation";
import Link from "next/link";
export function AuthProvider({ children }: { children: React.ReactNode }) {
const router = useRouter();
return (
router.refresh()}
Link={Link}
social={{
providers: ["google", "github"]
}}
>
{children}
);
}
```
### 3. Wrap App
Update `app/layout.tsx`:
```tsx
import { AuthProvider } from "./auth-provider";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
```
### 4. Create Auth Pages
Create `app/auth/[path]/page.tsx`:
```tsx
import { AuthView } from "@neondatabase/auth/react/ui";
import { authViewPaths } from "@neondatabase/auth/react/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 ;
}
```
This creates routes: `/auth/sign-in`, `/auth/sign-up`, `/auth/forgot-password`, etc.
---
## Provider Configuration
### Props Reference
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `authClient` | `AuthClient` | Yes | The auth client instance from `createAuthClient()` |
| `navigate` | `(path: string) => void` | Yes | Function to navigate to a new route |
| `replace` | `(path: string) => void` | Yes | Function to replace current route (for redirects) |
| `Link` | `Component` | Yes | Next.js Link component |
| `onSessionChange` | `() => void` | No | Callback fired when authentication state changes |
| `avatar` | `{ upload: (file: File) => Promise }` | No | Avatar upload configuration |
| `social` | `{ providers: string[] }` | No | Social login providers to display |
### Social Login
```tsx
```
**Note:** Social buttons require TWO configurations:
1. Enable providers in Neon Console (Auth tab)
2. Add the `social` prop shown above to display buttons
### Avatar Upload
```tsx
{
const formData = new FormData();
formData.append("file", file);
const response = await fetch("/api/upload", {
method: "POST",
body: formData,
});
const { url } = await response.json();
return url;
},
}}
>
```
---
## UI Components
### Authentication
```tsx
import { AuthView, SignInForm, SignUpForm } from "@neondatabase/auth/react/ui";
// Full auth view (recommended)
// Individual forms
```
### User Components
```tsx
import { UserButton, UserAvatar, SignedIn, SignedOut } from "@neondatabase/auth/react/ui";
function Navbar() {
return (
);
}
```
### Protected Routes
```tsx
import { RedirectToSignIn, SignedIn } from "@neondatabase/auth/react/ui";
function ProtectedPage() {
return (
<>
Protected content
);
}
```
### Account Settings
```tsx
import { AccountView, SettingsCards } from "@neondatabase/auth/react/ui";
// Full account view
// Or individual cards
import {
UpdateAvatarCard,
UpdateNameCard,
ChangeEmailCard,
ChangePasswordCard,
SessionsCard,
DeleteAccountCard
} from "@neondatabase/auth/react/ui";
```
---
## CSS Variables
Use these when styling custom components:
| Variable | Purpose |
|----------|---------|
| `--background`, `--foreground` | Page background/text |
| `--card`, `--card-foreground` | Card surfaces |
| `--primary`, `--primary-foreground` | Primary buttons |
| `--muted`, `--muted-foreground` | Muted elements |
| `--border`, `--ring` | Borders and focus rings |
| `--radius` | Border radius |
**Usage:**
```css
background: hsl(var(--background));
color: hsl(var(--foreground));
```
**Dark mode:** Add the `dark` class to `` or ``.
---
## Import Paths
| What | Import Path |
|------|-------------|
| UI Provider | `@neondatabase/auth/react/ui` |
| Components | `@neondatabase/auth/react/ui` |
| Server utilities | `@neondatabase/auth/react/ui/server` |
| CSS | `@neondatabase/auth/ui/css` |
| Tailwind | `@neondatabase/auth/ui/tailwind` |
---
## Related References
- [Setup - Next.js](https://raw.githubusercontent.com/neondatabase-labs/ai-rules/main/references/neon-auth-setup-nextjs.md) - Auth client setup
- [Common Mistakes](https://raw.githubusercontent.com/neondatabase-labs/ai-rules/main/references/neon-auth-common-mistakes.md) - Import paths, adapter patterns
- [Troubleshooting](https://raw.githubusercontent.com/neondatabase-labs/ai-rules/main/references/neon-auth-troubleshooting.md) - Error solutions
---
**Reference Version**: 1.1.0
**Last Updated**: 2025-12-16