name	form-patterens-and-best-practices
description	This skill provides guidance for creating consistent, well-structured forms in Next.js/react applications using shadcn UI components, react-hook-form, and Zod validation.

Form Patterns and Best Practices

Overview

This skill provides guidance for creating consistent, well-structured forms in Next.js/react applications using shadcn UI components, react-hook-form, and Zod validation.

Form Structure Pattern

Required Imports

Every form should import the following components and libraries:

import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { Button } from "@/components/ui/button";
import { Input } from "@/components/ui/input";
import { Form, FormControl, FormField, FormItem, FormLabel, FormMessage } from "@/components/ui/form";
import { formSchema, type FormDataType } from "@/features/feature-name/schema"; // Adjust import path
import Link from "next/link"; // If needed for navigation

Form Component Structure

All forms should follow this structure with the shadcn Form components:

export const FormComponentName = () => {
  const form = useForm<FormDataType>({
    resolver: zodResolver(formSchema),
    // Optionally set default values
    // defaultValues: {
    //   fieldName: "defaultValue"
    // }
  });

  const onSubmit = async (data: FormDataType) => {
    // Handle form submission
    // This could be a mutation call, API request, etc.
  }

  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">

        <FormField
          name="fieldName"
          control={form.control}
          render={({ field }) => (
            <FormItem>
              <FormLabel>Field Label</FormLabel>
              <FormControl>
                <Input placeholder="Placeholder text" {...field} />
              </FormControl>
              <FormMessage />
            </FormItem>
          )}
        />

        {/* Add more FormField components as needed */}

        <Button type="submit" className="w-full">
          Submit
        </Button>
      </form>
    </Form>
  );
}

Feature Hook Integration

When creating forms that interact with feature-specific hooks (authentication, tasks, todos, etc.), integrate the hook's mutation functions:

Required Additional Imports

import { useFeatureName } from "@/features/feature-name/hooks"; // e.g., useAuth, useTasks, useTodos

Integration Pattern

export function FeatureFormComponent() {
  const { featureFunction: {  // e.g., signIn/signUp/forgotPassword for auth, createTask/updateTask for tasks
    mutateAsync: featureFunction,
    isPending: isLoading,
  } } = useFeatureName(); // e.g., useAuth, useTasks, useTodos

  // ... rest of the form structure remains the same, just with loading state in the button
  <Button type="submit" className="w-full" disabled={isLoading}>
    {isLoading ? "Submitting..." : "Action Text"}
  </Button>
}

Form Location and Organization

File Location

All form components MUST be placed in src/components/forms folder
Organize forms by feature or purpose
Keep form components separate from other UI components

File Naming Convention

Use descriptive names that reflect the form's purpose
Use kebab-case for file names (e.g., sign-in-form.tsx, user-profile-form.tsx)
Include "form" in the name to clearly identify it as a form component

Validation Schema Pattern

Schema Location

Form validation schemas MUST be placed in src/features/[feature-name]/schema.ts
Use Zod for schema validation
Export both the schema and the inferred type

Schema Example

import { z } from "zod";

export const formSchema = z.object({
  fieldName: z.string().min(1, { message: "Field is required" }),
  email: z.email({ message: "Invalid email address" }),
  password: z.string().min(8, { message: "Password must be at least 8 characters" }),
});

// For forms with confirm password validation
export const formWithConfirmPasswordSchema = z.object({
  password: z.string().min(8, { message: "Password must be at least 8 characters" }),
  confirmPassword: z.string(),
}).refine((data) => data.password === data.confirmPassword, {
  message: "Passwords do not match",
  path: ["confirmPassword"],
});

export type FormDataType = z.infer<typeof formSchema>;

Loading States and Error Handling

Loading States

Use the loading state from mutations when available (e.g., isPending from useFeatureName hooks)
Disable the submit button when loading
Show loading text in the button

Error Handling

Form validation errors are automatically handled by FormMessage components
API/mutation errors should be handled by the mutation's error handling in the hooks
Use toast notifications for user feedback when needed

form-patterens-and-best-practices

Install Skill

SKILL.md