1# Auth Forms
2 
3## UAuthForm (recommended)
4 
5`UAuthForm` provides a complete auth form with fields, providers, validation, and submit — no manual `UForm` + `UFormField` wiring needed. Wrap it in `UPageCard` for a polished look.
6 
7```vue [pages/login.vue]
8<script setup lang="ts">
9import * as z from 'zod'
10import type { FormSubmitEvent, AuthFormField } from '@nuxt/ui'
11 
12const fields: AuthFormField[] = [{
13  name: 'email',
14  type: 'email',
15  label: 'Email',
16  placeholder: 'Enter your email',
17  required: true
18}, {
19  name: 'password',
20  label: 'Password',
21  type: 'password',
22  placeholder: 'Enter your password',
23  required: true
24}, {
25  name: 'remember',
26  label: 'Remember me',
27  type: 'checkbox'
28}]
29 
30const providers = [{
31  label: 'Google',
32  icon: 'i-simple-icons-google',
33  onClick: () => navigateTo('/auth/google', { external: true })
34}, {
35  label: 'GitHub',
36  icon: 'i-simple-icons-github',
37  onClick: () => navigateTo('/auth/github', { external: true })
38}]
39 
40const schema = z.object({
41  email: z.email('Invalid email'),
42  password: z.string('Password is required').min(8, 'Must be at least 8 characters')
43})
44 
45type Schema = z.output<typeof schema>
46 
47function onSubmit(payload: FormSubmitEvent<Schema>) {
48  // payload.data contains validated fields
49}
50</script>
51 
52<template>
53  <div class="flex min-h-dvh items-center justify-center">
54    <UPageCard class="w-full max-w-md">
55      <UAuthForm
56        :schema="schema"
57        :fields="fields"
58        :providers="providers"
59        title="Welcome back!"
60        description="Sign in to your account."
61        icon="i-lucide-lock"
62        @submit="onSubmit"
63      >
64        <template #password-hint>
65          <ULink to="/forgot-password" class="text-primary font-medium">Forgot password?</ULink>
66        </template>
67        <template #footer>
68          Don't have an account? <ULink to="/signup" class="text-primary font-medium">Sign up</ULink>.
69        </template>
70      </UAuthForm>
71    </UPageCard>
72  </div>
73</template>
74```
75 
76### UAuthForm key props
77 
78| Prop | Purpose |
79|---|---|
80| `title`, `description`, `icon` | Header content |
81| `fields` | `AuthFormField[]` — each has `name`, `type`, `label`, `placeholder`, `required` |
82| `providers` | `ButtonProps[]` — social login buttons shown above/below the form |
83| `schema` | Zod/Valibot schema for validation |
84| `submit` | Customize submit button: `{ label: 'Sign in', block: true }` |
85| `separator` | Text between providers and fields (default: `'or'`) |
86 
87### UAuthForm key slots
88 
89| Slot | Purpose |
90|---|---|
91| `#description` | Override description (e.g., add sign-up link) |
92| `#password-hint` | "Forgot password?" link on password field |
93| `#validation` | Custom error display (e.g., `UAlert`) |
94| `#footer` | Terms of service, sign-up link |
95| `#<field>-field` | Override a specific field's rendering |
96 
97## Custom auth layout
98 
99For layouts where `UAuthForm` is too opinionated, use `UCard` + `UForm` + `UFormField` directly.
100 
101```vue [pages/login.vue]
102<script setup lang="ts">
103import * as z from 'zod'
104import type { FormSubmitEvent } from '@nuxt/ui'
105 
106const schema = z.object({
107  email: z.email('Invalid email'),
108  password: z.string().min(1, 'Password is required')
109})
110 
111type Schema = z.output<typeof schema>
112const state = reactive<Partial<Schema>>({ email: '', password: '' })
113 
114async function onSubmit(event: FormSubmitEvent<Schema>) {
115  // event.data contains validated fields
116}
117</script>
118 
119<template>
120  <div class="flex min-h-dvh items-center justify-center">
121    <UCard class="w-full max-w-sm">
122      <template #header>
123        <div class="text-center">
124          <h1 class="text-xl font-semibold text-default">Welcome back</h1>
125          <p class="mt-1 text-sm text-muted">Sign in to your account</p>
126        </div>
127      </template>
128 
129      <UForm :schema="schema" :state="state" class="space-y-4" @submit="onSubmit">
130        <UFormField name="email" label="Email">
131          <UInput v-model="state.email" type="email" placeholder="[email protected]" />
132        </UFormField>
133 
134        <UFormField name="password" label="Password">
135          <template #hint>
136            <NuxtLink to="/forgot-password" class="text-sm text-primary">Forgot password?</NuxtLink>
137          </template>
138          <UInput v-model="state.password" type="password" />
139        </UFormField>
140 
141        <UButton type="submit" label="Sign in" block />
142      </UForm>
143 
144      <template #footer>
145        <p class="text-center text-sm text-muted">
146          Don't have an account?
147          <NuxtLink to="/signup" class="text-primary font-medium">Sign up</NuxtLink>
148        </p>
149      </template>
150    </UCard>
151  </div>
152</template>
153```
154 
155## Tips
156 
157- Prefer `UAuthForm` with `UPageCard` for standard auth pages — handles layout, providers, validation, and submit
158- Use `import * as z from 'zod'` and `z.email()` (Zod 4 syntax)
159- Type the submit handler: `function onSubmit(event: FormSubmitEvent<Schema>)` — access validated data via `event.data`
160- Center auth forms with `flex min-h-dvh items-center justify-center`
161- Place "Forgot password?" link as `#password-hint` slot on `UAuthForm`, or `#hint` slot on `UFormField`
162- Social login buttons: use `providers` prop on `UAuthForm`, or add manually with `<USeparator label="or" />`
163