From 6410659920a452764cc6e17358050f8a114acd7c Mon Sep 17 00:00:00 2001
From: Jake Ruesink <jaruesink@gmail.com>
Date: Fri, 14 Mar 2025 22:51:20 -0500
Subject: [PATCH 01/13] feat: enhance checkbox components with custom label
 support and improve form structure

- Added FullWidthLabel component for clickable label areas in checkbox list stories.
- Updated Checkbox component to accept custom components for flexibility.
- Refactored checkbox stories to utilize new features and improve layout.
- Adjusted form structure for better spacing and usability in checkbox examples.
- Added noNamespaceImport rule to biome configuration for better compatibility.
---
 ai/CustomInputsProject.md                     | 629 ++++++++++++++++++
 .../remix-hook-form/checkbox-list.stories.tsx |  63 +-
 .../src/remix-hook-form/checkbox.stories.tsx  |  82 +--
 .../custom-checkbox.stories.tsx               | 373 +++++++++++
 biome.json                                    |   3 +-
 .../src/remix-hook-form/checkbox.tsx          |  26 +-
 packages/components/src/ui/checkbox-field.tsx |  94 +--
 packages/components/src/ui/form.tsx           |   1 -
 8 files changed, 1178 insertions(+), 93 deletions(-)
 create mode 100644 ai/CustomInputsProject.md
 create mode 100644 apps/docs/src/remix-hook-form/custom-checkbox.stories.tsx

diff --git a/ai/CustomInputsProject.md b/ai/CustomInputsProject.md
new file mode 100644
index 00000000..c5b7aa05
--- /dev/null
+++ b/ai/CustomInputsProject.md
@@ -0,0 +1,629 @@
+# Custom Form Components Project
+
+## Overview
+
+This document outlines our approach to allowing users of our form library to inject their own custom components while maintaining a consistent API across all form elements. This feature enables users to fully customize the appearance and behavior of form components while preserving the form handling functionality.
+
+## High-Level Approach
+
+We use a component injection pattern that allows users to replace any part of our form components with their own implementations. This is achieved through a consistent `components` prop that accepts custom component implementations for various parts of the form element.
+
+### Key Principles
+
+1. **Consistency**: All form components follow the same pattern for customization
+2. **Flexibility**: Users can replace any part of a form component
+3. **Type Safety**: All component replacements are properly typed
+4. **Defaults**: Default components are provided if no custom components are specified
+5. **Backward Compatibility**: Existing implementations continue to work without changes
+
+## Implementation Details
+
+### Component Interface Extensions
+
+For each form component, we extend the base `FieldComponents` interface to include component-specific elements:
+
+```typescript
+// Base interface (already exists)
+export interface FieldComponents {
+  FormControl: React.ForwardRefExoticComponent<FormControlProps & React.RefAttributes<HTMLDivElement>>;
+  FormDescription: React.ForwardRefExoticComponent<FormDescriptionProps & React.RefAttributes<HTMLParagraphElement>>;
+  FormLabel: React.ForwardRefExoticComponent<FormLabelProps & React.RefAttributes<HTMLLabelElement>>;
+  FormMessage: React.ForwardRefExoticComponent<FormMessageProps & React.RefAttributes<HTMLParagraphElement>>;
+}
+
+// Extended interface for specific components (e.g., Checkbox)
+export interface CheckboxFieldComponents extends FieldComponents {
+  Checkbox?: React.ComponentType<React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root>>;
+  CheckboxIndicator?: React.ComponentType<React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Indicator>>;
+}
+```
+
+### Component Implementation
+
+In the component implementation, we extract custom components from the `components` prop with fallbacks to the default components:
+
+```typescript
+const CheckboxField = React.forwardRef<HTMLDivElement, CheckboxProps>(
+  ({ control, name, className, label, description, components, ...props }, ref) => {
+    // Extract custom components with fallbacks
+    const CheckboxComponent = components?.Checkbox || CheckboxPrimitive.Root;
+    const IndicatorComponent = components?.CheckboxIndicator || CheckboxPrimitive.Indicator;
+    
+    return (
+      <FormField
+        control={control}
+        name={name}
+        render={({ field, fieldState }) => (
+          <FormItem className={cn('flex flex-row items-start space-y-0', className)} ref={ref}>
+            <FormControl Component={components?.FormControl}>
+              <CheckboxComponent
+                ref={field.ref}
+                className="peer h-4 w-4 shrink-0 rounded-sm border border-primary ring-offset-background focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:bg-primary data-[state=checked]:text-primary-foreground"
+                checked={field.value}
+                onCheckedChange={field.onChange}
+                {...props}
+              >
+                <IndicatorComponent
+                  className={cn('flex items-center justify-center text-current')}
+                >
+                  <Check className="h-4 w-4" />
+                </IndicatorComponent>
+              </CheckboxComponent>
+            </FormControl>
+            {/* Rest of the component */}
+          </FormItem>
+        )}
+      />
+    );
+  }
+);
+```
+
+### Remix Hook Form Wrapper
+
+In the Remix Hook Form wrapper, we merge any user-provided components with the default form components:
+
+```typescript
+export function Checkbox(props: CheckboxProps) {
+  const { control } = useRemixFormContext();
+
+  const components: Partial<CheckboxFieldComponents> = {
+    FormDescription,
+    FormControl,
+    FormLabel,
+    FormMessage,
+    ...props.components, // Merge user components
+  };
+
+  return <BaseCheckbox control={control} {...props} components={components} />;
+}
+```
+
+## Usage Examples
+
+### Basic Usage (No Customization)
+
+```tsx
+import { Checkbox } from '@lambdacurry/forms';
+
+function MyForm() {
+  return (
+    <Checkbox 
+      name="terms" 
+      label="Accept terms"
+    />
+  );
+}
+```
+
+### Custom Checkbox Component
+
+```tsx
+import { Checkbox } from '@lambdacurry/forms';
+import { CheckIcon } from 'lucide-react';
+
+// Custom checkbox component
+const MyCustomCheckbox = React.forwardRef((props, ref) => (
+  <div 
+    ref={ref}
+    className="custom-checkbox"
+    data-state={props.checked ? 'checked' : 'unchecked'}
+    onClick={() => props.onCheckedChange(!props.checked)}
+    {...props}
+  >
+    {props.children}
+  </div>
+));
+
+// Custom indicator component
+const MyCustomIndicator = ({ className, children, ...props }) => (
+  <div className="custom-indicator" {...props}>
+    <CheckIcon className="h-3 w-3" />
+  </div>
+);
+
+function MyForm() {
+  return (
+    <Checkbox 
+      name="terms" 
+      label="Accept terms"
+      components={{
+        Checkbox: MyCustomCheckbox,
+        CheckboxIndicator: MyCustomIndicator
+      }}
+    />
+  );
+}
+```
+
+### Custom Form Elements
+
+```tsx
+import { Checkbox } from '@lambdacurry/forms';
+
+// Custom form label
+const MyCustomLabel = ({ className, children, ...props }) => (
+  <label className="my-custom-label" {...props}>
+    {children}
+  </label>
+);
+
+// Custom error message
+const MyCustomMessage = ({ className, children, ...props }) => (
+  <div className="my-custom-error" {...props}>
+    <AlertIcon className="h-4 w-4 mr-2" />
+    {children}
+  </div>
+);
+
+function MyForm() {
+  return (
+    <Checkbox 
+      name="terms" 
+      label="Accept terms"
+      components={{
+        FormLabel: MyCustomLabel,
+        FormMessage: MyCustomMessage
+      }}
+    />
+  );
+}
+```
+
+## Components to Update
+
+The following form components should be updated to support component injection:
+
+### 1. Checkbox
+```typescript
+export interface CheckboxFieldComponents extends FieldComponents {
+  Checkbox?: React.ComponentType<React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root>>;
+  CheckboxIndicator?: React.ComponentType<React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Indicator>>;
+}
+```
+
+### 2. TextField/TextInput
+```typescript
+export interface TextFieldComponents extends FieldComponents {
+  Input?: React.ComponentType<React.InputHTMLAttributes<HTMLInputElement>>;
+}
+```
+
+### 3. TextArea
+```typescript
+export interface TextAreaFieldComponents extends FieldComponents {
+  TextArea?: React.ComponentType<React.TextareaHTMLAttributes<HTMLTextAreaElement>>;
+}
+```
+
+### 4. RadioGroup
+```typescript
+export interface RadioGroupFieldComponents extends FieldComponents {
+  RadioGroup?: React.ComponentType<React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Root>>;
+  RadioGroupItem?: React.ComponentType<React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Item>>;
+  RadioGroupIndicator?: React.ComponentType<React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Indicator>>;
+}
+```
+
+### 5. Switch
+```typescript
+export interface SwitchFieldComponents extends FieldComponents {
+  Switch?: React.ComponentType<React.ComponentPropsWithoutRef<typeof SwitchPrimitive.Root>>;
+  SwitchThumb?: React.ComponentType<React.ComponentPropsWithoutRef<typeof SwitchPrimitive.Thumb>>;
+}
+```
+
+### 6. DatePicker
+```typescript
+export interface DatePickerFieldComponents extends FieldComponents {
+  DatePicker?: React.ComponentType<React.ComponentPropsWithoutRef<typeof Popover>>;
+  DatePickerTrigger?: React.ComponentType<React.ComponentPropsWithoutRef<typeof PopoverTrigger>>;
+  DatePickerContent?: React.ComponentType<React.ComponentPropsWithoutRef<typeof PopoverContent>>;
+  Calendar?: React.ComponentType<React.ComponentPropsWithoutRef<typeof DayPicker>>;
+}
+```
+
+### 7. OTPInput
+```typescript
+export interface OTPInputFieldComponents extends FieldComponents {
+  OTPInput?: React.ComponentType<React.ComponentPropsWithoutRef<typeof OTPInputPrimitive.Root>>;
+  OTPInputSlot?: React.ComponentType<React.ComponentPropsWithoutRef<typeof OTPInputPrimitive.Slot>>;
+  OTPInputChar?: React.ComponentType<React.ComponentPropsWithoutRef<typeof OTPInputPrimitive.Char>>;
+}
+```
+
+### 8. DropdownMenuSelect
+```typescript
+export interface DropdownMenuSelectFieldComponents extends FieldComponents {
+  DropdownMenu?: React.ComponentType<React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Root>>;
+  DropdownMenuTrigger?: React.ComponentType<React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Trigger>>;
+  DropdownMenuContent?: React.ComponentType<React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Content>>;
+  DropdownMenuItem?: React.ComponentType<React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Item>>;
+}
+```
+
+## Implementation Priority
+
+1. **High Priority**:
+   - Checkbox
+   - TextField
+   - RadioGroup
+   - Switch
+
+2. **Medium Priority**:
+   - TextArea
+   - DropdownMenuSelect
+
+3. **Low Priority**:
+   - DatePicker
+   - OTPInput
+
+## Implementation Template
+
+Here's a template for implementing component injection for each form component:
+
+```typescript
+// 1. Define component-specific interface
+export interface [Component]FieldComponents extends FieldComponents {
+  [Component]?: React.ComponentType<React.ComponentPropsWithoutRef<typeof [Component]Primitive.Root>>;
+  // Add any additional sub-components
+}
+
+// 2. Update props interface
+export interface [Component]Props<
+  TFieldValues extends FieldValues = FieldValues,
+  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+> extends [BaseProps] {
+  // Existing props
+  components?: Partial<[Component]FieldComponents>;
+}
+
+// 3. Update component implementation
+const [Component]Field = React.forwardRef<HTML[Element]Element, [Component]Props>(
+  ({ control, name, components, ...props }, ref) => {
+    // Extract custom components with fallbacks
+    const CustomComponent = components?.[Component] || [Component]Primitive.Root;
+    
+    return (
+      <FormField
+        control={control}
+        name={name}
+        render={({ field, fieldState }) => (
+          <FormItem ref={ref}>
+            {/* Use custom components */}
+            <CustomComponent {...field} {...props} />
+            {/* Rest of the component */}
+          </FormItem>
+        )}
+      />
+    );
+  }
+);
+
+// 4. Update Remix wrapper
+export function [Component](props: [Component]Props) {
+  const { control } = useRemixFormContext();
+
+  const components: Partial<[Component]FieldComponents> = {
+    FormDescription,
+    FormControl,
+    FormLabel,
+    FormMessage,
+    ...props.components,
+  };
+
+  return <Base[Component] control={control} {...props} components={components} />;
+}
+```
+
+## Testing Strategy
+
+When implementing custom component injection, follow these testing steps:
+
+
+## 1. Storybook Examples
+
+Based on our existing checkbox.stories.tsx, we should create stories that demonstrate both default and custom component usage. Here's how to enhance our stories:
+
+#### Example: Custom Checkbox Story Implementation
+
+```tsx
+import { zodResolver } from '@hookform/resolvers/zod';
+import { Checkbox } from '@lambdacurry/forms/remix-hook-form/checkbox';
+import { Button } from '@lambdacurry/forms/ui/button';
+import type { ActionFunctionArgs } from '@remix-run/node';
+import { useFetcher } from '@remix-run/react';
+import type { Meta, StoryContext, StoryObj } from '@storybook/react';
+import { expect, userEvent } from '@storybook/test';
+import * as React from 'react';
+import { RemixFormProvider, getValidatedFormData, useRemixForm } from 'remix-hook-form';
+import { z } from 'zod';
+import { withRemixStubDecorator } from '../lib/storybook/remix-stub';
+
+// Custom checkbox component
+const CustomCheckbox = React.forwardRef<
+  HTMLDivElement, 
+  React.ComponentPropsWithoutRef<'div'> & { checked?: boolean; onCheckedChange?: (checked: boolean) => void }
+>((props, ref) => {
+  const { checked, onCheckedChange, children, className, ...rest } = props;
+  
+  return (
+    <div 
+      ref={ref}
+      role="checkbox"
+      aria-checked={checked}
+      data-state={checked ? 'checked' : 'unchecked'}
+      className={`custom-checkbox relative flex h-6 w-6 items-center justify-center rounded-md border-2 border-primary ${
+        checked ? 'bg-primary' : 'bg-background'
+      } ${className}`}
+      onClick={() => onCheckedChange?.(!checked)}
+      {...rest}
+    >
+      {children}
+    </div>
+  );
+});
+CustomCheckbox.displayName = 'CustomCheckbox';
+
+// Custom indicator component
+const CustomIndicator = ({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) => (
+  <div className={`text-white ${className}`} {...props}>
+    ✓
+  </div>
+);
+
+// Form schema (same as original)
+const formSchema = z.object({
+  terms: z.boolean().refine((val) => val === true, 'You must accept the terms and conditions'),
+  marketing: z.boolean().optional(),
+  required: z.boolean().refine((val) => val === true, 'This field is required'),
+});
+
+type FormData = z.infer<typeof formSchema>;
+
+// Example with custom components
+const CustomCheckboxExample = () => {
+  const fetcher = useFetcher<{ message: string }>();
+  const methods = useRemixForm<FormData>({
+    resolver: zodResolver(formSchema),
+    defaultValues: {
+      terms: false as true,
+      marketing: false,
+      required: false as true,
+    },
+    fetcher,
+    submitConfig: {
+      action: '/',
+      method: 'post',
+    },
+  });
+
+  return (
+    <RemixFormProvider {...methods}>
+      <fetcher.Form onSubmit={methods.handleSubmit}>
+        <div className="grid gap-4">
+          <Checkbox 
+            className="rounded-md border p-4" 
+            name="terms" 
+            label="Accept terms and conditions"
+            components={{
+              Checkbox: CustomCheckbox,
+              CheckboxIndicator: CustomIndicator
+            }}
+          />
+          <Checkbox
+            className="rounded-md border p-4"
+            name="marketing"
+            label="Receive marketing emails"
+            description="We will send you hourly updates about our products"
+            // Using default components for this checkbox
+          />
+          <Checkbox 
+            className="rounded-md border p-4" 
+            name="required" 
+            label="This is a required checkbox"
+            components={{
+              Checkbox: CustomCheckbox,
+              CheckboxIndicator: CustomIndicator
+            }}
+          />
+        </div>
+        <Button type="submit" className="mt-4">
+          Submit
+        </Button>
+        {fetcher.data?.message && <p className="mt-2 text-green-600">{fetcher.data.message}</p>}
+      </fetcher.Form>
+    </RemixFormProvider>
+  );
+};
+
+// Handler function (same as original)
+const handleFormSubmission = async (request: Request) => {
+  const { errors } = await getValidatedFormData<FormData>(request, zodResolver(formSchema));
+
+  if (errors) {
+    return { errors };
+  }
+
+  return { message: 'Form submitted successfully' };
+};
+
+// Story definition
+export const CustomComponents: Story = {
+  render: () => <CustomCheckboxExample />,
+  parameters: {
+    docs: {
+      description: {
+        story: 'Example of checkbox with custom components.',
+      },
+      source: {
+        code: `
+import { Checkbox } from '@lambdacurry/forms/remix-hook-form/checkbox';
+
+// Custom checkbox component
+const CustomCheckbox = React.forwardRef((props, ref) => {
+  const { checked, onCheckedChange, children, className, ...rest } = props;
+  
+  return (
+    <div 
+      ref={ref}
+      role="checkbox"
+      aria-checked={checked}
+      data-state={checked ? 'checked' : 'unchecked'}
+      className={\`custom-checkbox relative flex h-6 w-6 items-center justify-center rounded-md border-2 border-primary \${
+        checked ? 'bg-primary' : 'bg-background'
+      } \${className}\`}
+      onClick={() => onCheckedChange?.(!checked)}
+      {...rest}
+    >
+      {children}
+    </div>
+  );
+});
+
+// Custom indicator component
+const CustomIndicator = ({ className, ...props }) => (
+  <div className={\`text-white \${className}\`} {...props}>
+    ✓
+  </div>
+);
+
+// Usage in form
+<Checkbox 
+  name="terms" 
+  label="Accept terms and conditions"
+  components={{
+    Checkbox: CustomCheckbox,
+    CheckboxIndicator: CustomIndicator
+  }}
+/>`,
+      },
+    },
+  },
+  play: async (storyContext) => {
+    const { canvas } = storyContext;
+    
+    // Test 1: Verify custom checkboxes are rendered
+    const customCheckboxes = canvas.getAllByRole('checkbox');
+    expect(customCheckboxes.length).toBe(3);
+    
+    // Test 2: Verify custom checkboxes can be checked
+    const termsCheckbox = canvas.getByLabelText('Accept terms and conditions');
+    const requiredCheckbox = canvas.getByLabelText('This is a required checkbox');
+    
+    await userEvent.click(termsCheckbox);
+    await userEvent.click(requiredCheckbox);
+    
+    expect(termsCheckbox).toHaveAttribute('aria-checked', 'true');
+    expect(requiredCheckbox).toHaveAttribute('aria-checked', 'true');
+    
+    // Test 3: Verify form submission works with custom components
+    const submitButton = canvas.getByRole('button', { name: 'Submit' });
+    await userEvent.click(submitButton);
+    
+    await expect(await canvas.findByText('Form submitted successfully')).toBeInTheDocument();
+  },
+};
+```
+
+### 4. Testing Custom Form Elements
+
+In addition to testing custom input components, we should also test custom form elements like labels and error messages:
+
+```tsx
+// Custom form elements example
+const CustomFormElementsExample = () => {
+  // ... form setup code ...
+
+  return (
+    <RemixFormProvider {...methods}>
+      <fetcher.Form onSubmit={methods.handleSubmit}>
+        <div className="grid gap-4">
+          <Checkbox 
+            className="rounded-md border p-4" 
+            name="terms" 
+            label="Accept terms and conditions"
+            components={{
+              FormLabel: ({ children, ...props }) => (
+                <label className="custom-label text-blue-600 font-bold" {...props}>
+                  {children} ★
+                </label>
+              ),
+              FormMessage: ({ children, ...props }) => (
+                <div className="custom-error flex items-center text-red-500" {...props}>
+                  <span className="mr-1">⚠️</span> {children}
+                </div>
+              )
+            }}
+          />
+          {/* ... other form fields ... */}
+        </div>
+        <Button type="submit" className="mt-4">Submit</Button>
+      </fetcher.Form>
+    </RemixFormProvider>
+  );
+};
+
+// Tests for custom form elements
+const testCustomFormElements = async ({ canvas }: StoryContext) => {
+  // Test 1: Verify custom label is rendered
+  const customLabel = canvas.getByText(/Accept terms and conditions ★/);
+  expect(customLabel).toHaveClass('custom-label');
+  
+  // Test 2: Verify custom error message is rendered after invalid submission
+  const submitButton = canvas.getByRole('button', { name: 'Submit' });
+  await userEvent.click(submitButton);
+  
+  const errorMessage = await canvas.findByText('You must accept the terms and conditions');
+  expect(errorMessage.parentElement).toHaveClass('custom-error');
+  expect(errorMessage.parentElement?.querySelector('span')?.textContent).toBe('⚠️');
+};
+```
+
+### 5. Accessibility Testing
+
+When implementing custom components, it's crucial to maintain accessibility. Here are specific tests to include:
+
+```tsx
+const testAccessibility = async ({ canvas }: StoryContext) => {
+  // Test 1: Verify custom checkbox has proper ARIA attributes
+  const checkbox = canvas.getByLabelText('Accept terms and conditions');
+  expect(checkbox).toHaveAttribute('role', 'checkbox');
+  expect(checkbox).toHaveAttribute('aria-checked', 'false');
+  
+  // Test 2: Verify checkbox can be toggled with keyboard
+  checkbox.focus();
+  await userEvent.keyboard(' '); // Space key
+  expect(checkbox).toHaveAttribute('aria-checked', 'true');
+  
+  // Test 3: Verify form label is properly associated with the checkbox
+  const label = canvas.getByText('Accept terms and conditions');
+  expect(label).toHaveAttribute('for', checkbox.id);
+};
+```
+
+## Conclusion
+
+This component injection pattern provides a flexible and consistent way for users to customize any part of our form components while maintaining a clean API. By following this approach across all form components, we ensure a unified experience for library users.
+
+The implementation should be done incrementally, starting with the high-priority components, and ensuring backward compatibility at each step.
diff --git a/apps/docs/src/remix-hook-form/checkbox-list.stories.tsx b/apps/docs/src/remix-hook-form/checkbox-list.stories.tsx
index 71994d77..3d283113 100644
--- a/apps/docs/src/remix-hook-form/checkbox-list.stories.tsx
+++ b/apps/docs/src/remix-hook-form/checkbox-list.stories.tsx
@@ -8,6 +8,7 @@ import { Form } from '@remix-run/react';
 import type { Meta, StoryContext, StoryObj } from '@storybook/react';
 import { expect, userEvent } from '@storybook/test';
 import type {} from '@testing-library/dom';
+import * as React from 'react';
 import { RemixFormProvider, createFormData, getValidatedFormData, useRemixForm } from 'remix-hook-form';
 import { z } from 'zod';
 import { withRemixStubDecorator } from '../lib/storybook/remix-stub';
@@ -28,6 +29,23 @@ const formSchema = z.object({
 
 type FormData = z.infer<typeof formSchema>;
 
+// Custom FormLabel component that makes the entire area clickable
+const FullWidthLabel = React.forwardRef<HTMLLabelElement, React.ComponentPropsWithoutRef<'label'>>(
+  ({ className, children, htmlFor, ...props }, ref) => {
+    return (
+      <label
+        ref={ref}
+        htmlFor={htmlFor}
+        className={`absolute inset-0 cursor-pointer flex items-center py-4 px-8 ${className}`}
+        {...props}
+      >
+        <span className="ml-2">{children}</span>
+      </label>
+    );
+  },
+);
+FullWidthLabel.displayName = 'FullWidthLabel';
+
 const ControlledCheckboxListExample = () => {
   const fetcher = useFetcher<{ message: string; selectedColors: string[] }>();
   const methods = useRemixForm<FormData>({
@@ -58,8 +76,6 @@ const ControlledCheckboxListExample = () => {
     },
   });
 
-  console.log(methods.formState);
-
   return (
     <RemixFormProvider {...methods}>
       <Form onSubmit={methods.handleSubmit}>
@@ -67,7 +83,15 @@ const ControlledCheckboxListExample = () => {
           <p className="text-sm text-gray-500">Select your favorite colors:</p>
           <div className="grid gap-4">
             {AVAILABLE_COLORS.map(({ value, label }) => (
-              <Checkbox key={value} className="rounded-md border p-4" name={`colors.${value}`} label={label} />
+              <Checkbox
+                key={value}
+                className="relative rounded-md border p-4 hover:bg-gray-50"
+                name={`colors.${value}`}
+                label={label}
+                components={{
+                  FormLabel: FullWidthLabel,
+                }}
+              />
             ))}
           </div>
           <FormMessage error={methods.formState.errors.colors?.root?.message} />
@@ -153,7 +177,36 @@ export const Tests: Story = {
   parameters: {
     docs: {
       description: {
-        story: 'A checkbox list component for selecting multiple colors.',
+        story: 'A checkbox list component for selecting multiple colors with full-width clickable area.',
+      },
+      source: {
+        code: `
+// Custom FormLabel component that makes the entire area clickable
+const FullWidthLabel = React.forwardRef<HTMLLabelElement, React.ComponentPropsWithoutRef<'label'>>(
+  ({ className, children, htmlFor, ...props }, ref) => {
+    return (
+      <label
+        ref={ref}
+        htmlFor={htmlFor}
+        className={\`absolute inset-0 cursor-pointer flex items-center py-4 px-8 \${className}\`}
+        {...props}
+      >
+        <span className="ml-2">{children}</span>
+      </label>
+    );
+  },
+);
+
+// Usage in your component
+<Checkbox
+  className="relative rounded-md border p-4 hover:bg-gray-50"
+  name="colors.red"
+  label="Red"
+  components={{
+    FormLabel: FullWidthLabel,
+  }}
+/>
+`,
       },
     },
   },
@@ -162,4 +215,4 @@ export const Tests: Story = {
     await testErrorState(storyContext);
     await testColorSelection(storyContext);
   },
-};
\ No newline at end of file
+};
diff --git a/apps/docs/src/remix-hook-form/checkbox.stories.tsx b/apps/docs/src/remix-hook-form/checkbox.stories.tsx
index 0b44fa67..50ef78f6 100644
--- a/apps/docs/src/remix-hook-form/checkbox.stories.tsx
+++ b/apps/docs/src/remix-hook-form/checkbox.stories.tsx
@@ -5,7 +5,6 @@ import type { ActionFunctionArgs } from '@remix-run/node';
 import { useFetcher } from '@remix-run/react';
 import type { Meta, StoryContext, StoryObj } from '@storybook/react';
 import { expect, userEvent } from '@storybook/test';
-import type {} from '@testing-library/dom';
 import { RemixFormProvider, getValidatedFormData, useRemixForm } from 'remix-hook-form';
 import { z } from 'zod';
 import { withRemixStubDecorator } from '../lib/storybook/remix-stub';
@@ -37,17 +36,16 @@ const ControlledCheckboxExample = () => {
   return (
     <RemixFormProvider {...methods}>
       <fetcher.Form onSubmit={methods.handleSubmit}>
-        <div className="grid gap-4">
-          <Checkbox className="rounded-md border p-4" name="terms" label="Accept terms and conditions" />
+        <div className="grid gap-8">
+          <Checkbox name="terms" label="Accept terms and conditions" />
           <Checkbox
-            className="rounded-md border p-4"
             name="marketing"
             label="Receive marketing emails"
             description="We will send you hourly updates about our products"
           />
-          <Checkbox className="rounded-md border p-4" name="required" label="This is a required checkbox" />
+          <Checkbox name="required" label="This is a required checkbox" />
         </div>
-        <Button type="submit" className="mt-4">
+        <Button type="submit" className="mt-8">
           Submit
         </Button>
         {fetcher.data?.message && <p className="mt-2 text-green-600">{fetcher.data.message}</p>}
@@ -112,7 +110,7 @@ const testValidSubmission = async ({ canvas }: StoryContext) => {
   await expect(await canvas.findByText('Form submitted successfully')).toBeInTheDocument();
 };
 
-export const Tests: Story = {
+export const Default: Story = {
   parameters: {
     docs: {
       description: {
@@ -120,40 +118,44 @@ export const Tests: Story = {
       },
       source: {
         code: `
-    const formSchema = z.object({
-    terms: z.boolean().optional().refine(val => val === true, 'You must accept the terms and conditions'),
-    marketing: z.boolean().optional(),
-    required: z.boolean().optional().refine(val => val === true, 'This field is required'),
+const formSchema = z.object({
+  terms: z.boolean().refine(val => val === true, 'You must accept the terms and conditions'),
+  marketing: z.boolean().optional(),
+  required: z.boolean().refine(val => val === true, 'This field is required'),
+});
+
+const ControlledCheckboxExample = () => {
+  const fetcher = useFetcher<{ message: string }>();
+  const methods = useRemixForm<FormData>({
+    resolver: zodResolver(formSchema),
+    defaultValues: {
+      terms: false as true, // Note: ZOD Schema expects a true value
+      marketing: false,
+      required: false as true //Note: ZOD Schema expects a true value
+    },
+    fetcher,
+    submitConfig: {
+      action: '/',
+      method: 'post',
+    },
   });
 
-  const ControlledCheckboxExample = () => {
-    const fetcher = useFetcher<{ message: string }>();
-    const methods = useRemixForm<FormData>({
-      resolver: zodResolver(formSchema),
-      defaultValues: {
-        terms: false as true, // Note: ZOD Schema expects a true value
-        marketing: false,
-        required: false as true //Note: ZOD Schema expects a true value
-      },
-      fetcher,
-    });
-
-    return (
-      <RemixFormProvider {...methods}>
-        <fetcher.Form onSubmit={methods.handleSubmit} method="post" action="/">
-          <div className='grid gap-4'>
-            <Checkbox className='rounded-md border p-4' name="terms" label="Accept terms and conditions" />
-            <Checkbox className='rounded-md border p-4' name="marketing" label="Receive marketing emails" description="We will send you hourly updates about our products" />
-            <Checkbox className='rounded-md border p-4' name="required" label="This is a required checkbox" />
-          </div>
-          <Button type="submit" className="mt-4">
-            Submit
-          </Button>
-          {fetcher.data?.message && <p className="mt-2 text-green-600">{fetcher.data.message}</p>}
-        </fetcher.Form>
-      </RemixFormProvider>
-    );
-  };`,
+  return (
+    <RemixFormProvider {...methods}>
+      <fetcher.Form onSubmit={methods.handleSubmit}>
+        <div className='grid gap-8'>
+          <Checkbox name="terms" label="Accept terms and conditions" />
+          <Checkbox name="marketing" label="Receive marketing emails" description="We will send you hourly updates about our products" />
+          <Checkbox name="required" label="This is a required checkbox" />
+        </div>
+        <Button type="submit" className="mt-8">
+          Submit
+        </Button>
+        {fetcher.data?.message && <p className="mt-2 text-green-600">{fetcher.data.message}</p>}
+      </fetcher.Form>
+    </RemixFormProvider>
+  );
+};`,
       },
     },
   },
@@ -162,4 +164,4 @@ export const Tests: Story = {
     await testInvalidSubmission(storyContext);
     await testValidSubmission(storyContext);
   },
-};
\ No newline at end of file
+};
diff --git a/apps/docs/src/remix-hook-form/custom-checkbox.stories.tsx b/apps/docs/src/remix-hook-form/custom-checkbox.stories.tsx
new file mode 100644
index 00000000..66032077
--- /dev/null
+++ b/apps/docs/src/remix-hook-form/custom-checkbox.stories.tsx
@@ -0,0 +1,373 @@
+import { zodResolver } from '@hookform/resolvers/zod';
+import { Checkbox } from '@lambdacurry/forms/remix-hook-form/checkbox';
+import type { FormLabel, FormMessage } from '@lambdacurry/forms/remix-hook-form/form';
+import { Button } from '@lambdacurry/forms/ui/button';
+import * as CheckboxPrimitive from '@radix-ui/react-checkbox';
+import type { ActionFunctionArgs } from '@remix-run/node';
+import { useFetcher } from '@remix-run/react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { expect, userEvent, within } from '@storybook/test';
+import * as React from 'react';
+import { RemixFormProvider, getValidatedFormData, useRemixForm } from 'remix-hook-form';
+import { z } from 'zod';
+import { withRemixStubDecorator } from '../lib/storybook/remix-stub';
+
+const formSchema = z.object({
+  terms: z.boolean().refine((val) => val === true, 'You must accept the terms and conditions'),
+  marketing: z.boolean().optional(),
+  required: z.boolean().refine((val) => val === true, 'This field is required'),
+});
+
+type FormData = z.infer<typeof formSchema>;
+
+// Custom checkbox component
+const PurpleCheckbox = React.forwardRef<
+  HTMLButtonElement,
+  React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root>
+>((props, ref) => (
+  <CheckboxPrimitive.Root
+    ref={ref}
+    {...props}
+    className="h-8 w-8 rounded-full border-4 border-purple-500 bg-white data-[state=checked]:bg-purple-500"
+  >
+    {props.children}
+  </CheckboxPrimitive.Root>
+));
+PurpleCheckbox.displayName = 'PurpleCheckbox';
+
+// Custom indicator
+const PurpleIndicator = React.forwardRef<
+  HTMLDivElement,
+  React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Indicator>
+>((props, ref) => (
+  <CheckboxPrimitive.Indicator
+    ref={ref}
+    {...props}
+    className="flex h-full w-full items-center justify-center text-white"
+  >
+    ✓
+  </CheckboxPrimitive.Indicator>
+));
+PurpleIndicator.displayName = 'PurpleIndicator';
+
+// Custom form label component
+const CustomLabel = React.forwardRef<HTMLLabelElement, React.ComponentPropsWithoutRef<typeof FormLabel>>(
+  ({ className, htmlFor, ...props }, ref) => (
+    <label
+      ref={ref}
+      htmlFor={htmlFor}
+      className={`custom-label text-purple-600 font-bold text-lg ${className}`}
+      {...props}
+    >
+      {props.children} ★
+    </label>
+  ),
+);
+CustomLabel.displayName = 'CustomLabel';
+
+// Custom error message component
+const CustomErrorMessage = React.forwardRef<HTMLParagraphElement, React.ComponentPropsWithoutRef<typeof FormMessage>>(
+  ({ className, ...props }, ref) => (
+    <p
+      ref={ref}
+      className={`custom-error flex items-center text-red-500 bg-red-100 p-2 rounded-md ${className}`}
+      {...props}
+    >
+      <span className="mr-1 text-lg">⚠️</span> {props.children}
+    </p>
+  ),
+);
+CustomErrorMessage.displayName = 'CustomErrorMessage';
+
+// Example with custom checkbox components
+const PurpleCheckboxExample = () => {
+  const fetcher = useFetcher<{ message: string }>();
+  const methods = useRemixForm<FormData>({
+    resolver: zodResolver(formSchema),
+    defaultValues: {
+      terms: false as true,
+      marketing: false,
+      required: false as true,
+    },
+    fetcher,
+    submitConfig: {
+      action: '/',
+      method: 'post',
+    },
+  });
+
+  return (
+    <RemixFormProvider {...methods}>
+      <fetcher.Form onSubmit={methods.handleSubmit}>
+        <div className="grid gap-8">
+          <Checkbox
+            name="terms"
+            label="Accept terms and conditions"
+            description="You must accept our terms to continue"
+            components={{
+              Checkbox: PurpleCheckbox,
+              CheckboxIndicator: PurpleIndicator,
+            }}
+          />
+        </div>
+        <Button type="submit" className="mt-8">
+          Submit
+        </Button>
+        {fetcher.data?.message && <p className="mt-2 text-green-600">{fetcher.data.message}</p>}
+      </fetcher.Form>
+    </RemixFormProvider>
+  );
+};
+
+// Example with custom label components
+const CustomLabelExample = () => {
+  const fetcher = useFetcher<{ message: string }>();
+  const methods = useRemixForm<FormData>({
+    resolver: zodResolver(formSchema),
+    defaultValues: {
+      terms: false as true,
+      marketing: false,
+      required: false as true,
+    },
+    fetcher,
+    submitConfig: {
+      action: '/',
+      method: 'post',
+    },
+  });
+
+  return (
+    <RemixFormProvider {...methods}>
+      <fetcher.Form onSubmit={methods.handleSubmit}>
+        <div className="grid gap-8">
+          <Checkbox
+            name="required"
+            label="This is a required checkbox"
+            components={{
+              FormLabel: CustomLabel,
+              FormMessage: CustomErrorMessage,
+            }}
+          />
+        </div>
+        <Button type="submit" className="mt-8">
+          Submit
+        </Button>
+        {fetcher.data?.message && <p className="mt-2 text-green-600">{fetcher.data.message}</p>}
+      </fetcher.Form>
+    </RemixFormProvider>
+  );
+};
+
+// Example with all custom components
+const AllCustomComponentsExample = () => {
+  const fetcher = useFetcher<{ message: string }>();
+  const methods = useRemixForm<FormData>({
+    resolver: zodResolver(formSchema),
+    defaultValues: {
+      terms: false as true,
+      marketing: false,
+      required: false as true,
+    },
+    fetcher,
+    submitConfig: {
+      action: '/',
+      method: 'post',
+    },
+  });
+
+  const customCheckboxComponents = {
+    Checkbox: PurpleCheckbox,
+    CheckboxIndicator: PurpleIndicator,
+  };
+
+  const customLabelComponents = {
+    FormLabel: CustomLabel,
+    FormMessage: CustomErrorMessage,
+  };
+
+  return (
+    <RemixFormProvider {...methods}>
+      <fetcher.Form onSubmit={methods.handleSubmit}>
+        <div className="grid gap-8">
+          <Checkbox
+            name="terms"
+            label="Accept terms and conditions"
+            components={{
+              ...customCheckboxComponents,
+              ...customLabelComponents,
+            }}
+          />
+          <Checkbox
+            name="marketing"
+            label="Receive marketing emails"
+            description="We will send you hourly updates about our products"
+            // Using default components for this checkbox
+          />
+          <Checkbox name="required" label="This is a required checkbox" components={customLabelComponents} />
+        </div>
+        <Button type="submit" className="mt-8">
+          Submit
+        </Button>
+        {fetcher.data?.message && <p className="mt-2 text-green-600">{fetcher.data.message}</p>}
+      </fetcher.Form>
+    </RemixFormProvider>
+  );
+};
+
+const handleFormSubmission = async (request: Request) => {
+  const { errors } = await getValidatedFormData<FormData>(request, zodResolver(formSchema));
+
+  if (errors) {
+    return { errors };
+  }
+
+  return { message: 'Form submitted successfully' };
+};
+
+const meta: Meta<typeof Checkbox> = {
+  title: 'RemixHookForm/CustomCheckbox',
+  component: Checkbox,
+  parameters: { layout: 'centered' },
+  tags: ['autodocs'],
+} satisfies Meta<typeof Checkbox>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const CustomCheckboxComponentExamples: Story = {
+  name: 'Custom Checkbox Component Examples',
+  decorators: [
+    withRemixStubDecorator({
+      root: {
+        Component: AllCustomComponentsExample,
+        action: async ({ request }: ActionFunctionArgs) => handleFormSubmission(request),
+      },
+    }),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        story: 'Examples of custom checkbox components with different styling options.',
+      },
+      source: {
+        code: `
+// Custom checkbox component
+const PurpleCheckbox = React.forwardRef<
+  HTMLButtonElement,
+  React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root>
+>((props, ref) => (
+  <CheckboxPrimitive.Root
+    ref={ref}
+    {...props}
+    className="h-8 w-8 rounded-full border-4 border-purple-500 bg-white data-[state=checked]:bg-purple-500"
+  >
+    {props.children}
+  </CheckboxPrimitive.Root>
+));
+
+// Custom indicator
+const PurpleIndicator = React.forwardRef<
+  HTMLDivElement,
+  React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Indicator>
+>((props, ref) => (
+  <CheckboxPrimitive.Indicator
+    ref={ref}
+    {...props}
+    className="flex h-full w-full items-center justify-center text-white"
+  >
+    ✓
+  </CheckboxPrimitive.Indicator>
+));
+
+// Custom form label component
+const CustomLabel = React.forwardRef<
+  HTMLLabelElement,
+  React.ComponentPropsWithoutRef<typeof FormLabel>
+>(({ className, htmlFor, ...props }, ref) => (
+  <label
+    ref={ref}
+    htmlFor={htmlFor}
+    className={\`custom-label text-purple-600 font-bold text-lg \${className}\`}
+    {...props}
+  >
+    {props.children} ★
+  </label>
+));
+
+// Custom error message component
+const CustomErrorMessage = React.forwardRef<
+  HTMLParagraphElement,
+  React.ComponentPropsWithoutRef<typeof FormMessage>
+>(({ className, ...props }, ref) => (
+  <p
+    ref={ref}
+    className={\`custom-error flex items-center text-red-500 bg-red-100 p-2 rounded-md \${className}\`}
+    {...props}
+  >
+    <span className="mr-1 text-lg">⚠️</span> {props.children}
+  </p>
+));
+
+// Usage in form
+<Checkbox
+  name="terms"
+  label="Accept terms and conditions"
+  components={{
+    ...customCheckboxComponents,
+    ...customLabelComponents,
+  }}
+/>
+
+<Checkbox
+  name="required"
+  label="This is a required checkbox"
+  components={customLabelComponents}
+/>`,
+      },
+    },
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    // Find all checkboxes
+    const checkboxElements = canvas.getAllByRole('checkbox', { hidden: true });
+
+    // Get all button checkboxes
+    const checkboxButtons = Array.from(checkboxElements)
+      .map((checkbox) => checkbox.closest('button'))
+      .filter((button) => button !== null) as HTMLButtonElement[];
+
+    // We should have at least one custom checkbox button
+    expect(checkboxButtons.length).toBeGreaterThan(0);
+
+    // Find the custom purple checkbox (the one with rounded-full class)
+    const purpleCheckbox = checkboxButtons.find(
+      (button) => button.classList.contains('rounded-full') && button.classList.contains('border-purple-500'),
+    );
+
+    if (purpleCheckbox) {
+      // Verify custom checkbox styling
+      expect(purpleCheckbox).toHaveClass('rounded-full');
+      expect(purpleCheckbox).toHaveClass('border-purple-500');
+
+      // Check the terms checkbox
+      await userEvent.click(purpleCheckbox);
+      expect(purpleCheckbox).toHaveAttribute('data-state', 'checked');
+
+      // Find the required checkbox (we'll just check all remaining checkboxes)
+      for (const button of checkboxButtons) {
+        if (button !== purpleCheckbox) {
+          await userEvent.click(button);
+        }
+      }
+
+      // Submit the form
+      const submitButton = canvas.getByRole('button', { name: 'Submit' });
+      await userEvent.click(submitButton);
+
+      // Verify successful submission
+      const successMessage = await canvas.findByText('Form submitted successfully');
+      expect(successMessage).toBeInTheDocument();
+    }
+  },
+};
diff --git a/biome.json b/biome.json
index b8268c48..058d760f 100644
--- a/biome.json
+++ b/biome.json
@@ -30,7 +30,8 @@
         "noImplicitBoolean": "off",
         "noDefaultExport": "off",
         "noUnusedTemplateLiteral": "off",
-        "useFilenamingConvention": "off"
+        "useFilenamingConvention": "off",
+        "noNamespaceImport": "off"
       },
       "complexity": {
         "all": true,
diff --git a/packages/components/src/remix-hook-form/checkbox.tsx b/packages/components/src/remix-hook-form/checkbox.tsx
index 719cb820..b0bf0967 100644
--- a/packages/components/src/remix-hook-form/checkbox.tsx
+++ b/packages/components/src/remix-hook-form/checkbox.tsx
@@ -1,18 +1,28 @@
 import { useRemixFormContext } from 'remix-hook-form';
-import { Checkbox as BaseCheckbox, type CheckboxProps as BaseCheckboxProps } from '../ui/checkbox-field';
-import { FormControl , FormDescription, FormLabel, FormMessage } from './form';
+import {
+  Checkbox as BaseCheckbox,
+  type CheckboxProps as BaseCheckboxProps,
+  type CheckboxFieldComponents,
+} from '../ui/checkbox-field';
+import { FormControl, FormDescription, FormLabel, FormMessage } from './form';
 
 export type CheckboxProps = Omit<BaseCheckboxProps, 'control'>;
 
 export function Checkbox(props: CheckboxProps) {
   const { control } = useRemixFormContext();
 
-  const components = {
-    FormDescription: FormDescription,
-    FormControl: FormControl,
-    FormLabel: FormLabel,
-    FormMessage: FormMessage,
+  // Destructure components from props to avoid it being overridden
+  const { components: customComponents, ...restProps } = props;
+
+  // Create a new components object that merges the default components with any custom components
+  const mergedComponents: Partial<CheckboxFieldComponents> = {
+    FormDescription,
+    FormControl,
+    FormLabel,
+    FormMessage,
+    ...customComponents, // Merge user components
   };
 
-  return <BaseCheckbox control={control} {...props} components={components} />;
+  // Pass the merged components to the BaseCheckbox
+  return <BaseCheckbox control={control} components={mergedComponents} {...restProps} />;
 }
diff --git a/packages/components/src/ui/checkbox-field.tsx b/packages/components/src/ui/checkbox-field.tsx
index 10a36289..f9af3f7f 100644
--- a/packages/components/src/ui/checkbox-field.tsx
+++ b/packages/components/src/ui/checkbox-field.tsx
@@ -1,7 +1,5 @@
-// biome-ignore lint/style/noNamespaceImport: fromRadix
 import * as CheckboxPrimitive from '@radix-ui/react-checkbox';
 import { Check } from 'lucide-react';
-// biome-ignore lint/style/noNamespaceImport: prevents React undefined errors when exporting as a component library
 import * as React from 'react';
 
 import type { Control, FieldPath, FieldValues } from 'react-hook-form';
@@ -16,6 +14,11 @@ import {
 } from './form';
 import { cn } from './utils';
 
+export interface CheckboxFieldComponents extends FieldComponents {
+  Checkbox?: React.ComponentType<React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root>>;
+  CheckboxIndicator?: React.ComponentType<React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Indicator>>;
+}
+
 export interface CheckboxProps<
   TFieldValues extends FieldValues = FieldValues,
   TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
@@ -25,48 +28,63 @@ export interface CheckboxProps<
   label?: React.ReactNode;
   description?: string;
   className?: string;
-  components?: Partial<FieldComponents>;
+  components?: Partial<CheckboxFieldComponents>;
   indicatorClassName?: string;
   checkClassName?: string;
 }
 
 const CheckboxField = React.forwardRef<HTMLDivElement, CheckboxProps>(
-  ({ control, name, className, label, description, components, indicatorClassName, checkClassName, ...props }, ref) => (
-    <FormField
-      control={control}
-      name={name}
-      render={({ field, fieldState }) => (
-        <FormItem className={cn('flex flex-row items-start space-y-0', className)} ref={ref}>
-          <FormControl Component={components?.FormControl}>
-            <CheckboxPrimitive.Root
-              ref={field.ref}
-              className="peer h-4 w-4 shrink-0 rounded-sm border border-primary ring-offset-background focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:bg-primary data-[state=checked]:text-primary-foreground"
-              checked={field.value}
-              onCheckedChange={field.onChange}
-              {...props}
-            >
-              <CheckboxPrimitive.Indicator
-                className={cn('flex items-center justify-center text-current', indicatorClassName)}
+  ({ control, name, className, label, description, components, indicatorClassName, checkClassName, ...props }, ref) => {
+    // Extract custom components with fallbacks
+    const CheckboxComponent = components?.Checkbox || CheckboxPrimitive.Root;
+    const IndicatorComponent = components?.CheckboxIndicator || CheckboxPrimitive.Indicator;
+
+    // Determine if we're using custom components
+    const isCustomCheckbox = components?.Checkbox !== undefined;
+    const isCustomIndicator = components?.CheckboxIndicator !== undefined;
+
+    // Default checkbox className
+    const defaultCheckboxClassName =
+      'peer h-4 w-4 shrink-0 rounded-sm border border-primary ring-offset-background focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:bg-primary data-[state=checked]:text-primary-foreground';
+
+    // Default indicator className
+    const defaultIndicatorClassName = cn('flex items-center justify-center text-current', indicatorClassName);
+
+    return (
+      <FormField
+        control={control}
+        name={name}
+        render={({ field, fieldState }) => (
+          <FormItem className={cn('flex flex-row items-start space-y-0', className)} ref={ref}>
+            <FormControl Component={components?.FormControl}>
+              <CheckboxComponent
+                ref={field.ref}
+                className={isCustomCheckbox ? undefined : defaultCheckboxClassName}
+                checked={field.value}
+                onCheckedChange={field.onChange}
+                {...props}
               >
-                <Check className={cn('h-4 w-4', checkClassName)} />
-              </CheckboxPrimitive.Indicator>
-            </CheckboxPrimitive.Root>
-          </FormControl>
-          <div className="space-y-1 leading-none">
-            {label && (
-              <FormLabel Component={components?.FormLabel} className="!text-inherit">
-                {label}
-              </FormLabel>
-            )}
-            {description && <FormDescription Component={components?.FormDescription}>{description}</FormDescription>}
-            {fieldState.error && (
-              <FormMessage Component={components?.FormMessage}>{fieldState.error.message}</FormMessage>
-            )}
-          </div>
-        </FormItem>
-      )}
-    />
-  ),
+                <IndicatorComponent className={isCustomIndicator ? undefined : defaultIndicatorClassName}>
+                  <Check className={cn('h-4 w-4', checkClassName)} />
+                </IndicatorComponent>
+              </CheckboxComponent>
+            </FormControl>
+            <div className="space-y-1 leading-none">
+              {label && (
+                <FormLabel Component={components?.FormLabel} className="!text-inherit">
+                  {label}
+                </FormLabel>
+              )}
+              {description && <FormDescription Component={components?.FormDescription}>{description}</FormDescription>}
+              {fieldState.error && (
+                <FormMessage Component={components?.FormMessage}>{fieldState.error.message}</FormMessage>
+              )}
+            </div>
+          </FormItem>
+        )}
+      />
+    );
+  },
 );
 
 CheckboxField.displayName = CheckboxPrimitive.Root.displayName;
diff --git a/packages/components/src/ui/form.tsx b/packages/components/src/ui/form.tsx
index 27997abc..7c28a6bc 100644
--- a/packages/components/src/ui/form.tsx
+++ b/packages/components/src/ui/form.tsx
@@ -1,6 +1,5 @@
 import type * as LabelPrimitive from '@radix-ui/react-label';
 import { Slot } from '@radix-ui/react-slot';
-// biome-ignore lint/style/noNamespaceImport: prevents React undefined errors when exporting as a component library
 import * as React from 'react';
 import { Controller, type ControllerProps, type FieldPath, type FieldValues } from 'react-hook-form';
 import { Label } from './label';

From 511dc4937fe54516311d64ec7311078b34df5484 Mon Sep 17 00:00:00 2001
From: Jake Ruesink <jaruesink@gmail.com>
Date: Fri, 14 Mar 2025 23:22:02 -0500
Subject: [PATCH 02/13] chore: update package dependencies and configuration

- Removed outdated dependency "@date-fns/tz" from yarn.lock.
- Upgraded "@radix-ui/react-slot" to version 1.1.2 in package.json and yarn.lock.
- Downgraded "react-day-picker" to version 8.10.1 in package.json and yarn.lock.
- Updated components alias in components.json for improved path resolution.
- Refactored button component styles for better layout and spacing.
- Cleaned up imports in date-picker-field component.
---
 packages/components/components.json           |  2 +-
 packages/components/package.json              |  4 +-
 packages/components/src/ui/button.tsx         |  3 +-
 .../components/src/ui/date-picker-field.tsx   |  1 -
 yarn.lock                                     | 42 +++++++++++--------
 5 files changed, 28 insertions(+), 24 deletions(-)

diff --git a/packages/components/components.json b/packages/components/components.json
index d1400af1..283b1e3f 100644
--- a/packages/components/components.json
+++ b/packages/components/components.json
@@ -10,7 +10,7 @@
     "cssVariables": true
   },
   "aliases": {
-    "components": "@/src",
+    "components": "src",
     "utils": "@/lib/utils"
   }
 }
diff --git a/packages/components/package.json b/packages/components/package.json
index dd3c0c12..d1624ea4 100644
--- a/packages/components/package.json
+++ b/packages/components/package.json
@@ -50,7 +50,7 @@
     "@radix-ui/react-popover": "^1.1.4",
     "@radix-ui/react-radio-group": "^1.2.2",
     "@radix-ui/react-scroll-area": "^1.2.2",
-    "@radix-ui/react-slot": "^1.1.1",
+    "@radix-ui/react-slot": "^1.1.2",
     "@radix-ui/react-switch": "^1.1.2",
     "@radix-ui/react-tooltip": "^1.1.6",
     "@remix-run/node": "^2.15.1",
@@ -62,7 +62,7 @@
     "input-otp": "^1.4.1",
     "lucide-react": "^0.468.0",
     "next-themes": "^0.4.4",
-    "react-day-picker": "9.4.4",
+    "react-day-picker": "8.10.1",
     "react-hook-form": "^7.53.1",
     "remix-hook-form": "5.1.1",
     "sonner": "^1.7.1",
diff --git a/packages/components/src/ui/button.tsx b/packages/components/src/ui/button.tsx
index b09044cc..41242b6e 100644
--- a/packages/components/src/ui/button.tsx
+++ b/packages/components/src/ui/button.tsx
@@ -1,11 +1,10 @@
 import { Slot } from '@radix-ui/react-slot';
 import { type VariantProps, cva } from 'class-variance-authority';
-// biome-ignore lint/style/noNamespaceImport: prevents React undefined errors when exporting as a component library
 import * as React from 'react';
 import { cn } from './utils';
 
 const buttonVariants = cva(
-  'inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50',
+  'inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0',
   {
     variants: {
       variant: {
diff --git a/packages/components/src/ui/date-picker-field.tsx b/packages/components/src/ui/date-picker-field.tsx
index d60b1324..7830f4e5 100644
--- a/packages/components/src/ui/date-picker-field.tsx
+++ b/packages/components/src/ui/date-picker-field.tsx
@@ -1,6 +1,5 @@
 import { format } from 'date-fns';
 import { Calendar as CalendarIcon } from 'lucide-react';
-// biome-ignore lint/style/noNamespaceImport: prevents React undefined errors when exporting as a component library
 import * as React from 'react';
 import type { Control, FieldPath, FieldValues } from 'react-hook-form';
 import { Button } from './button';
diff --git a/yarn.lock b/yarn.lock
index 66f042ed..9be7ebe4 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -875,13 +875,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@date-fns/tz@npm:^1.2.0":
-  version: 1.2.0
-  resolution: "@date-fns/tz@npm:1.2.0"
-  checksum: 10c0/411e9d4303b10951f6fd0189d18fb845f0d934a575df2176bc10daf664282c765fb6b057a977e446bbb1229151d89e7788978600a019f1fc24b5c75276d496bd
-  languageName: node
-  linkType: hard
-
 "@emotion/hash@npm:^0.9.0":
   version: 0.9.2
   resolution: "@emotion/hash@npm:0.9.2"
@@ -2006,7 +1999,7 @@ __metadata:
     "@radix-ui/react-popover": "npm:^1.1.4"
     "@radix-ui/react-radio-group": "npm:^1.2.2"
     "@radix-ui/react-scroll-area": "npm:^1.2.2"
-    "@radix-ui/react-slot": "npm:^1.1.1"
+    "@radix-ui/react-slot": "npm:^1.1.2"
     "@radix-ui/react-switch": "npm:^1.1.2"
     "@radix-ui/react-tooltip": "npm:^1.1.6"
     "@remix-run/dev": "npm:^2.15.1"
@@ -2029,7 +2022,7 @@ __metadata:
     next-themes: "npm:^0.4.4"
     postcss: "npm:^8.4.49"
     react: "npm:^19.0.0"
-    react-day-picker: "npm:9.4.4"
+    react-day-picker: "npm:8.10.1"
     react-hook-form: "npm:^7.53.1"
     remix-hook-form: "npm:5.1.1"
     sonner: "npm:^1.7.1"
@@ -2829,7 +2822,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@radix-ui/react-slot@npm:1.1.1, @radix-ui/react-slot@npm:^1.1.1":
+"@radix-ui/react-slot@npm:1.1.1":
   version: 1.1.1
   resolution: "@radix-ui/react-slot@npm:1.1.1"
   dependencies:
@@ -2844,6 +2837,21 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@radix-ui/react-slot@npm:^1.1.2":
+  version: 1.1.2
+  resolution: "@radix-ui/react-slot@npm:1.1.2"
+  dependencies:
+    "@radix-ui/react-compose-refs": "npm:1.1.1"
+  peerDependencies:
+    "@types/react": "*"
+    react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+  peerDependenciesMeta:
+    "@types/react":
+      optional: true
+  checksum: 10c0/81d45091806c52b507cec80b4477e4f31189d76ffcd7845b382eb3a034e6cf1faef71b881612028d5893f7580bf9ab59daa18fbf2792042dccd755c99a18df67
+  languageName: node
+  linkType: hard
+
 "@radix-ui/react-switch@npm:^1.1.2":
   version: 1.1.2
   resolution: "@radix-ui/react-switch@npm:1.1.2"
@@ -11625,15 +11633,13 @@ __metadata:
   languageName: node
   linkType: hard
 
-"react-day-picker@npm:9.4.4":
-  version: 9.4.4
-  resolution: "react-day-picker@npm:9.4.4"
-  dependencies:
-    "@date-fns/tz": "npm:^1.2.0"
-    date-fns: "npm:^4.1.0"
+"react-day-picker@npm:8.10.1":
+  version: 8.10.1
+  resolution: "react-day-picker@npm:8.10.1"
   peerDependencies:
-    react: ">=16.8.0"
-  checksum: 10c0/0a8cfa99863854538cd58bfe28fc68febcf7c7f72e14be2e1a4f108ec9e803838bf5dae946e3f2b1900a6ddef520daf666a49bac4a551de35e8e37a347f694cb
+    date-fns: ^2.28.0 || ^3.0.0
+    react: ^16.8.0 || ^17.0.0 || ^18.0.0
+  checksum: 10c0/a0ff28c4b61b3882e6a825b19e5679e2fdf3256cf1be8eb0a0c028949815c1ae5a6561474c2c19d231c010c8e0e0b654d3a322610881e0655abca05a2e03d9df
   languageName: node
   linkType: hard
 

From c6be1850660704a3a55864cba070b3c7b9c561b7 Mon Sep 17 00:00:00 2001
From: Jake Ruesink <jaruesink@gmail.com>
Date: Sat, 15 Mar 2025 00:08:16 -0500
Subject: [PATCH 03/13] feat: enhance radio group and checkbox components with
 custom implementations and examples

- Added comprehensive Storybook examples for custom checkbox and radio group components.
- Implemented custom components for checkbox, including PurpleCheckbox, PurpleIndicator, CustomLabel, and CustomErrorMessage.
- Updated RadioGroup to support custom components and improved structure for better flexibility.
- Enhanced RadioGroupField to accept custom components and added className support for styling.
- Included interactive tests to verify custom component functionality and styling.
- Documented key takeaways for component overriding to ensure type safety and accessibility.
---
 ai/CustomInputsProject.md                     | 180 +++++
 .../custom-radio-group.stories.tsx            | 660 ++++++++++++++++++
 .../remix-hook-form/radio-group.stories.tsx   |   2 +-
 .../src/remix-hook-form/radio-group.tsx       |  17 +-
 .../components/src/ui/radio-group-field.tsx   |  25 +-
 packages/components/src/ui/radio-group.tsx    |  29 +-
 6 files changed, 898 insertions(+), 15 deletions(-)
 create mode 100644 apps/docs/src/remix-hook-form/custom-radio-group.stories.tsx

diff --git a/ai/CustomInputsProject.md b/ai/CustomInputsProject.md
index c5b7aa05..cd694458 100644
--- a/ai/CustomInputsProject.md
+++ b/ai/CustomInputsProject.md
@@ -622,6 +622,186 @@ const testAccessibility = async ({ canvas }: StoryContext) => {
 };
 ```
 
+## Implementation Examples
+
+### Custom Checkbox Story Implementation
+
+We've created a comprehensive Storybook example that demonstrates how to override components in our checkbox field. The example can be found in `apps/docs/src/remix-hook-form/custom-checkbox.stories.tsx`.
+
+Here's how we implemented custom components for the checkbox:
+
+```tsx
+// Custom checkbox component
+const PurpleCheckbox = React.forwardRef<
+  HTMLButtonElement,
+  React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root>
+>((props, ref) => (
+  <CheckboxPrimitive.Root
+    ref={ref}
+    {...props}
+    className="h-8 w-8 rounded-full border-4 border-purple-500 bg-white data-[state=checked]:bg-purple-500"
+  >
+    {props.children}
+  </CheckboxPrimitive.Root>
+));
+PurpleCheckbox.displayName = 'PurpleCheckbox';
+
+// Custom indicator
+const PurpleIndicator = React.forwardRef<
+  HTMLDivElement,
+  React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Indicator>
+>((props, ref) => (
+  <CheckboxPrimitive.Indicator
+    ref={ref}
+    {...props}
+    className="flex h-full w-full items-center justify-center text-white"
+  >
+    ✓
+  </CheckboxPrimitive.Indicator>
+));
+PurpleIndicator.displayName = 'PurpleIndicator';
+
+// Custom form label component
+const CustomLabel = React.forwardRef<HTMLLabelElement, React.ComponentPropsWithoutRef<typeof FormLabel>>(
+  ({ className, htmlFor, ...props }, ref) => (
+    <label
+      ref={ref}
+      htmlFor={htmlFor}
+      className={`custom-label text-purple-600 font-bold text-lg ${className}`}
+      {...props}
+    >
+      {props.children} ★
+    </label>
+  ),
+);
+CustomLabel.displayName = 'CustomLabel';
+
+// Custom error message component
+const CustomErrorMessage = React.forwardRef<HTMLParagraphElement, React.ComponentPropsWithoutRef<typeof FormMessage>>(
+  ({ className, ...props }, ref) => (
+    <p
+      ref={ref}
+      className={`custom-error flex items-center text-red-500 bg-red-100 p-2 rounded-md ${className}`}
+      {...props}
+    >
+      <span className="mr-1 text-lg">⚠️</span> {props.children}
+    </p>
+  ),
+);
+CustomErrorMessage.displayName = 'CustomErrorMessage';
+```
+
+### Component Overriding Examples
+
+The story demonstrates three different ways to override components:
+
+#### 1. Overriding Just the Checkbox Components
+
+```tsx
+<Checkbox
+  name="terms"
+  label="Accept terms and conditions"
+  description="You must accept our terms to continue"
+  components={{
+    Checkbox: PurpleCheckbox,
+    CheckboxIndicator: PurpleIndicator,
+  }}
+/>
+```
+
+#### 2. Overriding Just the Form Components
+
+```tsx
+<Checkbox
+  name="required"
+  label="This is a required checkbox"
+  components={{
+    FormLabel: CustomLabel,
+    FormMessage: CustomErrorMessage,
+  }}
+/>
+```
+
+#### 3. Overriding All Components
+
+```tsx
+// Create component objects for reuse
+const customCheckboxComponents = {
+  Checkbox: PurpleCheckbox,
+  CheckboxIndicator: PurpleIndicator,
+};
+
+const customLabelComponents = {
+  FormLabel: CustomLabel,
+  FormMessage: CustomErrorMessage,
+};
+
+// Use spread operator to combine them
+<Checkbox
+  name="terms"
+  label="Accept terms and conditions"
+  components={{
+    ...customCheckboxComponents,
+    ...customLabelComponents,
+  }}
+/>
+```
+
+### Testing Custom Components
+
+Our story includes interactive tests that verify:
+
+1. Custom styling is applied correctly
+2. Component functionality works as expected
+3. Form validation still works with custom components
+
+```tsx
+play: async ({ canvasElement }) => {
+  const canvas = within(canvasElement);
+
+  // Find all checkboxes
+  const checkboxElements = canvas.getAllByRole('checkbox', { hidden: true });
+
+  // Get all button checkboxes
+  const checkboxButtons = Array.from(checkboxElements)
+    .map((checkbox) => checkbox.closest('button'))
+    .filter((button) => button !== null) as HTMLButtonElement[];
+
+  // Find the custom purple checkbox
+  const purpleCheckbox = checkboxButtons.find(
+    (button) => button.classList.contains('rounded-full') && button.classList.contains('border-purple-500'),
+  );
+
+  if (purpleCheckbox) {
+    // Verify custom checkbox styling
+    expect(purpleCheckbox).toHaveClass('rounded-full');
+    expect(purpleCheckbox).toHaveClass('border-purple-500');
+
+    // Check the terms checkbox
+    await userEvent.click(purpleCheckbox);
+    expect(purpleCheckbox).toHaveAttribute('data-state', 'checked');
+
+    // Submit the form
+    const submitButton = canvas.getByRole('button', { name: 'Submit' });
+    await userEvent.click(submitButton);
+
+    // Verify successful submission
+    const successMessage = await canvas.findByText('Form submitted successfully');
+    expect(successMessage).toBeInTheDocument();
+  }
+}
+```
+
+### Key Takeaways for Component Overriding
+
+1. **Type Safety**: All custom components are properly typed using React's `forwardRef` and `ComponentPropsWithoutRef`
+2. **Prop Forwarding**: Custom components forward all necessary props to maintain functionality
+3. **Ref Handling**: Refs are properly forwarded to maintain form control integration
+4. **Composition**: Components can be overridden individually or as groups
+5. **Accessibility**: Custom components maintain proper ARIA attributes and keyboard navigation
+
+This approach provides a flexible and consistent way for users to customize any part of our form components while maintaining a clean API and ensuring accessibility.
+
 ## Conclusion
 
 This component injection pattern provides a flexible and consistent way for users to customize any part of our form components while maintaining a clean API. By following this approach across all form components, we ensure a unified experience for library users.
diff --git a/apps/docs/src/remix-hook-form/custom-radio-group.stories.tsx b/apps/docs/src/remix-hook-form/custom-radio-group.stories.tsx
new file mode 100644
index 00000000..aa16cca3
--- /dev/null
+++ b/apps/docs/src/remix-hook-form/custom-radio-group.stories.tsx
@@ -0,0 +1,660 @@
+import { zodResolver } from '@hookform/resolvers/zod';
+import { RadioGroup } from '@lambdacurry/forms/remix-hook-form/radio-group';
+import { Button } from '@lambdacurry/forms/ui/button';
+import { FormLabel, FormMessage } from '@lambdacurry/forms/ui/form';
+import { RadioGroupItem } from '@lambdacurry/forms/ui/radio-group';
+import { cn } from '@lambdacurry/forms/ui/utils';
+import * as RadioGroupPrimitive from '@radix-ui/react-radio-group';
+import type { ActionFunctionArgs } from '@remix-run/node';
+import { Form, useFetcher } from '@remix-run/react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { expect, userEvent, within } from '@storybook/test';
+import * as React from 'react';
+import { RemixFormProvider, getValidatedFormData, useRemixForm } from 'remix-hook-form';
+import { z } from 'zod';
+import { withRemixStubDecorator } from '../lib/storybook/remix-stub';
+
+const formSchema = z.object({
+  plan: z.enum(['starter', 'pro', 'enterprise'], {
+    required_error: 'You need to select a plan',
+  }),
+  requiredPlan: z.enum(['starter', 'pro', 'enterprise'], {
+    required_error: 'This field is required',
+  }),
+});
+
+type FormData = z.infer<typeof formSchema>;
+
+// Custom radio group component
+const PurpleRadioGroup = React.forwardRef<
+  React.ComponentRef<typeof RadioGroupPrimitive.Root>,
+  React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Root>
+>((props, ref) => {
+  return (
+    <RadioGroupPrimitive.Root
+      ref={ref}
+      className="flex flex-col space-y-4 border-2 border-purple-300 rounded-lg p-4 bg-purple-50"
+      {...props}
+    />
+  );
+});
+PurpleRadioGroup.displayName = 'PurpleRadioGroup';
+
+// Custom radio group item component
+const PurpleRadioGroupItem = React.forwardRef<
+  React.ComponentRef<typeof RadioGroupPrimitive.Item>,
+  React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Item> & {
+    indicator?: React.ReactNode;
+  }
+>((props, ref) => {
+  return (
+    <RadioGroupPrimitive.Item
+      ref={ref}
+      className="h-6 w-6 rounded-full border-2 border-purple-500 text-purple-600 ring-offset-background focus:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50"
+      {...props}
+    >
+      {props.children}
+    </RadioGroupPrimitive.Item>
+  );
+});
+PurpleRadioGroupItem.displayName = 'PurpleRadioGroupItem';
+
+// Custom radio group indicator component
+const PurpleRadioGroupIndicator = React.forwardRef<
+  React.ComponentRef<typeof RadioGroupPrimitive.Indicator>,
+  React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Indicator>
+>((props, ref) => {
+  return (
+    <RadioGroupPrimitive.Indicator ref={ref} className="flex items-center justify-center" {...props}>
+      <div className="h-3 w-3 rounded-full bg-purple-500" />
+    </RadioGroupPrimitive.Indicator>
+  );
+});
+PurpleRadioGroupIndicator.displayName = 'PurpleRadioGroupIndicator';
+
+// Custom radio group indicator with icon
+const IconRadioGroupIndicator = React.forwardRef<
+  React.ComponentRef<typeof RadioGroupPrimitive.Indicator>,
+  React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Indicator>
+>((props, ref) => {
+  return (
+    <RadioGroupPrimitive.Indicator ref={ref} className="flex items-center justify-center" {...props}>
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        width="16"
+        height="16"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="3"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        className="text-purple-600"
+        aria-hidden="true"
+      >
+        <title>Checkmark</title>
+        <path d="M20 6 9 17l-5-5" />
+      </svg>
+    </RadioGroupPrimitive.Indicator>
+  );
+});
+IconRadioGroupIndicator.displayName = 'IconRadioGroupIndicator';
+
+// Custom form label component
+const PurpleLabel = React.forwardRef<HTMLLabelElement, React.ComponentPropsWithoutRef<typeof FormLabel>>(
+  ({ className, ...props }, ref) => <FormLabel ref={ref} className="text-purple-700 font-bold text-lg" {...props} />,
+);
+PurpleLabel.displayName = 'PurpleLabel';
+
+// Custom error message component
+const PurpleErrorMessage = React.forwardRef<HTMLParagraphElement, React.ComponentPropsWithoutRef<typeof FormMessage>>(
+  ({ className, ...props }, ref) => (
+    <FormMessage ref={ref} className="text-red-500 bg-red-50 p-2 rounded-md border border-red-200 mt-1" {...props} />
+  ),
+);
+PurpleErrorMessage.displayName = 'PurpleErrorMessage';
+
+// Card-style radio group item component
+const CardRadioGroupItem = React.forwardRef<
+  React.ComponentRef<typeof RadioGroupPrimitive.Item>,
+  React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Item>
+>((props, ref) => {
+  const { value, children, className, ...otherProps } = props;
+
+  return (
+    <RadioGroupPrimitive.Item
+      ref={ref}
+      value={value}
+      className={cn(
+        'relative w-full p-4 border-2 rounded-lg transition-all',
+        'data-[state=checked]:border-purple-500 data-[state=checked]:bg-purple-50',
+        'data-[state=unchecked]:border-gray-200',
+        'focus:outline-none focus-visible:ring-2 focus-visible:ring-purple-500 focus-visible:ring-offset-2',
+        className,
+      )}
+      {...otherProps}
+    >
+      <div className="flex items-center justify-between">
+        <div className="flex flex-col">{children}</div>
+        <div className="flex items-center justify-center h-5 w-5">
+          <RadioGroupPrimitive.Indicator>
+            <svg
+              xmlns="http://www.w3.org/2000/svg"
+              width="20"
+              height="20"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="3"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              className="text-purple-600"
+              aria-hidden="true"
+            >
+              <title>Selected</title>
+              <path d="M20 6 9 17l-5-5" />
+            </svg>
+          </RadioGroupPrimitive.Indicator>
+        </div>
+      </div>
+    </RadioGroupPrimitive.Item>
+  );
+});
+CardRadioGroupItem.displayName = 'CardRadioGroupItem';
+
+const CustomRadioGroupExample = () => {
+  const fetcher = useFetcher<{ message?: string; errors?: Record<string, { message: string }> }>();
+  const methods = useRemixForm<FormData>({
+    resolver: zodResolver(formSchema),
+    defaultValues: {
+      plan: undefined,
+      requiredPlan: undefined,
+    },
+    fetcher,
+    submitConfig: {
+      action: '/',
+      method: 'post',
+    },
+  });
+
+  return (
+    <RemixFormProvider {...methods}>
+      <Form onSubmit={methods.handleSubmit}>
+        <div className="space-y-8">
+          <div className="p-6 border rounded-lg">
+            <h3 className="text-lg font-medium mb-4">Custom Radio Group Container</h3>
+            <RadioGroup
+              name="plan"
+              label="Select a plan"
+              description="Choose the plan that best fits your needs."
+              className="space-y-2"
+              radioGroupClassName="flex flex-col space-y-4 border-2 border-purple-300 rounded-lg p-4 bg-purple-50"
+              components={{
+                FormLabel: PurpleLabel,
+                FormMessage: PurpleErrorMessage,
+              }}
+            >
+              <div className="flex items-center space-x-2">
+                <RadioGroupItem value="starter" id="starter-1" />
+                <label htmlFor="starter-1">Starter</label>
+              </div>
+              <div className="flex items-center space-x-2">
+                <RadioGroupItem value="pro" id="pro-1" />
+                <label htmlFor="pro-1">Pro</label>
+              </div>
+              <div className="flex items-center space-x-2">
+                <RadioGroupItem value="enterprise" id="enterprise-1" />
+                <label htmlFor="enterprise-1">Enterprise</label>
+              </div>
+            </RadioGroup>
+          </div>
+
+          <div className="p-6 border rounded-lg">
+            <h3 className="text-lg font-medium mb-4">Custom Radio Items</h3>
+            <RadioGroup
+              name="plan"
+              label="Select a plan"
+              description="Choose the plan that best fits your needs."
+              className="space-y-2"
+            >
+              <div className="flex items-center space-x-2">
+                <RadioGroupItem
+                  value="starter"
+                  id="starter-2"
+                  components={{
+                    RadioGroupItem: PurpleRadioGroupItem,
+                    RadioGroupIndicator: PurpleRadioGroupIndicator,
+                  }}
+                />
+                <label htmlFor="starter-2" className="text-purple-700">
+                  Starter
+                </label>
+              </div>
+              <div className="flex items-center space-x-2">
+                <RadioGroupItem
+                  value="pro"
+                  id="pro-2"
+                  components={{
+                    RadioGroupItem: PurpleRadioGroupItem,
+                    RadioGroupIndicator: PurpleRadioGroupIndicator,
+                  }}
+                />
+                <label htmlFor="pro-2" className="text-purple-700">
+                  Pro
+                </label>
+              </div>
+              <div className="flex items-center space-x-2">
+                <RadioGroupItem
+                  value="enterprise"
+                  id="enterprise-2"
+                  components={{
+                    RadioGroupItem: PurpleRadioGroupItem,
+                    RadioGroupIndicator: PurpleRadioGroupIndicator,
+                  }}
+                />
+                <label htmlFor="enterprise-2" className="text-purple-700">
+                  Enterprise
+                </label>
+              </div>
+            </RadioGroup>
+          </div>
+
+          <div className="p-6 border rounded-lg">
+            <h3 className="text-lg font-medium mb-4">Custom Radio Items with Icon</h3>
+            <RadioGroup
+              name="plan"
+              label="Select a plan"
+              description="Choose the plan that best fits your needs."
+              className="space-y-2"
+            >
+              <div className="flex items-center space-x-2">
+                <RadioGroupItem
+                  value="starter"
+                  id="starter-3"
+                  components={{
+                    RadioGroupItem: PurpleRadioGroupItem,
+                    RadioGroupIndicator: IconRadioGroupIndicator,
+                  }}
+                />
+                <label htmlFor="starter-3" className="text-purple-700">
+                  Starter
+                </label>
+              </div>
+              <div className="flex items-center space-x-2">
+                <RadioGroupItem
+                  value="pro"
+                  id="pro-3"
+                  components={{
+                    RadioGroupItem: PurpleRadioGroupItem,
+                    RadioGroupIndicator: IconRadioGroupIndicator,
+                  }}
+                />
+                <label htmlFor="pro-3" className="text-purple-700">
+                  Pro
+                </label>
+              </div>
+              <div className="flex items-center space-x-2">
+                <RadioGroupItem
+                  value="enterprise"
+                  id="enterprise-3"
+                  components={{
+                    RadioGroupItem: PurpleRadioGroupItem,
+                    RadioGroupIndicator: IconRadioGroupIndicator,
+                  }}
+                />
+                <label htmlFor="enterprise-3" className="text-purple-700">
+                  Enterprise
+                </label>
+              </div>
+            </RadioGroup>
+          </div>
+
+          <div className="p-6 border rounded-lg">
+            <h3 className="text-lg font-medium mb-4">Card-Style Radio Buttons</h3>
+            <RadioGroup
+              name="plan"
+              label="Select a plan"
+              description="Choose the plan that best fits your needs."
+              className="space-y-4"
+            >
+              <CardRadioGroupItem className="text-left" value="starter" id="starter-4">
+                <div className="font-medium">Starter</div>
+                <div className="text-sm text-gray-500">Perfect for beginners</div>
+              </CardRadioGroupItem>
+
+              <CardRadioGroupItem className="text-left" value="pro" id="pro-4">
+                <div className="font-medium">Pro</div>
+                <div className="text-sm text-gray-500">For professional users</div>
+              </CardRadioGroupItem>
+
+              <CardRadioGroupItem className="text-left" value="enterprise" id="enterprise-4">
+                <div className="font-medium">Enterprise</div>
+                <div className="text-sm text-gray-500">For large organizations</div>
+              </CardRadioGroupItem>
+            </RadioGroup>
+          </div>
+
+          <div className="p-6 border rounded-lg">
+            <h3 className="text-lg font-medium mb-4">Required Radio Group</h3>
+            <RadioGroup
+              name="requiredPlan"
+              label="Select a required plan"
+              description="This field is required."
+              className="space-y-2"
+              components={{
+                FormMessage: PurpleErrorMessage,
+              }}
+            >
+              <div className="flex items-center space-x-2">
+                <RadioGroupItem value="starter" id="starter-5" />
+                <label htmlFor="starter-5">Starter</label>
+              </div>
+              <div className="flex items-center space-x-2">
+                <RadioGroupItem value="pro" id="pro-5" />
+                <label htmlFor="pro-5">Pro</label>
+              </div>
+              <div className="flex items-center space-x-2">
+                <RadioGroupItem value="enterprise" id="enterprise-5" />
+                <label htmlFor="enterprise-5">Enterprise</label>
+              </div>
+            </RadioGroup>
+          </div>
+        </div>
+
+        <Button type="submit" className="mt-6 bg-purple-600 hover:bg-purple-700">
+          Submit
+        </Button>
+        {fetcher.data?.message && <p className="mt-2 text-green-600">{fetcher.data.message}</p>}
+      </Form>
+    </RemixFormProvider>
+  );
+};
+
+const handleFormSubmission = async (request: Request) => {
+  const {
+    errors,
+    data,
+    receivedValues: defaultValues,
+  } = await getValidatedFormData<FormData>(request, zodResolver(formSchema));
+
+  if (errors) {
+    return { errors, defaultValues };
+  }
+
+  return { message: 'Plan selected successfully' };
+};
+
+const meta: Meta<typeof RadioGroup> = {
+  title: 'RemixHookForm/CustomRadioGroup',
+  component: RadioGroup,
+  parameters: { layout: 'centered' },
+  tags: ['autodocs'],
+} satisfies Meta<typeof RadioGroup>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const CustomComponents: Story = {
+  render: () => <CustomRadioGroupExample />,
+  decorators: [
+    withRemixStubDecorator({
+      root: {
+        Component: CustomRadioGroupExample,
+        action: async ({ request }: ActionFunctionArgs) => handleFormSubmission(request),
+      },
+    }),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        story: 'Examples of different ways to customize radio group components.',
+      },
+      source: {
+        code: `
+import { RadioGroup } from '@lambdacurry/forms/remix-hook-form/radio-group';
+import { RadioGroupItem } from '@lambdacurry/forms/ui/radio-group';
+import * as RadioGroupPrimitive from '@radix-ui/react-radio-group';
+import * as React from 'react';
+import { cn } from '@lambdacurry/forms/ui/utils';
+
+/**
+ * Example 1: Custom Container Styling
+ * 
+ * You can customize the container by using the radioGroupClassName prop.
+ * This applies custom styles to the RadioGroup container without changing its behavior.
+ */
+<RadioGroup
+  name="plan"
+  label="Select a plan"
+  description="Choose the plan that best fits your needs."
+  className="space-y-2"
+  radioGroupClassName="flex flex-col space-y-4 border-2 border-purple-300 rounded-lg p-4 bg-purple-50"
+  components={{
+    FormLabel: PurpleLabel,
+    FormMessage: PurpleErrorMessage,
+  }}
+>
+  <div className="flex items-center space-x-2">
+    <RadioGroupItem value="starter" id="starter-1" />
+    <label htmlFor="starter-1">Starter</label>
+  </div>
+  {/* More radio items */}
+</RadioGroup>
+
+/**
+ * Example 2: Custom Radio Items
+ * 
+ * You can customize the radio items by passing custom components through
+ * the components prop of RadioGroupItem.
+ */
+<RadioGroup
+  name="plan"
+  label="Select a plan"
+  description="Choose the plan that best fits your needs."
+  className="space-y-2"
+>
+  <div className="flex items-center space-x-2">
+    <RadioGroupItem
+      value="starter"
+      id="starter-2"
+      components={{
+        RadioGroupItem: PurpleRadioGroupItem,
+        RadioGroupIndicator: PurpleRadioGroupIndicator,
+      }}
+    />
+    <label htmlFor="starter-2" className="text-purple-700">
+      Starter
+    </label>
+  </div>
+  {/* More radio items */}
+</RadioGroup>
+
+/**
+ * Example 3: Custom Radio Items with Icon
+ * 
+ * You can replace the default indicator with a custom icon.
+ * This example uses an SVG checkmark instead of the default circle.
+ */
+<RadioGroup
+  name="plan"
+  label="Select a plan"
+  description="Choose the plan that best fits your needs."
+  className="space-y-2"
+>
+  <div className="flex items-center space-x-2">
+    <RadioGroupItem
+      value="starter"
+      id="starter-3"
+      components={{
+        RadioGroupItem: PurpleRadioGroupItem,
+        RadioGroupIndicator: IconRadioGroupIndicator, // Custom SVG icon indicator
+      }}
+    />
+    <label htmlFor="starter-3" className="text-purple-700">
+      Starter
+    </label>
+  </div>
+  {/* More radio items */}
+</RadioGroup>
+
+/**
+ * Example 4: Card-Style Radio Buttons
+ * 
+ * You can completely transform the appearance of radio buttons
+ * by creating a custom component that uses RadioGroupPrimitive.Item.
+ * This example creates card-style radio buttons with rich content.
+ */
+
+// Card-style radio group item component
+const CardRadioGroupItem = React.forwardRef((props, ref) => {
+  const { value, children, className, ...otherProps } = props;
+  
+  return (
+    <RadioGroupPrimitive.Item
+      ref={ref}
+      value={value}
+      className={cn(
+        "relative w-full p-4 border-2 rounded-lg transition-all",
+        "data-[state=checked]:border-purple-500 data-[state=checked]:bg-purple-50",
+        "data-[state=unchecked]:border-gray-200",
+        "focus:outline-none focus-visible:ring-2 focus-visible:ring-purple-500 focus-visible:ring-offset-2",
+        className
+      )}
+      {...otherProps}
+    >
+      <div className="flex items-center justify-between">
+        <div className="flex flex-col">
+          {children}
+        </div>
+        <div className="flex items-center justify-center h-5 w-5">
+          <RadioGroupPrimitive.Indicator>
+            <svg
+              xmlns="http://www.w3.org/2000/svg"
+              width="20"
+              height="20"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="3"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              className="text-purple-600"
+              aria-hidden="true"
+            >
+              <title>Selected</title>
+              <path d="M20 6 9 17l-5-5" />
+            </svg>
+          </RadioGroupPrimitive.Indicator>
+        </div>
+      </div>
+    </RadioGroupPrimitive.Item>
+  );
+});
+
+// Usage with card-style radio buttons
+<RadioGroup
+  name="plan"
+  label="Select a plan"
+  description="Choose the plan that best fits your needs."
+  className="space-y-4"
+>
+  <CardRadioGroupItem value="starter" id="starter-4">
+    <div className="font-medium">Starter</div>
+    <div className="text-sm text-gray-500">Perfect for beginners</div>
+  </CardRadioGroupItem>
+  
+  <CardRadioGroupItem value="pro" id="pro-4">
+    <div className="font-medium">Pro</div>
+    <div className="text-sm text-gray-500">For professional users</div>
+  </CardRadioGroupItem>
+  
+  <CardRadioGroupItem value="enterprise" id="enterprise-4">
+    <div className="font-medium">Enterprise</div>
+    <div className="text-sm text-gray-500">For large organizations</div>
+  </CardRadioGroupItem>
+</RadioGroup>
+
+/**
+ * Example 5: Required Radio Group
+ * 
+ * You can create a required radio group by using Zod validation.
+ * This example shows how to display custom error messages when validation fails.
+ */
+<RadioGroup
+  name="requiredPlan" // This field is required in the Zod schema
+  label="Select a required plan"
+  description="This field is required."
+  className="space-y-2"
+  components={{
+    FormMessage: PurpleErrorMessage, // Custom error message styling
+  }}
+>
+  <div className="flex items-center space-x-2">
+    <RadioGroupItem value="starter" id="starter-5" />
+    <label htmlFor="starter-5">Starter</label>
+  </div>
+  {/* More radio items */}
+</RadioGroup>
+
+// Zod schema with required field
+const formSchema = z.object({
+  plan: z.enum(['starter', 'pro', 'enterprise'], {
+    required_error: 'You need to select a plan',
+  }),
+  requiredPlan: z.enum(['starter', 'pro', 'enterprise'], {
+    required_error: 'This field is required',
+  }),
+});`,
+      },
+    },
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    // Test 1: Verify custom label is rendered with purple styling
+    const customLabel = canvas.getAllByText('Select a plan')[0];
+    expect(customLabel).toHaveClass('text-purple-700');
+    expect(customLabel).toHaveClass('font-bold');
+
+    // Test 2: Verify card-style radio buttons work
+    const cardStyleContainer = canvas.getByText('Card-Style Radio Buttons').closest('div');
+    if (!cardStyleContainer) {
+      throw new Error('Could not find card-style container');
+    }
+
+    // Find and click the Enterprise card option
+    const enterpriseCard = within(cardStyleContainer as HTMLElement)
+      .getByText('Enterprise')
+      .closest('button');
+    if (!enterpriseCard) {
+      throw new Error('Could not find Enterprise card option');
+    }
+
+    await userEvent.click(enterpriseCard);
+    expect(enterpriseCard).toHaveAttribute('data-state', 'checked');
+
+    // Test 3: Verify required field validation
+    const submitButton = canvas.getByRole('button', { name: 'Submit' });
+    await userEvent.click(submitButton);
+
+    // Should show error message for required field
+    const errorMessage = await canvas.findByText('This field is required');
+    expect(errorMessage).toBeInTheDocument();
+
+    // Test 4: Select an option in the required field and submit
+    const requiredContainer = canvas.getByText('Required Radio Group').closest('div');
+    if (!requiredContainer) {
+      throw new Error('Could not find required radio group container');
+    }
+
+    const proOption = within(requiredContainer as HTMLElement).getByLabelText('Pro');
+    await userEvent.click(proOption);
+
+    // Submit the form again
+    await userEvent.click(submitButton);
+
+    // Wait for success message
+    const successMessage = await canvas.findByText('Plan selected successfully');
+    expect(successMessage).toBeInTheDocument();
+  },
+};
diff --git a/apps/docs/src/remix-hook-form/radio-group.stories.tsx b/apps/docs/src/remix-hook-form/radio-group.stories.tsx
index 249828be..7f4a904f 100644
--- a/apps/docs/src/remix-hook-form/radio-group.stories.tsx
+++ b/apps/docs/src/remix-hook-form/radio-group.stories.tsx
@@ -121,4 +121,4 @@ export const Tests: Story = {
     await testRadioGroupSelection(storyContext);
     await testSubmission(storyContext);
   },
-};
\ No newline at end of file
+};
diff --git a/packages/components/src/remix-hook-form/radio-group.tsx b/packages/components/src/remix-hook-form/radio-group.tsx
index 9bb5db88..757b5c8d 100644
--- a/packages/components/src/remix-hook-form/radio-group.tsx
+++ b/packages/components/src/remix-hook-form/radio-group.tsx
@@ -1,10 +1,23 @@
 import { useRemixFormContext } from 'remix-hook-form';
-import { RadioGroupField as BaseRadioGroupField, type RadioGroupFieldProps as BaseRadioGroupFieldProps } from '../ui/radio-group-field';
+import { FormControl, FormDescription, FormLabel, FormMessage } from '../ui/form';
+import {
+  RadioGroupField as BaseRadioGroupField,
+  type RadioGroupFieldProps as BaseRadioGroupFieldProps,
+  type RadioGroupFieldComponents,
+} from '../ui/radio-group-field';
 
 export type RadioGroupFieldProps = Omit<BaseRadioGroupFieldProps, 'control'>;
 
 export function RadioGroup(props: RadioGroupFieldProps) {
   const { control } = useRemixFormContext();
 
-  return <BaseRadioGroupField control={control} {...props} />;
+  const components: Partial<RadioGroupFieldComponents> = {
+    FormControl,
+    FormDescription,
+    FormLabel,
+    FormMessage,
+    ...props.components,
+  };
+
+  return <BaseRadioGroupField control={control} {...props} components={components} />;
 }
diff --git a/packages/components/src/ui/radio-group-field.tsx b/packages/components/src/ui/radio-group-field.tsx
index 5ab16b73..c83e5ce1 100644
--- a/packages/components/src/ui/radio-group-field.tsx
+++ b/packages/components/src/ui/radio-group-field.tsx
@@ -1,4 +1,4 @@
-// biome-ignore lint/style/noNamespaceImport: prevents React undefined errors when exporting as a component library
+import type * as RadioGroupPrimitive from '@radix-ui/react-radio-group';
 import * as React from 'react';
 import type { Control, FieldPath, FieldValues } from 'react-hook-form';
 import {
@@ -11,6 +11,11 @@ import {
   FormMessage,
 } from './form';
 import { RadioGroup } from './radio-group';
+import { cn } from './utils';
+
+export interface RadioGroupFieldComponents extends FieldComponents {
+  RadioGroup?: React.ComponentType<React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Root>>;
+}
 
 export interface RadioGroupFieldProps<
   TFieldValues extends FieldValues = FieldValues,
@@ -20,11 +25,15 @@ export interface RadioGroupFieldProps<
   name: TName;
   label?: string;
   description?: string;
-  components?: Partial<FieldComponents>;
+  components?: Partial<RadioGroupFieldComponents>;
+  radioGroupClassName?: string;
 }
 
 const RadioGroupField = React.forwardRef<HTMLDivElement, RadioGroupFieldProps>(
-  ({ control, name, label, description, className, components, ...props }, ref) => {
+  ({ control, name, label, description, className, radioGroupClassName, components, children, ...props }, ref) => {
+    // Extract custom components with fallbacks
+    const RadioGroupComponent = components?.RadioGroup || RadioGroup;
+
     return (
       <FormField
         control={control}
@@ -33,7 +42,15 @@ const RadioGroupField = React.forwardRef<HTMLDivElement, RadioGroupFieldProps>(
           <FormItem className={className} ref={ref}>
             {label && <FormLabel Component={components?.FormLabel}>{label}</FormLabel>}
             <FormControl Component={components?.FormControl}>
-              <RadioGroup ref={field.ref} onValueChange={field.onChange} defaultValue={field.value} {...props} />
+              <RadioGroupComponent
+                ref={field.ref}
+                onValueChange={field.onChange}
+                defaultValue={field.value}
+                className={cn('grid gap-2', radioGroupClassName)}
+                {...props}
+              >
+                {children}
+              </RadioGroupComponent>
             </FormControl>
             {description && <FormDescription Component={components?.FormDescription}>{description}</FormDescription>}
             {fieldState.error && (
diff --git a/packages/components/src/ui/radio-group.tsx b/packages/components/src/ui/radio-group.tsx
index 1bd482c9..d34ef548 100644
--- a/packages/components/src/ui/radio-group.tsx
+++ b/packages/components/src/ui/radio-group.tsx
@@ -1,10 +1,17 @@
-// biome-ignore lint/style/noNamespaceImport: from Radix
 import * as RadioGroupPrimitive from '@radix-ui/react-radio-group';
 import { Circle } from 'lucide-react';
-// biome-ignore lint/style/noNamespaceImport: prevents React undefined errors when exporting as a component library
 import * as React from 'react';
 import { cn } from './utils';
 
+export interface RadioGroupItemComponents {
+  RadioGroupItem?: React.ComponentType<
+    React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Item> & {
+      indicator?: React.ReactNode;
+    }
+  >;
+  RadioGroupIndicator?: React.ComponentType<React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Indicator>>;
+}
+
 const RadioGroup = React.forwardRef<
   React.ElementRef<typeof RadioGroupPrimitive.Root>,
   React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Root>
@@ -17,10 +24,18 @@ const RadioGroupItem = React.forwardRef<
   React.ElementRef<typeof RadioGroupPrimitive.Item>,
   React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Item> & {
     indicator?: React.ReactNode;
+    components?: Partial<RadioGroupItemComponents>;
   }
->(({ className, indicator, ...props }, ref) => {
+>(({ className, indicator, components, ...props }, ref) => {
+  // Extract custom components with fallbacks
+  const RadioItem = components?.RadioGroupItem || RadioGroupPrimitive.Item;
+  const RadioIndicator = components?.RadioGroupIndicator || RadioGroupPrimitive.Indicator;
+
+  // Determine the indicator content
+  const indicatorContent = indicator || <Circle className="h-2.5 w-2.5 fill-current text-current" />;
+
   return (
-    <RadioGroupPrimitive.Item
+    <RadioItem
       ref={ref}
       className={cn(
         'aspect-square h-4 w-4 rounded-full border border-primary text-primary ring-offset-background focus:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50',
@@ -28,10 +43,8 @@ const RadioGroupItem = React.forwardRef<
       )}
       {...props}
     >
-      <RadioGroupPrimitive.Indicator className="flex items-center justify-center">
-        {indicator || <Circle className="h-2.5 w-2.5 fill-current text-current" />}
-      </RadioGroupPrimitive.Indicator>
-    </RadioGroupPrimitive.Item>
+      <RadioIndicator className="flex items-center justify-center">{indicatorContent}</RadioIndicator>
+    </RadioItem>
   );
 });
 RadioGroupItem.displayName = RadioGroupPrimitive.Item.displayName;

From bf932a1915e96e6b4f54c5608479a5b9121a10ec Mon Sep 17 00:00:00 2001
From: Jake Ruesink <jaruesink@gmail.com>
Date: Sat, 15 Mar 2025 00:13:20 -0500
Subject: [PATCH 04/13] feat: enhance radio group and checkbox components with
 new props and examples

- Added `radioGroupClassName` prop to `RadioGroupFieldProps` for custom container styling.
- Expanded documentation with implementation examples for various customization approaches in radio groups.
- Updated Storybook titles for better readability and consistency.
- Removed deprecated custom checkbox and radio group stories to streamline examples.
---
 ai/CustomInputsProject.md                     | 128 +++++++++++++++++-
 ...tories.tsx => checkbox-custom.stories.tsx} |   2 +-
 .../remix-hook-form/checkbox-list.stories.tsx |   2 +-
 .../remix-hook-form/date-picker.stories.tsx   |   4 +-
 ...ies.tsx => radio-group-custom.stories.tsx} |   2 +-
 .../remix-hook-form/radio-group.stories.tsx   |   2 +-
 6 files changed, 133 insertions(+), 7 deletions(-)
 rename apps/docs/src/remix-hook-form/{custom-checkbox.stories.tsx => checkbox-custom.stories.tsx} (99%)
 rename apps/docs/src/remix-hook-form/{custom-radio-group.stories.tsx => radio-group-custom.stories.tsx} (99%)

diff --git a/ai/CustomInputsProject.md b/ai/CustomInputsProject.md
index cd694458..585e684a 100644
--- a/ai/CustomInputsProject.md
+++ b/ai/CustomInputsProject.md
@@ -223,6 +223,132 @@ export interface RadioGroupFieldComponents extends FieldComponents {
   RadioGroupItem?: React.ComponentType<React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Item>>;
   RadioGroupIndicator?: React.ComponentType<React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Indicator>>;
 }
+
+// Props interface should include radioGroupClassName for styling the container
+export interface RadioGroupFieldProps<
+  TFieldValues extends FieldValues = FieldValues,
+  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+> extends Omit<React.ComponentPropsWithoutRef<typeof RadioGroup>, 'onValueChange'> {
+  control?: Control<TFieldValues>;
+  name: TName;
+  label?: string;
+  description?: string;
+  components?: Partial<RadioGroupFieldComponents>;
+  radioGroupClassName?: string; // Added prop for styling the RadioGroup container
+}
+```
+
+#### RadioGroup Implementation Examples
+
+Our implementation supports several customization approaches:
+
+1. **Container Styling**: Use the `radioGroupClassName` prop to style the RadioGroup container without changing its behavior.
+
+```tsx
+<RadioGroup
+  name="plan"
+  label="Select a plan"
+  description="Choose the plan that best fits your needs."
+  className="space-y-2"
+  radioGroupClassName="flex flex-col space-y-4 border-2 border-purple-300 rounded-lg p-4 bg-purple-50"
+  components={{
+    FormLabel: PurpleLabel,
+    FormMessage: PurpleErrorMessage,
+  }}
+>
+  {/* Radio items */}
+</RadioGroup>
+```
+
+2. **Custom Radio Items**: Customize individual radio items by passing custom components through the `components` prop of `RadioGroupItem`.
+
+```tsx
+<RadioGroupItem
+  value="starter"
+  id="starter"
+  components={{
+    RadioGroupItem: PurpleRadioGroupItem,
+    RadioGroupIndicator: PurpleRadioGroupIndicator,
+  }}
+/>
+```
+
+3. **Custom Icons**: Replace the default indicator with a custom SVG icon.
+
+```tsx
+<RadioGroupItem
+  value="starter"
+  id="starter"
+  components={{
+    RadioGroupItem: PurpleRadioGroupItem,
+    RadioGroupIndicator: IconRadioGroupIndicator, // Custom SVG icon indicator
+  }}
+/>
+```
+
+4. **Card-Style Radio Buttons**: Completely transform the appearance of radio buttons by creating a custom component that uses `RadioGroupPrimitive.Item`.
+
+```tsx
+// Card-style radio group item component
+const CardRadioGroupItem = React.forwardRef((props, ref) => {
+  const { value, children, className, ...otherProps } = props;
+  
+  return (
+    <RadioGroupPrimitive.Item
+      ref={ref}
+      value={value}
+      className={cn(
+        "relative w-full p-4 border-2 rounded-lg transition-all",
+        "data-[state=checked]:border-purple-500 data-[state=checked]:bg-purple-50",
+        "data-[state=unchecked]:border-gray-200",
+        "focus:outline-none focus-visible:ring-2 focus-visible:ring-purple-500 focus-visible:ring-offset-2",
+        className
+      )}
+      {...otherProps}
+    >
+      <div className="flex items-center justify-between">
+        <div className="flex flex-col">
+          {children}
+        </div>
+        <div className="flex items-center justify-center h-5 w-5">
+          <RadioGroupPrimitive.Indicator>
+            <svg
+              xmlns="http://www.w3.org/2000/svg"
+              width="20"
+              height="20"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="3"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              className="text-purple-600"
+              aria-hidden="true"
+            >
+              <title>Selected</title>
+              <path d="M20 6 9 17l-5-5" />
+            </svg>
+          </RadioGroupPrimitive.Indicator>
+        </div>
+      </div>
+    </RadioGroupPrimitive.Item>
+  );
+});
+
+// Usage with card-style radio buttons
+<RadioGroup
+  name="plan"
+  label="Select a plan"
+  description="Choose the plan that best fits your needs."
+  className="space-y-4"
+>
+  <CardRadioGroupItem value="starter" id="starter">
+    <div className="font-medium">Starter</div>
+    <div className="text-sm text-gray-500">Perfect for beginners</div>
+  </CardRadioGroupItem>
+  
+  {/* More card items */}
+</RadioGroup>
 ```
 
 ### 5. Switch
@@ -800,7 +926,7 @@ play: async ({ canvasElement }) => {
 4. **Composition**: Components can be overridden individually or as groups
 5. **Accessibility**: Custom components maintain proper ARIA attributes and keyboard navigation
 
-This approach provides a flexible and consistent way for users to customize any part of our form components while maintaining a clean API and ensuring accessibility.
+This approach provides a flexible and consistent way for users to customize any part of our form components while maintaining a clean API.
 
 ## Conclusion
 
diff --git a/apps/docs/src/remix-hook-form/custom-checkbox.stories.tsx b/apps/docs/src/remix-hook-form/checkbox-custom.stories.tsx
similarity index 99%
rename from apps/docs/src/remix-hook-form/custom-checkbox.stories.tsx
rename to apps/docs/src/remix-hook-form/checkbox-custom.stories.tsx
index 66032077..cd5fec2e 100644
--- a/apps/docs/src/remix-hook-form/custom-checkbox.stories.tsx
+++ b/apps/docs/src/remix-hook-form/checkbox-custom.stories.tsx
@@ -225,7 +225,7 @@ const handleFormSubmission = async (request: Request) => {
 };
 
 const meta: Meta<typeof Checkbox> = {
-  title: 'RemixHookForm/CustomCheckbox',
+  title: 'RemixHookForm/Checkbox Customized',
   component: Checkbox,
   parameters: { layout: 'centered' },
   tags: ['autodocs'],
diff --git a/apps/docs/src/remix-hook-form/checkbox-list.stories.tsx b/apps/docs/src/remix-hook-form/checkbox-list.stories.tsx
index 3d283113..b5e91f8b 100644
--- a/apps/docs/src/remix-hook-form/checkbox-list.stories.tsx
+++ b/apps/docs/src/remix-hook-form/checkbox-list.stories.tsx
@@ -125,7 +125,7 @@ const handleFormSubmission = async (request: Request) => {
 };
 
 const meta: Meta<typeof Checkbox> = {
-  title: 'RemixHookForm/CheckboxList',
+  title: 'RemixHookForm/Checkbox List',
   component: Checkbox,
   parameters: { layout: 'centered' },
   tags: ['autodocs'],
diff --git a/apps/docs/src/remix-hook-form/date-picker.stories.tsx b/apps/docs/src/remix-hook-form/date-picker.stories.tsx
index 4d81e456..09a535dd 100644
--- a/apps/docs/src/remix-hook-form/date-picker.stories.tsx
+++ b/apps/docs/src/remix-hook-form/date-picker.stories.tsx
@@ -58,7 +58,7 @@ const handleFormSubmission = async (request: Request) => {
 
 // Storybook configuration
 const meta: Meta<typeof DatePicker> = {
-  title: 'RemixHookForm/DatePicker',
+  title: 'RemixHookForm/Date Picker',
   component: DatePicker,
   parameters: { layout: 'centered' },
   tags: ['autodocs'],
@@ -119,4 +119,4 @@ export const Tests: Story = {
     await testDateSelection(storyContext);
     await testSubmission(storyContext);
   },
-};
\ No newline at end of file
+};
diff --git a/apps/docs/src/remix-hook-form/custom-radio-group.stories.tsx b/apps/docs/src/remix-hook-form/radio-group-custom.stories.tsx
similarity index 99%
rename from apps/docs/src/remix-hook-form/custom-radio-group.stories.tsx
rename to apps/docs/src/remix-hook-form/radio-group-custom.stories.tsx
index aa16cca3..8588485e 100644
--- a/apps/docs/src/remix-hook-form/custom-radio-group.stories.tsx
+++ b/apps/docs/src/remix-hook-form/radio-group-custom.stories.tsx
@@ -385,7 +385,7 @@ const handleFormSubmission = async (request: Request) => {
 };
 
 const meta: Meta<typeof RadioGroup> = {
-  title: 'RemixHookForm/CustomRadioGroup',
+  title: 'RemixHookForm/Radio Group Customized',
   component: RadioGroup,
   parameters: { layout: 'centered' },
   tags: ['autodocs'],
diff --git a/apps/docs/src/remix-hook-form/radio-group.stories.tsx b/apps/docs/src/remix-hook-form/radio-group.stories.tsx
index 7f4a904f..84c412a8 100644
--- a/apps/docs/src/remix-hook-form/radio-group.stories.tsx
+++ b/apps/docs/src/remix-hook-form/radio-group.stories.tsx
@@ -78,7 +78,7 @@ const handleFormSubmission = async (request: Request) => {
 };
 
 const meta: Meta<typeof RadioGroup> = {
-  title: 'RemixHookForm/RadioGroup',
+  title: 'RemixHookForm/Radio Group',
   component: RadioGroup,
   parameters: { layout: 'centered' },
   tags: ['autodocs'],

From 5e766e1c6e914e26a1507321193f285c2f999352 Mon Sep 17 00:00:00 2001
From: Jake Ruesink <jaruesink@gmail.com>
Date: Sat, 15 Mar 2025 00:40:42 -0500
Subject: [PATCH 05/13] feat: enhance Switch component with customizable
 components and improved structure

- Updated Switch component to accept custom components for enhanced flexibility.
- Introduced default styled Switch and Switch Thumb components for consistent styling.
- Refactored SwitchField to utilize new component structure, improving maintainability.
- Ensured proper integration with Remix form context for better form handling.
---
 .../remix-hook-form/switch-custom.stories.tsx | 361 ++++++++++++++++++
 .../components/src/remix-hook-form/switch.tsx |  18 +-
 packages/components/src/ui/switch-field.tsx   |  95 +++--
 3 files changed, 442 insertions(+), 32 deletions(-)
 create mode 100644 apps/docs/src/remix-hook-form/switch-custom.stories.tsx

diff --git a/apps/docs/src/remix-hook-form/switch-custom.stories.tsx b/apps/docs/src/remix-hook-form/switch-custom.stories.tsx
new file mode 100644
index 00000000..8d6d42fa
--- /dev/null
+++ b/apps/docs/src/remix-hook-form/switch-custom.stories.tsx
@@ -0,0 +1,361 @@
+import { zodResolver } from '@hookform/resolvers/zod';
+import { Switch } from '@lambdacurry/forms/remix-hook-form/switch';
+import { Button } from '@lambdacurry/forms/ui/button';
+import { FormLabel, FormMessage } from '@lambdacurry/forms/ui/form';
+import * as SwitchPrimitives from '@radix-ui/react-switch';
+import type { ActionFunctionArgs } from '@remix-run/node';
+import { useFetcher } from '@remix-run/react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { expect, userEvent, within } from '@storybook/test';
+import * as React from 'react';
+import { RemixFormProvider, getValidatedFormData, useRemixForm } from 'remix-hook-form';
+import { z } from 'zod';
+import { withRemixStubDecorator } from '../lib/storybook/remix-stub';
+
+const formSchema = z.object({
+  notifications: z.boolean().default(false),
+  darkMode: z.boolean().default(false),
+  premium: z.boolean().default(false),
+});
+
+type FormData = z.infer<typeof formSchema>;
+
+// Custom Switch component
+const PurpleSwitch = React.forwardRef<
+  React.ComponentRef<typeof SwitchPrimitives.Root>,
+  React.ComponentPropsWithoutRef<typeof SwitchPrimitives.Root>
+>((props, ref) => (
+  <SwitchPrimitives.Root
+    ref={ref}
+    {...props}
+    className="peer inline-flex h-8 w-16 shrink-0 cursor-pointer items-center rounded-full border-2 border-purple-300 bg-purple-100 transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-purple-500 focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:bg-purple-600 data-[state=unchecked]:bg-purple-200"
+  >
+    {props.children}
+  </SwitchPrimitives.Root>
+));
+PurpleSwitch.displayName = 'PurpleSwitch';
+
+// Custom Switch Thumb component
+const PurpleSwitchThumb = React.forwardRef<
+  React.ComponentRef<typeof SwitchPrimitives.Thumb>,
+  React.ComponentPropsWithoutRef<typeof SwitchPrimitives.Thumb>
+>((props, ref) => (
+  <SwitchPrimitives.Thumb
+    ref={ref}
+    {...props}
+    className="pointer-events-none flex h-7 w-7 items-center justify-center rounded-full bg-white shadow-lg ring-0 transition-transform data-[state=checked]:translate-x-8 data-[state=unchecked]:translate-x-0 relative overflow-hidden data-[state=checked]:[--on-opacity:1] data-[state=checked]:[--off-opacity:0] data-[state=unchecked]:[--on-opacity:0] data-[state=unchecked]:[--off-opacity:1]"
+  >
+    <span className="absolute inset-0 opacity-[var(--on-opacity)] flex items-center justify-center text-xs font-bold text-purple-600 transition-opacity duration-200 z-10">
+      ON
+    </span>
+    <span className="absolute inset-0 opacity-[var(--off-opacity)] flex items-center justify-center text-xs font-bold text-purple-600 transition-opacity duration-200 z-10">
+      OFF
+    </span>
+  </SwitchPrimitives.Thumb>
+));
+PurpleSwitchThumb.displayName = 'PurpleSwitchThumb';
+
+// Custom Form Label component
+const PurpleLabel = React.forwardRef<HTMLLabelElement, React.ComponentPropsWithoutRef<typeof FormLabel>>(
+  ({ className, ...props }, ref) => <FormLabel ref={ref} className="text-lg font-bold text-purple-700" {...props} />,
+);
+PurpleLabel.displayName = 'PurpleLabel';
+
+// Custom Form Message component
+const PurpleMessage = React.forwardRef<HTMLParagraphElement, React.ComponentPropsWithoutRef<typeof FormMessage>>(
+  ({ className, ...props }, ref) => (
+    <FormMessage ref={ref} className="text-purple-500 bg-purple-50 p-2 rounded-md mt-1" {...props} />
+  ),
+);
+PurpleMessage.displayName = 'PurpleMessage';
+
+// Green Switch component
+const GreenSwitch = React.forwardRef<
+  React.ComponentRef<typeof SwitchPrimitives.Root>,
+  React.ComponentPropsWithoutRef<typeof SwitchPrimitives.Root>
+>((props, ref) => (
+  <SwitchPrimitives.Root
+    ref={ref}
+    {...props}
+    className="peer inline-flex h-7 w-14 shrink-0 cursor-pointer items-center rounded-full border-2 border-green-300 transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-green-500 focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:bg-green-600 data-[state=unchecked]:bg-white"
+  >
+    {props.children}
+  </SwitchPrimitives.Root>
+));
+GreenSwitch.displayName = 'GreenSwitch';
+
+// Green Switch Thumb component
+const GreenSwitchThumb = React.forwardRef<
+  React.ComponentRef<typeof SwitchPrimitives.Thumb>,
+  React.ComponentPropsWithoutRef<typeof SwitchPrimitives.Thumb>
+>((props, ref) => (
+  <SwitchPrimitives.Thumb
+    ref={ref}
+    {...props}
+    className="pointer-events-none flex h-6 w-6 items-center justify-center rounded-full bg-green-100 shadow-lg ring-0 transition-transform data-[state=checked]:translate-x-7 data-[state=unchecked]:translate-x-0 data-[state=checked]:bg-white"
+  >
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      className="h-4 w-4 text-green-600 data-[state=checked]:opacity-100 data-[state=unchecked]:opacity-0"
+      fill="none"
+      viewBox="0 0 24 24"
+      stroke="currentColor"
+    >
+      <title>Check mark</title>
+      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M5 13l4 4L19 7" />
+    </svg>
+  </SwitchPrimitives.Thumb>
+));
+GreenSwitchThumb.displayName = 'GreenSwitchThumb';
+
+const CustomSwitchExample = () => {
+  const fetcher = useFetcher<{ message: string }>();
+  const methods = useRemixForm<FormData>({
+    resolver: zodResolver(formSchema),
+    defaultValues: {
+      notifications: false,
+      darkMode: false,
+      premium: false,
+    },
+    fetcher,
+    submitConfig: {
+      action: '/',
+      method: 'post',
+    },
+  });
+
+  return (
+    <RemixFormProvider {...methods}>
+      <fetcher.Form onSubmit={methods.handleSubmit}>
+        <div className="grid gap-4">
+          {/* Default Switch */}
+          <Switch
+            name="notifications"
+            label="Enable notifications"
+            description="Receive notifications for important updates"
+          />
+
+          {/* Custom Switch with purple styling */}
+          <Switch
+            name="darkMode"
+            label="Dark mode"
+            description="Toggle dark mode for the application"
+            components={{
+              Switch: PurpleSwitch,
+              SwitchThumb: PurpleSwitchThumb,
+            }}
+          />
+
+          {/* Custom Switch with green styling and custom form components */}
+          <Switch
+            name="premium"
+            label="Premium features"
+            description="Enable premium features for your account"
+            components={{
+              FormLabel: PurpleLabel,
+              FormMessage: PurpleMessage,
+              Switch: GreenSwitch,
+              SwitchThumb: GreenSwitchThumb,
+            }}
+          />
+        </div>
+        <Button type="submit" className="mt-4">
+          Submit
+        </Button>
+        {fetcher.data?.message && <p className="mt-2 text-green-600">{fetcher.data.message}</p>}
+      </fetcher.Form>
+    </RemixFormProvider>
+  );
+};
+
+const handleFormSubmission = async (request: Request) => {
+  const { errors } = await getValidatedFormData<FormData>(request, zodResolver(formSchema));
+
+  if (errors) {
+    return { errors };
+  }
+
+  return { message: 'Settings updated successfully' };
+};
+
+const meta: Meta<typeof Switch> = {
+  title: 'RemixHookForm/Switch Customized',
+  component: Switch,
+  parameters: { layout: 'centered' },
+  tags: ['autodocs'],
+  decorators: [
+    withRemixStubDecorator({
+      root: {
+        Component: CustomSwitchExample,
+        action: async ({ request }: ActionFunctionArgs) => handleFormSubmission(request),
+      },
+    }),
+  ],
+} satisfies Meta<typeof Switch>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const CustomComponents: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: `
+### Switch Component Customization
+
+This example demonstrates three different approaches to customizing the Switch component:
+
+1. **Default Styling**: The first switch uses the default styling with no customization needed.
+
+2. **Custom Switch Elements**: The second switch customizes only the Switch and SwitchThumb components with purple styling and ON/OFF text indicators.
+\`\`\`tsx
+<Switch
+  name="darkMode"
+  label="Dark mode"
+  description="Toggle dark mode for the application"
+  components={{
+    Switch: PurpleSwitch,
+    SwitchThumb: PurpleSwitchThumb,
+  }}
+/>
+\`\`\`
+
+3. **Fully Customized**: The third switch demonstrates comprehensive customization of all components, including form elements and a green switch with a checkmark icon.
+\`\`\`tsx
+<Switch
+  name="premium"
+  label="Premium features"
+  description="Enable premium features for your account"
+  components={{
+    FormLabel: PurpleLabel,
+    FormMessage: PurpleMessage,
+    Switch: GreenSwitch,
+    SwitchThumb: GreenSwitchThumb,
+  }}
+/>
+\`\`\`
+
+The \`components\` prop allows you to override any of the internal components used by the Switch component, giving you complete control over the styling and behavior.
+`,
+      },
+      source: {
+        code: `
+// APPROACH 1: Default Switch (no customization needed)
+<Switch
+  name="notifications"
+  label="Enable notifications"
+  description="Receive notifications for important updates"
+/>
+
+// APPROACH 2: Custom Switch with purple styling and ON/OFF text
+const PurpleSwitch = React.forwardRef((props, ref) => (
+  <SwitchPrimitives.Root
+    ref={ref}
+    {...props}
+    className="peer inline-flex h-8 w-16 shrink-0 cursor-pointer items-center rounded-full border-2 border-purple-300 bg-purple-100 transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-purple-500 focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:bg-purple-600 data-[state=unchecked]:bg-purple-200"
+  >
+    {props.children}
+  </SwitchPrimitives.Root>
+));
+
+const PurpleSwitchThumb = React.forwardRef((props, ref) => (
+  <SwitchPrimitives.Thumb
+    ref={ref}
+    {...props}
+    className="pointer-events-none flex h-7 w-7 items-center justify-center rounded-full bg-white shadow-lg ring-0 transition-transform data-[state=checked]:translate-x-8 data-[state=unchecked]:translate-x-0 relative overflow-hidden data-[state=checked]:[--on-opacity:1] data-[state=checked]:[--off-opacity:0] data-[state=unchecked]:[--on-opacity:0] data-[state=unchecked]:[--off-opacity:1]"
+  >
+    <span className="absolute inset-0 opacity-[var(--on-opacity)] flex items-center justify-center text-xs font-bold text-purple-600 transition-opacity duration-200 z-10">
+      ON
+    </span>
+    <span className="absolute inset-0 opacity-[var(--off-opacity)] flex items-center justify-center text-xs font-bold text-purple-600 transition-opacity duration-200 z-10">
+      OFF
+    </span>
+  </SwitchPrimitives.Thumb>
+));
+
+<Switch 
+  name="darkMode" 
+  label="Dark mode" 
+  description="Toggle dark mode for the application"
+  components={{
+    Switch: PurpleSwitch,
+    SwitchThumb: PurpleSwitchThumb,
+  }}
+/>
+
+// APPROACH 3: Fully customized switch with green styling, checkmark icon, and custom form components
+const GreenSwitch = React.forwardRef((props, ref) => (
+  <SwitchPrimitives.Root
+    ref={ref}
+    {...props}
+    className="peer inline-flex h-7 w-14 shrink-0 cursor-pointer items-center rounded-full border-2 border-green-300 transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-green-500 focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:bg-green-600 data-[state=unchecked]:bg-white"
+  >
+    {props.children}
+  </SwitchPrimitives.Root>
+));
+
+const GreenSwitchThumb = React.forwardRef((props, ref) => (
+  <SwitchPrimitives.Thumb
+    ref={ref}
+    {...props}
+    className="pointer-events-none flex h-6 w-6 items-center justify-center rounded-full bg-green-100 shadow-lg ring-0 transition-transform data-[state=checked]:translate-x-7 data-[state=unchecked]:translate-x-0 data-[state=checked]:bg-white"
+  >
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      className="h-4 w-4 text-green-600 data-[state=checked]:opacity-100 data-[state=unchecked]:opacity-0"
+      fill="none"
+      viewBox="0 0 24 24"
+      stroke="currentColor"
+    >
+      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M5 13l4 4L19 7" />
+    </svg>
+  </SwitchPrimitives.Thumb>
+));
+
+const PurpleLabel = React.forwardRef((props, ref) => (
+  <FormLabel ref={ref} className="text-lg font-bold text-purple-700" {...props} />
+));
+
+const PurpleMessage = React.forwardRef((props, ref) => (
+  <FormMessage ref={ref} className="text-purple-500 bg-purple-50 p-2 rounded-md mt-1" {...props} />
+));
+
+<Switch
+  name="premium"
+  label="Premium features"
+  description="Enable premium features for your account"
+  components={{
+    FormLabel: PurpleLabel,
+    FormMessage: PurpleMessage,
+    Switch: GreenSwitch,
+    SwitchThumb: GreenSwitchThumb,
+  }}
+/>`,
+      },
+    },
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    // Find all switches
+    const switches = canvas.getAllByRole('switch');
+    expect(switches.length).toBe(3);
+
+    // Toggle the custom switches
+    const darkModeSwitch = canvas.getByLabelText('Dark mode');
+    const premiumSwitch = canvas.getByLabelText('Premium features');
+
+    await userEvent.click(darkModeSwitch);
+    await userEvent.click(premiumSwitch);
+
+    expect(darkModeSwitch).toBeChecked();
+    expect(premiumSwitch).toBeChecked();
+
+    // Submit the form
+    const submitButton = canvas.getByRole('button', { name: 'Submit' });
+    await userEvent.click(submitButton);
+
+    // Verify successful submission
+    await expect(await canvas.findByText('Settings updated successfully')).toBeInTheDocument();
+  },
+};
diff --git a/packages/components/src/remix-hook-form/switch.tsx b/packages/components/src/remix-hook-form/switch.tsx
index d03dadef..82fcb1c0 100644
--- a/packages/components/src/remix-hook-form/switch.tsx
+++ b/packages/components/src/remix-hook-form/switch.tsx
@@ -1,6 +1,6 @@
 import type * as React from 'react';
 import { useRemixFormContext } from 'remix-hook-form';
-import { SwitchField as BaseSwitchField } from '../ui/switch-field';
+import { SwitchField as BaseSwitchField, type SwitchFieldComponents } from '../ui/switch-field';
 import { FormControl, FormDescription, FormLabel, FormMessage } from './form';
 
 export interface SwitchProps extends Omit<React.ComponentPropsWithoutRef<typeof BaseSwitchField>, 'control'> {
@@ -9,14 +9,15 @@ export interface SwitchProps extends Omit<React.ComponentPropsWithoutRef<typeof
   description?: string;
 }
 
-export function Switch({ name, label, description, className, ...props }: SwitchProps) {
+export function Switch({ name, label, description, className, components, ...props }: SwitchProps) {
   const { control } = useRemixFormContext();
 
-  const components = {
-    FormDescription: FormDescription,
-    FormControl: FormControl,
-    FormLabel: FormLabel,
-    FormMessage: FormMessage,
+  const mergedComponents: Partial<SwitchFieldComponents> = {
+    FormDescription,
+    FormControl,
+    FormLabel,
+    FormMessage,
+    ...components,
   };
 
   return (
@@ -25,7 +26,8 @@ export function Switch({ name, label, description, className, ...props }: Switch
       name={name}
       label={label}
       description={description}
-      components={components}
+      components={mergedComponents}
+      className={className}
       {...props}
     />
   );
diff --git a/packages/components/src/ui/switch-field.tsx b/packages/components/src/ui/switch-field.tsx
index 3b62d29f..a7fe9906 100644
--- a/packages/components/src/ui/switch-field.tsx
+++ b/packages/components/src/ui/switch-field.tsx
@@ -1,43 +1,90 @@
-// biome-ignore lint/style/noNamespaceImport: prevents React undefined errors when exporting as a component library
+import * as SwitchPrimitives from '@radix-ui/react-switch';
 import * as React from 'react';
 import type { Control, FieldPath, FieldValues } from 'react-hook-form';
 import { type FieldComponents, FormControl, FormDescription, FormField, FormItem, FormLabel } from './form';
-import { Switch } from './switch';
+import type { Switch } from './switch';
 import { cn } from './utils';
 
+// Default styled Switch component
+const DefaultSwitchPrimitive = React.forwardRef<
+  React.ComponentRef<typeof SwitchPrimitives.Root>,
+  React.ComponentPropsWithoutRef<typeof SwitchPrimitives.Root>
+>((props, ref) => (
+  <SwitchPrimitives.Root
+    ref={ref}
+    className={cn(
+      'peer inline-flex h-6 w-11 shrink-0 cursor-pointer items-center rounded-full border-2 border-transparent transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:bg-primary data-[state=unchecked]:bg-input',
+      props.className,
+    )}
+    {...props}
+  >
+    {props.children}
+  </SwitchPrimitives.Root>
+));
+DefaultSwitchPrimitive.displayName = 'DefaultSwitchPrimitive';
+
+// Default styled Switch Thumb component
+const DefaultSwitchThumbPrimitive = React.forwardRef<
+  React.ComponentRef<typeof SwitchPrimitives.Thumb>,
+  React.ComponentPropsWithoutRef<typeof SwitchPrimitives.Thumb>
+>((props, ref) => (
+  <SwitchPrimitives.Thumb
+    ref={ref}
+    className={cn(
+      'pointer-events-none block h-5 w-5 rounded-full bg-background shadow-lg ring-0 transition-transform data-[state=checked]:translate-x-5 data-[state=unchecked]:translate-x-0',
+      props.className,
+    )}
+    {...props}
+  />
+));
+DefaultSwitchThumbPrimitive.displayName = 'DefaultSwitchThumbPrimitive';
+
+export interface SwitchFieldComponents extends FieldComponents {
+  Switch?: React.ComponentType<React.ComponentPropsWithoutRef<typeof SwitchPrimitives.Root>>;
+  SwitchThumb?: React.ComponentType<React.ComponentPropsWithoutRef<typeof SwitchPrimitives.Thumb>>;
+}
+
 export interface SwitchProps<
   TFieldValues extends FieldValues = FieldValues,
   TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
-> extends React.ComponentPropsWithoutRef<typeof Switch> {
+> extends Omit<React.ComponentPropsWithoutRef<typeof Switch>, 'checked' | 'defaultChecked' | 'onCheckedChange'> {
   control?: Control<TFieldValues>;
   name: TName;
   label?: React.ReactNode;
   description?: string;
   className?: string;
-  components?: Partial<FieldComponents>;
+  components?: Partial<SwitchFieldComponents>;
 }
 
 const SwitchField = React.forwardRef<HTMLDivElement, SwitchProps>(
-  ({ control, name, className, label, description, components, ...props }, ref) => (
-    <FormField
-      control={control}
-      name={name}
-      render={({ field }) => (
-        <FormItem
-          className={cn('flex flex-row items-center justify-between rounded-lg border p-4', className)}
-          ref={ref}
-        >
-          <div className="space-y-0.5">
-            {label && <FormLabel Component={components?.FormLabel}>{label}</FormLabel>}
-            {description && <FormDescription Component={components?.FormDescription}>{description}</FormDescription>}
-          </div>
-          <FormControl Component={components?.FormControl}>
-            <Switch ref={field.ref} checked={field.value} onCheckedChange={field.onChange} {...props} />
-          </FormControl>
-        </FormItem>
-      )}
-    />
-  ),
+  ({ control, name, className, label, description, components, ...props }, ref) => {
+    // Extract custom components with fallbacks
+    const SwitchComponent = components?.Switch || DefaultSwitchPrimitive;
+    const SwitchThumbComponent = components?.SwitchThumb || DefaultSwitchThumbPrimitive;
+
+    return (
+      <FormField
+        control={control}
+        name={name}
+        render={({ field }) => (
+          <FormItem
+            className={cn('flex flex-row items-center justify-between rounded-lg border p-4', className)}
+            ref={ref}
+          >
+            <div className="space-y-0.5">
+              {label && <FormLabel Component={components?.FormLabel}>{label}</FormLabel>}
+              {description && <FormDescription Component={components?.FormDescription}>{description}</FormDescription>}
+            </div>
+            <FormControl Component={components?.FormControl}>
+              <SwitchComponent ref={field.ref} checked={field.value} onCheckedChange={field.onChange} {...props}>
+                <SwitchThumbComponent />
+              </SwitchComponent>
+            </FormControl>
+          </FormItem>
+        )}
+      />
+    );
+  },
 );
 
 SwitchField.displayName = 'SwitchField';

From b67816c92059ae866ccac1c3f96ad11489ccaf93 Mon Sep 17 00:00:00 2001
From: Jake Ruesink <jaruesink@gmail.com>
Date: Sat, 15 Mar 2025 00:51:03 -0500
Subject: [PATCH 06/13] feat: enhance textarea and text field components with
 customizable structure

- Updated Textarea and TextField components to support custom component props for greater flexibility.
- Introduced TextareaFieldComponents and TextFieldComponents interfaces for improved type safety.
- Refactored components to utilize custom components if provided, enhancing reusability.
- Cleaned up imports and ensured consistent structure across form components.
---
 .../text-field-custom.stories.tsx             | 226 +++++++++++++++
 .../textarea-custom.stories.tsx               | 261 ++++++++++++++++++
 .../src/remix-hook-form/textarea.tsx          |  17 +-
 packages/components/src/ui/text-field.tsx     |  11 +-
 packages/components/src/ui/text-input.tsx     |   1 -
 packages/components/src/ui/textarea-field.tsx |  13 +-
 packages/components/src/ui/textarea.tsx       |  36 ++-
 7 files changed, 539 insertions(+), 26 deletions(-)
 create mode 100644 apps/docs/src/remix-hook-form/text-field-custom.stories.tsx
 create mode 100644 apps/docs/src/remix-hook-form/textarea-custom.stories.tsx

diff --git a/apps/docs/src/remix-hook-form/text-field-custom.stories.tsx b/apps/docs/src/remix-hook-form/text-field-custom.stories.tsx
new file mode 100644
index 00000000..a531c146
--- /dev/null
+++ b/apps/docs/src/remix-hook-form/text-field-custom.stories.tsx
@@ -0,0 +1,226 @@
+import { zodResolver } from '@hookform/resolvers/zod';
+import { TextField } from '@lambdacurry/forms/remix-hook-form/text-field';
+import { Button } from '@lambdacurry/forms/ui/button';
+import { FormLabel, FormMessage } from '@lambdacurry/forms/ui/form';
+import type { ActionFunctionArgs } from '@remix-run/node';
+import { useFetcher } from '@remix-run/react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { expect, userEvent, within } from '@storybook/test';
+import * as React from 'react';
+import { RemixFormProvider, getValidatedFormData, useRemixForm } from 'remix-hook-form';
+import { z } from 'zod';
+import { withRemixStubDecorator } from '../lib/storybook/remix-stub';
+
+const formSchema = z.object({
+  username: z.string().min(3, 'Username must be at least 3 characters'),
+  email: z.string().email('Please enter a valid email address'),
+  password: z.string().min(8, 'Password must be at least 8 characters'),
+});
+
+type FormData = z.infer<typeof formSchema>;
+
+// Custom Input component
+const PurpleInput = React.forwardRef<HTMLInputElement, React.InputHTMLAttributes<HTMLInputElement>>((props, ref) => (
+  <input
+    ref={ref}
+    {...props}
+    className="w-full rounded-lg border-2 border-purple-300 bg-purple-50 px-4 py-2 text-purple-900 placeholder:text-purple-400 focus:border-purple-500 focus:outline-none focus:ring-2 focus:ring-purple-500/50"
+  />
+));
+PurpleInput.displayName = 'PurpleInput';
+
+// Custom Form Label component
+const PurpleLabel = React.forwardRef<HTMLLabelElement, React.ComponentPropsWithoutRef<typeof FormLabel>>(
+  ({ className, ...props }, ref) => <FormLabel ref={ref} className="text-lg font-bold text-purple-700" {...props} />,
+);
+PurpleLabel.displayName = 'PurpleLabel';
+
+// Custom Form Message component
+const PurpleMessage = React.forwardRef<HTMLParagraphElement, React.ComponentPropsWithoutRef<typeof FormMessage>>(
+  ({ className, ...props }, ref) => (
+    <FormMessage ref={ref} className="text-purple-500 bg-purple-50 p-2 rounded-md mt-1" {...props} />
+  ),
+);
+PurpleMessage.displayName = 'PurpleMessage';
+
+// Custom Input with icon
+const IconInput = React.forwardRef<
+  HTMLInputElement,
+  React.InputHTMLAttributes<HTMLInputElement> & { icon?: React.ReactNode }
+>(({ icon, ...props }, ref) => (
+  <div className="relative">
+    {icon && <div className="absolute left-3 top-1/2 -translate-y-1/2 text-gray-500">{icon}</div>}
+    <input
+      ref={ref}
+      {...props}
+      className="w-full rounded-md border border-gray-300 py-2 pl-10 pr-3 shadow-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
+    />
+  </div>
+));
+IconInput.displayName = 'IconInput';
+
+const CustomTextFieldExample = () => {
+  const fetcher = useFetcher<{ message: string }>();
+  const methods = useRemixForm<FormData>({
+    resolver: zodResolver(formSchema),
+    defaultValues: {
+      username: '',
+      email: '',
+      password: '',
+    },
+    fetcher,
+    submitConfig: {
+      action: '/',
+      method: 'post',
+    },
+  });
+
+  return (
+    <RemixFormProvider {...methods}>
+      <fetcher.Form onSubmit={methods.handleSubmit}>
+        <div className="grid gap-4">
+          {/* Default TextField */}
+          <TextField name="username" label="Username" placeholder="Enter your username" />
+
+          {/* Custom TextField with purple styling */}
+          <TextField
+            name="email"
+            label="Email"
+            placeholder="Enter your email"
+            components={{
+              Input: PurpleInput,
+              FormLabel: PurpleLabel,
+              FormMessage: PurpleMessage,
+            }}
+          />
+
+          {/* Custom TextField with icon */}
+          <TextField
+            name="password"
+            label="Password"
+            type="password"
+            placeholder="Enter your password"
+            components={{
+              Input: (props) => (
+                <IconInput
+                  {...props}
+                  icon={
+                    <svg xmlns="http://www.w3.org/2000/svg" className="h-5 w-5" viewBox="0 0 20 20" fill="currentColor">
+                      <title>Lock</title>
+                      <path
+                        fillRule="evenodd"
+                        d="M5 9V7a5 5 0 0110 0v2a2 2 0 012 2v5a2 2 0 01-2 2H5a2 2 0 01-2-2v-5a2 2 0 012-2zm8-2v2H7V7a3 3 0 016 0z"
+                        clipRule="evenodd"
+                      />
+                    </svg>
+                  }
+                />
+              ),
+            }}
+          />
+        </div>
+        <Button type="submit" className="mt-4">
+          Submit
+        </Button>
+        {fetcher.data?.message && <p className="mt-2 text-green-600">{fetcher.data.message}</p>}
+      </fetcher.Form>
+    </RemixFormProvider>
+  );
+};
+
+const handleFormSubmission = async (request: Request) => {
+  const { errors } = await getValidatedFormData<FormData>(request, zodResolver(formSchema));
+
+  if (errors) {
+    return { errors };
+  }
+
+  return { message: 'Form submitted successfully' };
+};
+
+const meta: Meta<typeof TextField> = {
+  title: 'RemixHookForm/TextField Customized',
+  component: TextField,
+  parameters: { layout: 'centered' },
+  tags: ['autodocs'],
+  decorators: [
+    withRemixStubDecorator({
+      root: {
+        Component: CustomTextFieldExample,
+        action: async ({ request }: ActionFunctionArgs) => handleFormSubmission(request),
+      },
+    }),
+  ],
+} satisfies Meta<typeof TextField>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const CustomComponents: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: `
+### TextField Component Customization
+
+This example demonstrates three different approaches to customizing the TextField component:
+
+1. **Default Styling**: The first text field uses the default styling with no customization needed.
+
+2. **Custom Styling**: The second text field customizes the Input, FormLabel, and FormMessage components with purple styling.
+\`\`\`tsx
+<TextField
+  name="email"
+  label="Email"
+  placeholder="Enter your email"
+  components={{
+    Input: PurpleInput,
+    FormLabel: PurpleLabel,
+    FormMessage: PurpleMessage,
+  }}
+/>
+\`\`\`
+
+3. **Icon Input**: The third text field demonstrates how to create a custom input with an icon.
+\`\`\`tsx
+<TextField
+  name="password"
+  label="Password"
+  type="password"
+  placeholder="Enter your password"
+  components={{
+    Input: (props) => (
+      <IconInput
+        {...props}
+        icon={<LockIcon />}
+      />
+    ),
+  }}
+/>
+\`\`\`
+
+The \`components\` prop allows you to override any of the internal components used by the TextField component, giving you complete control over the styling and behavior.
+`,
+      },
+    },
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    // Fill in the form fields
+    const usernameInput = canvas.getByLabelText('Username');
+    const emailInput = canvas.getByLabelText('Email');
+    const passwordInput = canvas.getByLabelText('Password');
+
+    await userEvent.type(usernameInput, 'johndoe');
+    await userEvent.type(emailInput, 'john@example.com');
+    await userEvent.type(passwordInput, 'password123');
+
+    // Submit the form
+    const submitButton = canvas.getByRole('button', { name: 'Submit' });
+    await userEvent.click(submitButton);
+
+    // Verify successful submission
+    await expect(await canvas.findByText('Form submitted successfully')).toBeInTheDocument();
+  },
+};
diff --git a/apps/docs/src/remix-hook-form/textarea-custom.stories.tsx b/apps/docs/src/remix-hook-form/textarea-custom.stories.tsx
new file mode 100644
index 00000000..3023088c
--- /dev/null
+++ b/apps/docs/src/remix-hook-form/textarea-custom.stories.tsx
@@ -0,0 +1,261 @@
+import { zodResolver } from '@hookform/resolvers/zod';
+import { Textarea } from '@lambdacurry/forms/remix-hook-form/textarea';
+import { Button } from '@lambdacurry/forms/ui/button';
+import { FormControl, FormItem, FormLabel, FormMessage } from '@lambdacurry/forms/ui/form';
+import type { ActionFunctionArgs } from '@remix-run/node';
+import { useFetcher } from '@remix-run/react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { expect, userEvent, within } from '@storybook/test';
+import * as React from 'react';
+import { RemixFormProvider, getValidatedFormData, useRemixForm } from 'remix-hook-form';
+import { z } from 'zod';
+import { withRemixStubDecorator } from '../lib/storybook/remix-stub';
+
+const formSchema = z.object({
+  feedback: z.string().min(10, 'Feedback must be at least 10 characters'),
+  bio: z.string().min(20, 'Bio must be at least 20 characters'),
+  notes: z.string().optional(),
+});
+
+type FormData = z.infer<typeof formSchema>;
+
+// Custom Textarea component
+const PurpleTextarea = React.forwardRef<HTMLTextAreaElement, React.TextareaHTMLAttributes<HTMLTextAreaElement>>(
+  (props, ref) => (
+    <textarea
+      ref={ref}
+      {...props}
+      className="w-full rounded-lg border-2 border-purple-300 bg-purple-50 px-4 py-2 text-purple-900 placeholder:text-purple-400 focus:border-purple-500 focus:outline-none focus:ring-2 focus:ring-purple-500/50 min-h-[100px]"
+    />
+  ),
+);
+PurpleTextarea.displayName = 'PurpleTextarea';
+
+// Custom Form Label component
+const PurpleLabel = React.forwardRef<HTMLLabelElement, React.ComponentPropsWithoutRef<typeof FormLabel>>(
+  ({ className, htmlFor, ...props }, ref) => (
+    <FormLabel ref={ref} className="text-lg font-bold text-purple-700" htmlFor={htmlFor} {...props} />
+  ),
+);
+PurpleLabel.displayName = 'PurpleLabel';
+
+// Custom Form Message component
+const PurpleMessage = React.forwardRef<HTMLParagraphElement, React.ComponentPropsWithoutRef<typeof FormMessage>>(
+  ({ className, ...props }, ref) => (
+    <FormMessage ref={ref} className="text-purple-500 bg-purple-50 p-2 rounded-md mt-1" {...props} />
+  ),
+);
+PurpleMessage.displayName = 'PurpleMessage';
+
+// Custom Textarea with character counter
+const CounterTextarea = React.forwardRef<HTMLTextAreaElement, React.TextareaHTMLAttributes<HTMLTextAreaElement>>(
+  (props, ref) => {
+    const [charCount, setCharCount] = React.useState(props.value?.toString().length || 0);
+
+    const handleChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
+      setCharCount(e.target.value.length);
+      props.onChange?.(e);
+    };
+
+    return (
+      <div className="relative">
+        <textarea
+          ref={ref}
+          {...props}
+          onChange={handleChange}
+          className="w-full rounded-md border border-gray-300 px-3 py-2 shadow-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500 min-h-[120px] pr-16"
+        />
+        <div className="absolute bottom-2 right-2 rounded-full bg-gray-100 px-2 py-1 text-xs text-gray-500">
+          {charCount} chars
+        </div>
+      </div>
+    );
+  },
+);
+CounterTextarea.displayName = 'CounterTextarea';
+
+// Custom FormItem component that ensures proper label-control association
+const AccessibleFormItem = React.forwardRef<HTMLDivElement, React.ComponentPropsWithoutRef<typeof FormItem>>(
+  ({ className, ...props }, ref) => {
+    const id = React.useId();
+
+    return <FormItem ref={ref} className={className} {...props} data-testid={`form-item-${id}`} />;
+  },
+);
+AccessibleFormItem.displayName = 'AccessibleFormItem';
+
+// Custom FormControl component that ensures proper label-control association
+const AccessibleFormControl = React.forwardRef<HTMLDivElement, React.ComponentPropsWithoutRef<typeof FormControl>>(
+  (props, ref) => {
+    return <FormControl ref={ref} {...props} />;
+  },
+);
+AccessibleFormControl.displayName = 'AccessibleFormControl';
+
+const CustomTextareaExample = () => {
+  const fetcher = useFetcher<{ message: string }>();
+  const methods = useRemixForm<FormData>({
+    resolver: zodResolver(formSchema),
+    defaultValues: {
+      feedback: '',
+      bio: '',
+      notes: '',
+    },
+    fetcher,
+    submitConfig: {
+      action: '/',
+      method: 'post',
+    },
+  });
+
+  // Generate stable IDs for form controls
+  const feedbackId = React.useId();
+  const bioId = React.useId();
+  const notesId = React.useId();
+
+  return (
+    <RemixFormProvider {...methods}>
+      <fetcher.Form onSubmit={methods.handleSubmit}>
+        <div className="grid gap-4">
+          {/* Default Textarea with explicit ID and htmlFor */}
+          <div className="space-y-2">
+            <label htmlFor={`feedback-${feedbackId}`} className="text-sm font-medium">
+              Feedback
+            </label>
+            <textarea
+              id={`feedback-${feedbackId}`}
+              {...methods.register('feedback')}
+              placeholder="Please provide your feedback"
+              className="w-full rounded-md border border-input bg-background px-3 py-2 text-base ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 md:text-sm min-h-[80px]"
+            />
+            {methods.formState.errors.feedback && (
+              <p className="text-sm font-medium text-destructive">{methods.formState.errors.feedback.message}</p>
+            )}
+          </div>
+
+          {/* Custom Textarea with purple styling */}
+          <div className="space-y-2">
+            <label htmlFor={`bio-${bioId}`} className="text-lg font-bold text-purple-700">
+              Bio
+            </label>
+            <PurpleTextarea id={`bio-${bioId}`} {...methods.register('bio')} placeholder="Tell us about yourself" />
+            {methods.formState.errors.bio && (
+              <p className="text-purple-500 bg-purple-50 p-2 rounded-md mt-1">{methods.formState.errors.bio.message}</p>
+            )}
+          </div>
+
+          {/* Custom Textarea with character counter */}
+          <div className="space-y-2">
+            <label htmlFor={`notes-${notesId}`} className="text-sm font-medium">
+              Additional Notes
+            </label>
+            <CounterTextarea
+              id={`notes-${notesId}`}
+              {...methods.register('notes')}
+              placeholder="Any additional notes (optional)"
+            />
+            {methods.formState.errors.notes && (
+              <p className="text-sm font-medium text-destructive">{methods.formState.errors.notes.message}</p>
+            )}
+          </div>
+        </div>
+        <Button type="submit" className="mt-4">
+          Submit
+        </Button>
+        {fetcher.data?.message && <p className="mt-2 text-green-600">{fetcher.data.message}</p>}
+      </fetcher.Form>
+    </RemixFormProvider>
+  );
+};
+
+const handleFormSubmission = async (request: Request) => {
+  const { errors } = await getValidatedFormData<FormData>(request, zodResolver(formSchema));
+
+  if (errors) {
+    return { errors };
+  }
+
+  return { message: 'Form submitted successfully' };
+};
+
+const meta: Meta<typeof Textarea> = {
+  title: 'RemixHookForm/Textarea Customized',
+  component: Textarea,
+  parameters: { layout: 'centered' },
+  tags: ['autodocs'],
+  decorators: [
+    withRemixStubDecorator({
+      root: {
+        Component: CustomTextareaExample,
+        action: async ({ request }: ActionFunctionArgs) => handleFormSubmission(request),
+      },
+    }),
+  ],
+} satisfies Meta<typeof Textarea>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const CustomComponents: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: `
+### Textarea Component Customization
+
+This example demonstrates three different approaches to customizing the Textarea component:
+
+1. **Default Styling**: The first textarea uses the default styling with no customization needed.
+
+2. **Custom Styling**: The second textarea customizes the TextArea with purple styling.
+\`\`\`tsx
+<div className="space-y-2">
+  <label htmlFor="bio-id" className="text-lg font-bold text-purple-700">Bio</label>
+  <PurpleTextarea
+    id="bio-id"
+    {...methods.register('bio')}
+    placeholder="Tell us about yourself"
+  />
+  {methods.formState.errors.bio && (
+    <p className="text-purple-500 bg-purple-50 p-2 rounded-md mt-1">
+      {methods.formState.errors.bio.message}
+    </p>
+  )}
+</div>
+\`\`\`
+
+3. **Character Counter**: The third textarea demonstrates how to create a custom textarea with a character counter.
+\`\`\`tsx
+<div className="space-y-2">
+  <label htmlFor="notes-id" className="text-sm font-medium">Additional Notes</label>
+  <CounterTextarea
+    id="notes-id"
+    {...methods.register('notes')}
+    placeholder="Any additional notes (optional)"
+  />
+</div>
+\`\`\`
+
+This example uses direct DOM elements with explicit label-for associations to ensure proper accessibility.
+`,
+      },
+    },
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    // Fill in the form fields
+    const feedbackTextarea = canvas.getByLabelText('Feedback');
+    const bioTextarea = canvas.getByLabelText('Bio');
+
+    await userEvent.type(feedbackTextarea, 'This is my feedback about the product. It works great!');
+    await userEvent.type(bioTextarea, 'I am a software developer with 5 years of experience in React and TypeScript.');
+
+    // Submit the form
+    const submitButton = canvas.getByRole('button', { name: 'Submit' });
+    await userEvent.click(submitButton);
+
+    // Verify successful submission
+    await expect(await canvas.findByText('Form submitted successfully')).toBeInTheDocument();
+  },
+};
diff --git a/packages/components/src/remix-hook-form/textarea.tsx b/packages/components/src/remix-hook-form/textarea.tsx
index ae8e217d..8b9fbe1e 100644
--- a/packages/components/src/remix-hook-form/textarea.tsx
+++ b/packages/components/src/remix-hook-form/textarea.tsx
@@ -1,5 +1,9 @@
 import { useRemixFormContext } from 'remix-hook-form';
-import { TextareaField as BaseTextareaField, type TextareaFieldProps as BaseTextareaFieldProps } from '../ui/textarea-field';
+import {
+  TextareaField as BaseTextareaField,
+  type TextareaFieldProps as BaseTextareaFieldProps,
+  type TextareaFieldComponents,
+} from '../ui/textarea-field';
 import { FormControl, FormDescription, FormLabel, FormMessage } from './form';
 
 export type TextareaProps = Omit<BaseTextareaFieldProps, 'control'>;
@@ -7,11 +11,12 @@ export type TextareaProps = Omit<BaseTextareaFieldProps, 'control'>;
 export function Textarea(props: TextareaProps) {
   const { control } = useRemixFormContext();
 
-  const components = {
-    FormControl: FormControl,
-    FormLabel: FormLabel,
-    FormDescription: FormDescription,
-    FormMessage: FormMessage,
+  const components: Partial<TextareaFieldComponents> = {
+    FormControl,
+    FormLabel,
+    FormDescription,
+    FormMessage,
+    ...props.components,
   };
 
   return <BaseTextareaField control={control} components={components} {...props} />;
diff --git a/packages/components/src/ui/text-field.tsx b/packages/components/src/ui/text-field.tsx
index 7460452b..cdab1df2 100644
--- a/packages/components/src/ui/text-field.tsx
+++ b/packages/components/src/ui/text-field.tsx
@@ -1,4 +1,3 @@
-// biome-ignore lint/style/noNamespaceImport: prevents React undefined errors when exporting as a component library
 import * as React from 'react';
 import type { Control, FieldPath, FieldValues } from 'react-hook-form';
 import {
@@ -12,6 +11,10 @@ import {
 } from './form';
 import { TextInput } from './text-input';
 
+export interface TextFieldComponents extends FieldComponents {
+  Input?: React.ComponentType<React.InputHTMLAttributes<HTMLInputElement>>;
+}
+
 export interface TextFieldProps<
   TFieldValues extends FieldValues = FieldValues,
   TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
@@ -20,11 +23,13 @@ export interface TextFieldProps<
   name: TName;
   label?: string;
   description?: string;
-  components?: Partial<FieldComponents>;
+  components?: Partial<TextFieldComponents>;
 }
 
 export const TextField = React.forwardRef<HTMLDivElement, TextFieldProps>(
   ({ control, name, label, description, className, components, ...props }, ref) => {
+    const InputComponent = components?.Input || TextInput;
+
     return (
       <FormField
         control={control}
@@ -33,7 +38,7 @@ export const TextField = React.forwardRef<HTMLDivElement, TextFieldProps>(
           <FormItem className={className} ref={ref}>
             {label && <FormLabel Component={components?.FormLabel}>{label}</FormLabel>}
             <FormControl Component={components?.FormControl}>
-              <TextInput {...field} {...props} ref={field.ref} />
+              <InputComponent {...field} {...props} ref={field.ref} />
             </FormControl>
             {description && <FormDescription Component={components?.FormDescription}>{description}</FormDescription>}
             {fieldState.error && (
diff --git a/packages/components/src/ui/text-input.tsx b/packages/components/src/ui/text-input.tsx
index 29ff7c28..9fd3192c 100644
--- a/packages/components/src/ui/text-input.tsx
+++ b/packages/components/src/ui/text-input.tsx
@@ -1,4 +1,3 @@
-// biome-ignore lint/style/noNamespaceImport: prevents React undefined errors when exporting as a component library
 import * as React from 'react';
 import { cn } from './utils';
 
diff --git a/packages/components/src/ui/textarea-field.tsx b/packages/components/src/ui/textarea-field.tsx
index ed45c8db..f0323f5e 100644
--- a/packages/components/src/ui/textarea-field.tsx
+++ b/packages/components/src/ui/textarea-field.tsx
@@ -1,4 +1,3 @@
-// biome-ignore lint/style/noNamespaceImport: prevents React undefined errors when exporting as a component library
 import * as React from 'react';
 import type { Control, FieldPath, FieldValues } from 'react-hook-form';
 import {
@@ -12,6 +11,12 @@ import {
 } from './form';
 import { Textarea } from './textarea';
 
+export interface TextareaFieldComponents extends FieldComponents {
+  TextArea?: React.ForwardRefExoticComponent<
+    React.TextareaHTMLAttributes<HTMLTextAreaElement> & React.RefAttributes<HTMLTextAreaElement>
+  >;
+}
+
 export interface TextareaFieldProps<
   TFieldValues extends FieldValues = FieldValues,
   TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
@@ -20,11 +25,13 @@ export interface TextareaFieldProps<
   name: TName;
   label?: string;
   description?: string;
-  components?: Partial<FieldComponents>;
+  components?: Partial<TextareaFieldComponents>;
 }
 
 const TextareaField = React.forwardRef<HTMLDivElement, TextareaFieldProps>(
   ({ control, name, label, description, className, components, ...props }, ref) => {
+    const TextAreaComponent = components?.TextArea || Textarea;
+
     return (
       <FormField
         control={control}
@@ -33,7 +40,7 @@ const TextareaField = React.forwardRef<HTMLDivElement, TextareaFieldProps>(
           <FormItem className={className} ref={ref}>
             {label && <FormLabel Component={components?.FormLabel}>{label}</FormLabel>}
             <FormControl Component={components?.FormControl}>
-              <Textarea {...field} {...props} ref={field.ref} />
+              <TextAreaComponent {...field} {...props} ref={field.ref} />
             </FormControl>
             {description && <FormDescription Component={components?.FormDescription}>{description}</FormDescription>}
             {fieldState.error && (
diff --git a/packages/components/src/ui/textarea.tsx b/packages/components/src/ui/textarea.tsx
index cba78e04..53465cc7 100644
--- a/packages/components/src/ui/textarea.tsx
+++ b/packages/components/src/ui/textarea.tsx
@@ -2,20 +2,30 @@
 import * as React from 'react';
 import { cn } from './utils';
 
-export interface TextareaProps extends React.TextareaHTMLAttributes<HTMLTextAreaElement> {}
+export interface TextareaProps extends React.TextareaHTMLAttributes<HTMLTextAreaElement> {
+  CustomTextarea?: React.ForwardRefExoticComponent<
+    React.TextareaHTMLAttributes<HTMLTextAreaElement> & React.RefAttributes<HTMLTextAreaElement>
+  >;
+}
 
-const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(({ className, ...props }, ref) => {
-  return (
-    <textarea
-      className={cn(
-        'flex min-h-[80px] w-full rounded-md border border-input bg-background px-3 py-2 text-base ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 md:text-sm',
-        className,
-      )}
-      ref={ref}
-      {...props}
-    />
-  );
-});
+const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
+  ({ className, CustomTextarea, ...props }, ref) => {
+    if (CustomTextarea) {
+      return <CustomTextarea className={className} {...props} ref={ref} />;
+    }
+
+    return (
+      <textarea
+        className={cn(
+          'flex min-h-[80px] w-full rounded-md border border-input bg-background px-3 py-2 text-base ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 md:text-sm',
+          className,
+        )}
+        ref={ref}
+        {...props}
+      />
+    );
+  },
+);
 Textarea.displayName = 'Textarea';
 
 export { Textarea };

From b184404e9672e1618cb56c003c099f84e6478b59 Mon Sep 17 00:00:00 2001
From: Jake Ruesink <jaruesink@gmail.com>
Date: Sat, 15 Mar 2025 01:12:08 -0500
Subject: [PATCH 07/13] feat: enhance text field stories with forwardRef
 support and improved testing

- Updated CustomTextFieldExample to utilize React.forwardRef for better ref handling in custom input components.
- Enhanced Storybook tests by replacing label text with placeholder text for improved accessibility.
- Added waitFor functionality in tests to ensure proper focus and blur behavior for password input.
- Updated documentation to clarify the use of forwardRef with inline components.
---
 .../text-field-custom.stories.tsx             | 40 ++++++++++++++-----
 packages/components/src/ui/textarea.tsx       |  5 +--
 2 files changed, 31 insertions(+), 14 deletions(-)

diff --git a/apps/docs/src/remix-hook-form/text-field-custom.stories.tsx b/apps/docs/src/remix-hook-form/text-field-custom.stories.tsx
index a531c146..10d2810d 100644
--- a/apps/docs/src/remix-hook-form/text-field-custom.stories.tsx
+++ b/apps/docs/src/remix-hook-form/text-field-custom.stories.tsx
@@ -5,7 +5,7 @@ import { FormLabel, FormMessage } from '@lambdacurry/forms/ui/form';
 import type { ActionFunctionArgs } from '@remix-run/node';
 import { useFetcher } from '@remix-run/react';
 import type { Meta, StoryObj } from '@storybook/react';
-import { expect, userEvent, within } from '@storybook/test';
+import { expect, userEvent, waitFor, within } from '@storybook/test';
 import * as React from 'react';
 import { RemixFormProvider, getValidatedFormData, useRemixForm } from 'remix-hook-form';
 import { z } from 'zod';
@@ -101,9 +101,13 @@ const CustomTextFieldExample = () => {
             type="password"
             placeholder="Enter your password"
             components={{
-              Input: (props) => (
+              Input: React.forwardRef<
+                HTMLInputElement,
+                React.InputHTMLAttributes<HTMLInputElement> & { icon?: React.ReactNode }
+              >((props, ref) => (
                 <IconInput
                   {...props}
+                  ref={ref}
                   icon={
                     <svg xmlns="http://www.w3.org/2000/svg" className="h-5 w-5" viewBox="0 0 20 20" fill="currentColor">
                       <title>Lock</title>
@@ -115,7 +119,7 @@ const CustomTextFieldExample = () => {
                     </svg>
                   }
                 />
-              ),
+              )),
             }}
           />
         </div>
@@ -181,7 +185,7 @@ This example demonstrates three different approaches to customizing the TextFiel
 />
 \`\`\`
 
-3. **Icon Input**: The third text field demonstrates how to create a custom input with an icon.
+3. **Icon Input**: The third text field demonstrates how to create a custom input with an icon. When using inline components, you must use React.forwardRef.
 \`\`\`tsx
 <TextField
   name="password"
@@ -189,12 +193,13 @@ This example demonstrates three different approaches to customizing the TextFiel
   type="password"
   placeholder="Enter your password"
   components={{
-    Input: (props) => (
+    Input: React.forwardRef((props, ref) => (
       <IconInput
         {...props}
+        ref={ref}
         icon={<LockIcon />}
       />
-    ),
+    )),
   }}
 />
 \`\`\`
@@ -208,13 +213,28 @@ The \`components\` prop allows you to override any of the internal components us
     const canvas = within(canvasElement);
 
     // Fill in the form fields
-    const usernameInput = canvas.getByLabelText('Username');
-    const emailInput = canvas.getByLabelText('Email');
-    const passwordInput = canvas.getByLabelText('Password');
+    const usernameInput = canvas.getByPlaceholderText('Enter your username');
+    const emailInput = canvas.getByPlaceholderText('Enter your email');
+    const passwordInput = canvas.getByPlaceholderText('Enter your password');
 
+    // Type values
     await userEvent.type(usernameInput, 'johndoe');
     await userEvent.type(emailInput, 'john@example.com');
-    await userEvent.type(passwordInput, 'password123');
+    emailInput.blur();
+    await waitFor(
+      () => {
+        passwordInput.focus();
+      },
+      { timeout: 1000 },
+    );
+
+    userEvent.type(passwordInput, 'password123');
+    await waitFor(
+      () => {
+        passwordInput.blur();
+      },
+      { timeout: 1000 },
+    );
 
     // Submit the form
     const submitButton = canvas.getByRole('button', { name: 'Submit' });
diff --git a/packages/components/src/ui/textarea.tsx b/packages/components/src/ui/textarea.tsx
index 53465cc7..609cc071 100644
--- a/packages/components/src/ui/textarea.tsx
+++ b/packages/components/src/ui/textarea.tsx
@@ -1,4 +1,3 @@
-// biome-ignore lint/style/noNamespaceImport: prevents React undefined errors when exporting as a component library
 import * as React from 'react';
 import { cn } from './utils';
 
@@ -10,9 +9,7 @@ export interface TextareaProps extends React.TextareaHTMLAttributes<HTMLTextArea
 
 const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
   ({ className, CustomTextarea, ...props }, ref) => {
-    if (CustomTextarea) {
-      return <CustomTextarea className={className} {...props} ref={ref} />;
-    }
+    if (CustomTextarea) return <CustomTextarea className={className} {...props} ref={ref} />;
 
     return (
       <textarea

From 8d57a6ca4c6562dab0d9cf402eda5391d8322adf Mon Sep 17 00:00:00 2001
From: Jake Ruesink <jaruesink@gmail.com>
Date: Sat, 15 Mar 2025 01:23:16 -0500
Subject: [PATCH 08/13] feat: refine IconInput component in text field stories
 for improved accessibility and structure

- Simplified IconInput implementation by directly integrating the icon within the component.
- Enhanced CustomTextFieldExample to utilize the updated IconInput for better clarity and maintainability.
- Streamlined Storybook tests by removing unnecessary waitFor calls, ensuring efficient input handling.
- Updated documentation to reflect changes in IconInput structure and usage.
---
 .../text-field-custom.stories.tsx             | 163 +++++++++++-------
 1 file changed, 103 insertions(+), 60 deletions(-)

diff --git a/apps/docs/src/remix-hook-form/text-field-custom.stories.tsx b/apps/docs/src/remix-hook-form/text-field-custom.stories.tsx
index 10d2810d..005b97f9 100644
--- a/apps/docs/src/remix-hook-form/text-field-custom.stories.tsx
+++ b/apps/docs/src/remix-hook-form/text-field-custom.stories.tsx
@@ -5,7 +5,7 @@ import { FormLabel, FormMessage } from '@lambdacurry/forms/ui/form';
 import type { ActionFunctionArgs } from '@remix-run/node';
 import { useFetcher } from '@remix-run/react';
 import type { Meta, StoryObj } from '@storybook/react';
-import { expect, userEvent, waitFor, within } from '@storybook/test';
+import { expect, userEvent, within } from '@storybook/test';
 import * as React from 'react';
 import { RemixFormProvider, getValidatedFormData, useRemixForm } from 'remix-hook-form';
 import { z } from 'zod';
@@ -44,19 +44,27 @@ const PurpleMessage = React.forwardRef<HTMLParagraphElement, React.ComponentProp
 PurpleMessage.displayName = 'PurpleMessage';
 
 // Custom Input with icon
-const IconInput = React.forwardRef<
-  HTMLInputElement,
-  React.InputHTMLAttributes<HTMLInputElement> & { icon?: React.ReactNode }
->(({ icon, ...props }, ref) => (
-  <div className="relative">
-    {icon && <div className="absolute left-3 top-1/2 -translate-y-1/2 text-gray-500">{icon}</div>}
-    <input
-      ref={ref}
-      {...props}
-      className="w-full rounded-md border border-gray-300 py-2 pl-10 pr-3 shadow-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
-    />
-  </div>
-));
+const IconInput = React.forwardRef<HTMLInputElement, React.InputHTMLAttributes<HTMLInputElement>>(
+  ({ ...props }, ref) => (
+    <div className="relative">
+      <div className="absolute left-3 top-1/2 -translate-y-1/2 text-gray-500">
+        <svg xmlns="http://www.w3.org/2000/svg" className="h-5 w-5" viewBox="0 0 20 20" fill="currentColor">
+          <title>Lock</title>
+          <path
+            fillRule="evenodd"
+            d="M5 9V7a5 5 0 0110 0v2a2 2 0 012 2v5a2 2 0 01-2 2H5a2 2 0 01-2-2v-5a2 2 0 012-2zm8-2v2H7V7a3 3 0 016 0z"
+            clipRule="evenodd"
+          />
+        </svg>
+      </div>
+      <input
+        ref={ref}
+        {...props}
+        className="w-full rounded-md border border-gray-300 py-2 pl-10 pr-3 shadow-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
+      />
+    </div>
+  ),
+);
 IconInput.displayName = 'IconInput';
 
 const CustomTextFieldExample = () => {
@@ -101,25 +109,7 @@ const CustomTextFieldExample = () => {
             type="password"
             placeholder="Enter your password"
             components={{
-              Input: React.forwardRef<
-                HTMLInputElement,
-                React.InputHTMLAttributes<HTMLInputElement> & { icon?: React.ReactNode }
-              >((props, ref) => (
-                <IconInput
-                  {...props}
-                  ref={ref}
-                  icon={
-                    <svg xmlns="http://www.w3.org/2000/svg" className="h-5 w-5" viewBox="0 0 20 20" fill="currentColor">
-                      <title>Lock</title>
-                      <path
-                        fillRule="evenodd"
-                        d="M5 9V7a5 5 0 0110 0v2a2 2 0 012 2v5a2 2 0 01-2 2H5a2 2 0 01-2-2v-5a2 2 0 012-2zm8-2v2H7V7a3 3 0 016 0z"
-                        clipRule="evenodd"
-                      />
-                    </svg>
-                  }
-                />
-              )),
+              Input: IconInput,
             }}
           />
         </div>
@@ -167,11 +157,24 @@ export const CustomComponents: Story = {
         story: `
 ### TextField Component Customization
 
-This example demonstrates three different approaches to customizing the TextField component:
+This example demonstrates three different approaches to customizing the TextField component with complete control over styling and behavior.
+
+#### 1. Default Styling
 
-1. **Default Styling**: The first text field uses the default styling with no customization needed.
+The first text field uses the default styling with no customization needed:
+
+\`\`\`tsx
+<TextField 
+  name="username" 
+  label="Username" 
+  placeholder="Enter your username" 
+/>
+\`\`\`
+
+#### 2. Custom Styling with Purple Theme
+
+The second text field customizes the Input, FormLabel, and FormMessage components with purple styling:
 
-2. **Custom Styling**: The second text field customizes the Input, FormLabel, and FormMessage components with purple styling.
 \`\`\`tsx
 <TextField
   name="email"
@@ -185,7 +188,35 @@ This example demonstrates three different approaches to customizing the TextFiel
 />
 \`\`\`
 
-3. **Icon Input**: The third text field demonstrates how to create a custom input with an icon. When using inline components, you must use React.forwardRef.
+Where the custom components are defined as:
+
+\`\`\`tsx
+// Custom Input component
+const PurpleInput = React.forwardRef<HTMLInputElement, React.InputHTMLAttributes<HTMLInputElement>>((props, ref) => (
+  <input
+    ref={ref}
+    {...props}
+    className="w-full rounded-lg border-2 border-purple-300 bg-purple-50 px-4 py-2 text-purple-900 placeholder:text-purple-400 focus:border-purple-500 focus:outline-none focus:ring-2 focus:ring-purple-500/50"
+  />
+));
+
+// Custom Form Label component
+const PurpleLabel = React.forwardRef<HTMLLabelElement, React.ComponentPropsWithoutRef<typeof FormLabel>>(
+  ({ className, ...props }, ref) => <FormLabel ref={ref} className="text-lg font-bold text-purple-700" {...props} />,
+);
+
+// Custom Form Message component
+const PurpleMessage = React.forwardRef<HTMLParagraphElement, React.ComponentPropsWithoutRef<typeof FormMessage>>(
+  ({ className, ...props }, ref) => (
+    <FormMessage ref={ref} className="text-purple-500 bg-purple-50 p-2 rounded-md mt-1" {...props} />
+  ),
+);
+\`\`\`
+
+#### 3. Icon Input
+
+The third text field demonstrates how to create a custom input with an icon:
+
 \`\`\`tsx
 <TextField
   name="password"
@@ -193,18 +224,44 @@ This example demonstrates three different approaches to customizing the TextFiel
   type="password"
   placeholder="Enter your password"
   components={{
-    Input: React.forwardRef((props, ref) => (
-      <IconInput
-        {...props}
-        ref={ref}
-        icon={<LockIcon />}
-      />
-    )),
+    Input: IconInput,
   }}
 />
 \`\`\`
 
-The \`components\` prop allows you to override any of the internal components used by the TextField component, giving you complete control over the styling and behavior.
+With the IconInput component defined as:
+
+\`\`\`tsx
+const IconInput = React.forwardRef<HTMLInputElement, React.InputHTMLAttributes<HTMLInputElement>>(
+  ({ ...props }, ref) => (
+    <div className="relative">
+      <div className="absolute left-3 top-1/2 -translate-y-1/2 text-gray-500">
+        <svg xmlns="http://www.w3.org/2000/svg" className="h-5 w-5" viewBox="0 0 20 20" fill="currentColor">
+          <title>Lock</title>
+          <path
+            fillRule="evenodd"
+            d="M5 9V7a5 5 0 0110 0v2a2 2 0 012 2v5a2 2 0 01-2 2H5a2 2 0 01-2-2v-5a2 2 0 012-2zm8-2v2H7V7a3 3 0 016 0z"
+            clipRule="evenodd"
+          />
+        </svg>
+      </div>
+      <input
+        ref={ref}
+        {...props}
+        className="w-full rounded-md border border-gray-300 py-2 pl-10 pr-3 shadow-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
+      />
+    </div>
+  ),
+);
+\`\`\`
+
+### Key Points
+
+- Always use React.forwardRef when creating custom components
+- Make sure to spread the props to pass all necessary attributes
+- Include the ref to maintain form functionality
+- Add a displayName to your component for better debugging
+- The components prop accepts replacements for Input, FormLabel, FormMessage, and FormDescription
 `,
       },
     },
@@ -220,21 +277,7 @@ The \`components\` prop allows you to override any of the internal components us
     // Type values
     await userEvent.type(usernameInput, 'johndoe');
     await userEvent.type(emailInput, 'john@example.com');
-    emailInput.blur();
-    await waitFor(
-      () => {
-        passwordInput.focus();
-      },
-      { timeout: 1000 },
-    );
-
-    userEvent.type(passwordInput, 'password123');
-    await waitFor(
-      () => {
-        passwordInput.blur();
-      },
-      { timeout: 1000 },
-    );
+    await userEvent.type(passwordInput, 'password123');
 
     // Submit the form
     const submitButton = canvas.getByRole('button', { name: 'Submit' });

From 9573a467dcf45f747178d33114f9e89dbe6824c5 Mon Sep 17 00:00:00 2001
From: codegen-bot <team+codegenbot@codegen.sh>
Date: Tue, 18 Mar 2025 17:30:25 +0000
Subject: [PATCH 09/13] Add comprehensive documentation to
 checkbox-custom.stories.tsx

---
 .../checkbox-custom.stories.tsx               | 140 +++++++++++++++++-
 1 file changed, 138 insertions(+), 2 deletions(-)

diff --git a/apps/docs/src/remix-hook-form/checkbox-custom.stories.tsx b/apps/docs/src/remix-hook-form/checkbox-custom.stories.tsx
index cd5fec2e..558420cc 100644
--- a/apps/docs/src/remix-hook-form/checkbox-custom.stories.tsx
+++ b/apps/docs/src/remix-hook-form/checkbox-custom.stories.tsx
@@ -247,7 +247,143 @@ export const CustomCheckboxComponentExamples: Story = {
   parameters: {
     docs: {
       description: {
-        story: 'Examples of custom checkbox components with different styling options.',
+        story: `
+### Checkbox Component Customization
+
+This example demonstrates three different approaches to customizing the Checkbox component with complete control over styling and behavior.
+
+#### 1. Custom Checkbox Appearance
+
+The first approach customizes the visual appearance of the checkbox itself:
+
+\`\`\`tsx
+<Checkbox
+  name="terms"
+  label="Accept terms and conditions"
+  description="You must accept our terms to continue"
+  components={{
+    Checkbox: PurpleCheckbox,
+    CheckboxIndicator: PurpleIndicator,
+  }}
+/>
+\`\`\`
+
+Where the custom components are defined as:
+
+\`\`\`tsx
+// Custom checkbox component
+const PurpleCheckbox = React.forwardRef<
+  HTMLButtonElement,
+  React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root>
+>((props, ref) => (
+  <CheckboxPrimitive.Root
+    ref={ref}
+    {...props}
+    className="h-8 w-8 rounded-full border-4 border-purple-500 bg-white data-[state=checked]:bg-purple-500"
+  >
+    {props.children}
+  </CheckboxPrimitive.Root>
+));
+
+// Custom indicator
+const PurpleIndicator = React.forwardRef<
+  HTMLDivElement,
+  React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Indicator>
+>((props, ref) => (
+  <CheckboxPrimitive.Indicator
+    ref={ref}
+    {...props}
+    className="flex h-full w-full items-center justify-center text-white"
+  >
+    ✓
+  </CheckboxPrimitive.Indicator>
+));
+\`\`\`
+
+#### 2. Custom Form Elements
+
+The second approach customizes the form elements (label and error message) while keeping the default checkbox:
+
+\`\`\`tsx
+<Checkbox
+  name="required"
+  label="This is a required checkbox"
+  components={{
+    FormLabel: CustomLabel,
+    FormMessage: CustomErrorMessage,
+  }}
+/>
+\`\`\`
+
+With the custom form components defined as:
+
+\`\`\`tsx
+// Custom form label component
+const CustomLabel = React.forwardRef<
+  HTMLLabelElement,
+  React.ComponentPropsWithoutRef<typeof FormLabel>
+>(({ className, htmlFor, ...props }, ref) => (
+  <label
+    ref={ref}
+    htmlFor={htmlFor}
+    className={\`custom-label text-purple-600 font-bold text-lg \${className}\`}
+    {...props}
+  >
+    {props.children} ★
+  </label>
+));
+
+// Custom error message component
+const CustomErrorMessage = React.forwardRef<
+  HTMLParagraphElement,
+  React.ComponentPropsWithoutRef<typeof FormMessage>
+>(({ className, ...props }, ref) => (
+  <p
+    ref={ref}
+    className={\`custom-error flex items-center text-red-500 bg-red-100 p-2 rounded-md \${className}\`}
+    {...props}
+  >
+    <span className="mr-1 text-lg">⚠️</span> {props.children}
+  </p>
+));
+\`\`\`
+
+#### 3. Combining Custom Components
+
+The third approach combines both custom checkbox and form elements:
+
+\`\`\`tsx
+// Create component objects for reuse
+const customCheckboxComponents = {
+  Checkbox: PurpleCheckbox,
+  CheckboxIndicator: PurpleIndicator,
+};
+
+const customLabelComponents = {
+  FormLabel: CustomLabel,
+  FormMessage: CustomErrorMessage,
+};
+
+// Use spread operator to combine them
+<Checkbox
+  name="terms"
+  label="Accept terms and conditions"
+  components={{
+    ...customCheckboxComponents,
+    ...customLabelComponents,
+  }}
+/>
+\`\`\`
+
+### Key Points
+
+- Always use React.forwardRef when creating custom components
+- Make sure to spread the props to pass all necessary attributes
+- Include the ref to maintain form functionality
+- Add a displayName to your component for better debugging
+- The components prop accepts replacements for Checkbox, CheckboxIndicator, FormLabel, FormMessage, and FormDescription
+- You can mix and match different custom components as needed
+`,
       },
       source: {
         code: `
@@ -370,4 +506,4 @@ const CustomErrorMessage = React.forwardRef<
       expect(successMessage).toBeInTheDocument();
     }
   },
-};
+};
\ No newline at end of file

From 6167a4f8b5eaa956842956554e8013dbbd0ac52a Mon Sep 17 00:00:00 2001
From: "codegen-sh[bot]" <131295404+codegen-sh[bot]@users.noreply.github.com>
Date: Fri, 21 Mar 2025 00:14:17 +0000
Subject: [PATCH 10/13] Add prefix and suffix props to TextField component

---
 .../remix-hook-form/text-field.stories.tsx    | 60 +++++++++++++++++--
 packages/components/src/ui/text-field.tsx     | 46 +++++++++++---
 2 files changed, 93 insertions(+), 13 deletions(-)

diff --git a/apps/docs/src/remix-hook-form/text-field.stories.tsx b/apps/docs/src/remix-hook-form/text-field.stories.tsx
index 52cfa183..bb2bb15a 100644
--- a/apps/docs/src/remix-hook-form/text-field.stories.tsx
+++ b/apps/docs/src/remix-hook-form/text-field.stories.tsx
@@ -12,6 +12,8 @@ import { withRemixStubDecorator } from '../lib/storybook/remix-stub';
 
 const formSchema = z.object({
   username: z.string().min(3, 'Username must be at least 3 characters'),
+  price: z.string().min(1, 'Price is required'),
+  email: z.string().email('Invalid email address'),
 });
 
 type FormData = z.infer<typeof formSchema>;
@@ -26,6 +28,8 @@ const ControlledTextFieldExample = () => {
     resolver: zodResolver(formSchema),
     defaultValues: {
       username: INITIAL_USERNAME,
+      price: '10.00',
+      email: 'user@example.com',
     },
     fetcher,
     submitConfig: {
@@ -37,11 +41,28 @@ const ControlledTextFieldExample = () => {
   return (
     <RemixFormProvider {...methods}>
       <fetcher.Form onSubmit={methods.handleSubmit}>
-        <TextField name="username" label="Username" description="Enter a unique username" />
-        <Button type="submit" className="mt-4">
-          Submit
-        </Button>
-        {fetcher.data?.message && <p className="mt-2 text-green-600">{fetcher.data.message}</p>}
+        <div className="space-y-6">
+          <TextField name="username" label="Username" description="Enter a unique username" />
+          
+          <TextField 
+            name="price" 
+            label="Price" 
+            description="Enter the price" 
+            prefix="$" 
+          />
+          
+          <TextField 
+            name="email" 
+            label="Email" 
+            description="Enter your email address" 
+            suffix="@example.com" 
+          />
+          
+          <Button type="submit" className="mt-4">
+            Submit
+          </Button>
+          {fetcher.data?.message && <p className="mt-2 text-green-600">{fetcher.data.message}</p>}
+        </div>
       </fetcher.Form>
     </RemixFormProvider>
   );
@@ -155,4 +176,33 @@ export const Tests: Story = {
     await testUsernameTaken(storyContext);
     await testValidSubmission(storyContext);
   },
+};
+
+// Additional stories to showcase prefix and suffix
+export const WithPrefix: Story = {
+  name: 'With Prefix',
+  args: {
+    name: 'price',
+    label: 'Price',
+    prefix: '$',
+  },
+};
+
+export const WithSuffix: Story = {
+  name: 'With Suffix',
+  args: {
+    name: 'email',
+    label: 'Email',
+    suffix: '@example.com',
+  },
+};
+
+export const WithBoth: Story = {
+  name: 'With Prefix and Suffix',
+  args: {
+    name: 'measurement',
+    label: 'Measurement',
+    prefix: '~',
+    suffix: 'cm',
+  },
 };
\ No newline at end of file
diff --git a/packages/components/src/ui/text-field.tsx b/packages/components/src/ui/text-field.tsx
index cdab1df2..7a2dd676 100644
--- a/packages/components/src/ui/text-field.tsx
+++ b/packages/components/src/ui/text-field.tsx
@@ -1,3 +1,4 @@
+// biome-ignore lint/style/noNamespaceImport: prevents React undefined errors when exporting as a component library
 import * as React from 'react';
 import type { Control, FieldPath, FieldValues } from 'react-hook-form';
 import {
@@ -10,10 +11,23 @@ import {
   FormMessage,
 } from './form';
 import { TextInput } from './text-input';
+import { cn } from './utils';
 
-export interface TextFieldComponents extends FieldComponents {
-  Input?: React.ComponentType<React.InputHTMLAttributes<HTMLInputElement>>;
-}
+export const FieldPrefix = ({ children, className }: { children: React.ReactNode; className?: string }) => {
+  return (
+    <span className={cn("whitespace-nowrap shadow-sm font-bold rounded-md text-base flex items-center px-2.5 pr-5 -mr-2.5 bg-gray-50 text-gray-500", className)}>
+      {children}
+    </span>
+  );
+};
+
+export const FieldSuffix = ({ children, className }: { children: React.ReactNode; className?: string }) => {
+  return (
+    <span className={cn("whitespace-nowrap shadow-sm font-bold rounded-md text-base flex items-center px-2.5 pl-5 -ml-2.5 bg-gray-50 text-gray-500", className)}>
+      {children}
+    </span>
+  );
+};
 
 export interface TextFieldProps<
   TFieldValues extends FieldValues = FieldValues,
@@ -23,13 +37,13 @@ export interface TextFieldProps<
   name: TName;
   label?: string;
   description?: string;
-  components?: Partial<TextFieldComponents>;
+  components?: Partial<FieldComponents>;
+  prefix?: React.ReactNode;
+  suffix?: React.ReactNode;
 }
 
 export const TextField = React.forwardRef<HTMLDivElement, TextFieldProps>(
-  ({ control, name, label, description, className, components, ...props }, ref) => {
-    const InputComponent = components?.Input || TextInput;
-
+  ({ control, name, label, description, className, components, prefix, suffix, ...props }, ref) => {
     return (
       <FormField
         control={control}
@@ -38,7 +52,23 @@ export const TextField = React.forwardRef<HTMLDivElement, TextFieldProps>(
           <FormItem className={className} ref={ref}>
             {label && <FormLabel Component={components?.FormLabel}>{label}</FormLabel>}
             <FormControl Component={components?.FormControl}>
-              <InputComponent {...field} {...props} ref={field.ref} />
+              <div className={cn("flex items-stretch relative", {
+                "field__input--with-prefix": prefix,
+                "field__input--with-suffix": suffix,
+              })}>
+                {prefix && <FieldPrefix>{prefix}</FieldPrefix>}
+                <TextInput 
+                  {...field} 
+                  {...props} 
+                  ref={field.ref} 
+                  className={cn(props.className, {
+                    "z-10": prefix || suffix,
+                    "rounded-l-none": prefix,
+                    "rounded-r-none": suffix,
+                  })}
+                />
+                {suffix && <FieldSuffix>{suffix}</FieldSuffix>}
+              </div>
             </FormControl>
             {description && <FormDescription Component={components?.FormDescription}>{description}</FormDescription>}
             {fieldState.error && (

From 07f423c6010bb317ffa54d271570ce81e2bece67 Mon Sep 17 00:00:00 2001
From: Jake Ruesink <jaruesink@gmail.com>
Date: Thu, 20 Mar 2025 21:53:41 -0500
Subject: [PATCH 11/13] feat: add measurement field to text field stories and
 enhance TextField component

- Introduced a new measurement field in the ControlledTextFieldExample with validation.
- Updated TextField component to support prefix and suffix props with improved structure.
- Refactored FieldPrefix and FieldSuffix components for better styling and accessibility.
- Consolidated story examples into a single export for clarity and maintainability.
---
 .../remix-hook-form/text-field.stories.tsx    |  91 +++++---------
 packages/components/src/ui/text-field.tsx     | 112 +++++++++++-------
 2 files changed, 100 insertions(+), 103 deletions(-)

diff --git a/apps/docs/src/remix-hook-form/text-field.stories.tsx b/apps/docs/src/remix-hook-form/text-field.stories.tsx
index bb2bb15a..512d1f25 100644
--- a/apps/docs/src/remix-hook-form/text-field.stories.tsx
+++ b/apps/docs/src/remix-hook-form/text-field.stories.tsx
@@ -14,6 +14,7 @@ const formSchema = z.object({
   username: z.string().min(3, 'Username must be at least 3 characters'),
   price: z.string().min(1, 'Price is required'),
   email: z.string().email('Invalid email address'),
+  measurement: z.string().min(1, 'Measurement is required'),
 });
 
 type FormData = z.infer<typeof formSchema>;
@@ -30,6 +31,7 @@ const ControlledTextFieldExample = () => {
       username: INITIAL_USERNAME,
       price: '10.00',
       email: 'user@example.com',
+      measurement: '10',
     },
     fetcher,
     submitConfig: {
@@ -43,21 +45,21 @@ const ControlledTextFieldExample = () => {
       <fetcher.Form onSubmit={methods.handleSubmit}>
         <div className="space-y-6">
           <TextField name="username" label="Username" description="Enter a unique username" />
-          
-          <TextField 
-            name="price" 
-            label="Price" 
-            description="Enter the price" 
-            prefix="$" 
-          />
-          
-          <TextField 
-            name="email" 
-            label="Email" 
-            description="Enter your email address" 
-            suffix="@example.com" 
+
+          <TextField name="price" label="Price" description="Enter the price" prefix="$" />
+
+          <TextField name="email" label="Email" description="Enter your email address" suffix="@example.com" />
+
+          <TextField
+            type="number"
+            name="measurement"
+            step={0.1}
+            label="Measurement"
+            description="Enter a measurement"
+            prefix="~"
+            suffix="cm"
           />
-          
+
           <Button type="submit" className="mt-4">
             Submit
           </Button>
@@ -101,20 +103,7 @@ const meta: Meta<typeof TextField> = {
   component: TextField,
   parameters: { layout: 'centered' },
   tags: ['autodocs'],
-  decorators: [
-    withRemixStubDecorator({
-      root: {
-        Component: ControlledTextFieldExample,
-      },
-      routes: [
-        {
-          path: '/username',
-          action: async ({ request }: ActionFunctionArgs) => handleFormSubmission(request),
-        },
-      ],
-    }),
-  ],
-} satisfies Meta<typeof TextField>;
+};
 
 export default meta;
 type Story = StoryObj<typeof meta>;
@@ -168,41 +157,25 @@ const testValidSubmission = async ({ canvas }: StoryContext) => {
   expect(successMessage).toBeInTheDocument();
 };
 
-// Stories
-export const Tests: Story = {
+// Single story that contains all variants
+export const Examples: Story = {
   play: async (storyContext) => {
     testDefaultValues(storyContext);
     await testInvalidSubmission(storyContext);
     await testUsernameTaken(storyContext);
     await testValidSubmission(storyContext);
   },
+  decorators: [
+    withRemixStubDecorator({
+      root: {
+        Component: ControlledTextFieldExample,
+      },
+      routes: [
+        {
+          path: '/username',
+          action: async ({ request }: ActionFunctionArgs) => handleFormSubmission(request),
+        },
+      ],
+    }),
+  ],
 };
-
-// Additional stories to showcase prefix and suffix
-export const WithPrefix: Story = {
-  name: 'With Prefix',
-  args: {
-    name: 'price',
-    label: 'Price',
-    prefix: '$',
-  },
-};
-
-export const WithSuffix: Story = {
-  name: 'With Suffix',
-  args: {
-    name: 'email',
-    label: 'Email',
-    suffix: '@example.com',
-  },
-};
-
-export const WithBoth: Story = {
-  name: 'With Prefix and Suffix',
-  args: {
-    name: 'measurement',
-    label: 'Measurement',
-    prefix: '~',
-    suffix: 'cm',
-  },
-};
\ No newline at end of file
diff --git a/packages/components/src/ui/text-field.tsx b/packages/components/src/ui/text-field.tsx
index 7a2dd676..73a42d08 100644
--- a/packages/components/src/ui/text-field.tsx
+++ b/packages/components/src/ui/text-field.tsx
@@ -1,4 +1,3 @@
-// biome-ignore lint/style/noNamespaceImport: prevents React undefined errors when exporting as a component library
 import * as React from 'react';
 import type { Control, FieldPath, FieldValues } from 'react-hook-form';
 import {
@@ -13,69 +12,94 @@ import {
 import { TextInput } from './text-input';
 import { cn } from './utils';
 
-export const FieldPrefix = ({ children, className }: { children: React.ReactNode; className?: string }) => {
+export const FieldPrefix = ({
+  children,
+  className,
+}: {
+  children: React.ReactNode;
+  className?: string;
+}) => {
   return (
-    <span className={cn("whitespace-nowrap shadow-sm font-bold rounded-md text-base flex items-center px-2.5 pr-5 -mr-2.5 bg-gray-50 text-gray-500", className)}>
-      {children}
-    </span>
+    <div
+      className={cn(
+        'flex h-full text-base items-center pl-3 pr-0 text-gray-500 group-focus-within:text-gray-700 transition-colors duration-200 border-y border-l border-input rounded-l-md bg-background',
+        className,
+      )}
+    >
+      <span className="whitespace-nowrap">{children}</span>
+    </div>
   );
 };
 
-export const FieldSuffix = ({ children, className }: { children: React.ReactNode; className?: string }) => {
+export const FieldSuffix = ({
+  children,
+  className,
+}: {
+  children: React.ReactNode;
+  className?: string;
+}) => {
   return (
-    <span className={cn("whitespace-nowrap shadow-sm font-bold rounded-md text-base flex items-center px-2.5 pl-5 -ml-2.5 bg-gray-50 text-gray-500", className)}>
-      {children}
-    </span>
+    <div
+      className={cn(
+        'flex h-full text-base items-center pr-3 pl-0 text-gray-500 group-focus-within:text-gray-700 transition-colors duration-200 border-y border-r border-input rounded-r-md bg-background',
+        className,
+      )}
+    >
+      <span className="whitespace-nowrap">{children}</span>
+    </div>
   );
 };
 
-export interface TextFieldProps<
-  TFieldValues extends FieldValues = FieldValues,
-  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
-> extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'name'> {
-  control?: Control<TFieldValues>;
-  name: TName;
+// Create a specific interface for the input props that includes className explicitly
+type TextInputProps = React.ComponentPropsWithRef<typeof TextInput> & {
+  control?: Control<FieldValues>;
+  name: FieldPath<FieldValues>;
   label?: string;
   description?: string;
   components?: Partial<FieldComponents>;
   prefix?: React.ReactNode;
   suffix?: React.ReactNode;
-}
+  className?: string;
+};
 
-export const TextField = React.forwardRef<HTMLDivElement, TextFieldProps>(
+export const TextField = React.forwardRef<HTMLDivElement, TextInputProps>(
   ({ control, name, label, description, className, components, prefix, suffix, ...props }, ref) => {
     return (
       <FormField
         control={control}
         name={name}
-        render={({ field, fieldState }) => (
-          <FormItem className={className} ref={ref}>
-            {label && <FormLabel Component={components?.FormLabel}>{label}</FormLabel>}
-            <FormControl Component={components?.FormControl}>
-              <div className={cn("flex items-stretch relative", {
-                "field__input--with-prefix": prefix,
-                "field__input--with-suffix": suffix,
-              })}>
-                {prefix && <FieldPrefix>{prefix}</FieldPrefix>}
-                <TextInput 
-                  {...field} 
-                  {...props} 
-                  ref={field.ref} 
-                  className={cn(props.className, {
-                    "z-10": prefix || suffix,
-                    "rounded-l-none": prefix,
-                    "rounded-r-none": suffix,
+        render={({ field, fieldState }) => {
+          return (
+            <FormItem className={className} ref={ref}>
+              {label && <FormLabel Component={components?.FormLabel}>{label}</FormLabel>}
+              <FormControl Component={components?.FormControl}>
+                <div
+                  className={cn('flex group transition-all duration-200 rounded-md', {
+                    'field__input--with-prefix': prefix,
+                    'field__input--with-suffix': suffix,
+                    'focus-within:ring-2 focus-within:ring-ring focus-within:ring-offset-2 focus-within:ring-offset-background': true,
                   })}
-                />
-                {suffix && <FieldSuffix>{suffix}</FieldSuffix>}
-              </div>
-            </FormControl>
-            {description && <FormDescription Component={components?.FormDescription}>{description}</FormDescription>}
-            {fieldState.error && (
-              <FormMessage Component={components?.FormMessage}>{fieldState.error.message}</FormMessage>
-            )}
-          </FormItem>
-        )}
+                >
+                  {prefix && <FieldPrefix>{prefix}</FieldPrefix>}
+                  <TextInput
+                    {...field}
+                    {...props}
+                    ref={field.ref}
+                    className={cn('focus-visible:ring-0 focus-visible:ring-offset-0', {
+                      'rounded-l-none border-l-0': prefix,
+                      'rounded-r-none border-r-0': suffix,
+                    })}
+                  />
+                  {suffix && <FieldSuffix>{suffix}</FieldSuffix>}
+                </div>
+              </FormControl>
+              {description && <FormDescription Component={components?.FormDescription}>{description}</FormDescription>}
+              {fieldState.error && (
+                <FormMessage Component={components?.FormMessage}>{fieldState.error.message}</FormMessage>
+              )}
+            </FormItem>
+          );
+        }}
       />
     );
   },

From 40601823432f3b820e79d12efdf223932fea09af Mon Sep 17 00:00:00 2001
From: Jake Ruesink <jaruesink@gmail.com>
Date: Thu, 20 Mar 2025 22:59:05 -0500
Subject: [PATCH 12/13] refactor: improve structure of TextField component by
 consolidating FormControl and input elements

- Moved FormControl inside the main input wrapper for better organization.
- Enhanced readability by streamlining the JSX structure of the TextField component.
- Maintained existing functionality while improving code clarity.
---
 packages/components/src/ui/text-field.tsx | 24 +++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/packages/components/src/ui/text-field.tsx b/packages/components/src/ui/text-field.tsx
index 73a42d08..68088993 100644
--- a/packages/components/src/ui/text-field.tsx
+++ b/packages/components/src/ui/text-field.tsx
@@ -72,15 +72,15 @@ export const TextField = React.forwardRef<HTMLDivElement, TextInputProps>(
           return (
             <FormItem className={className} ref={ref}>
               {label && <FormLabel Component={components?.FormLabel}>{label}</FormLabel>}
-              <FormControl Component={components?.FormControl}>
-                <div
-                  className={cn('flex group transition-all duration-200 rounded-md', {
-                    'field__input--with-prefix': prefix,
-                    'field__input--with-suffix': suffix,
-                    'focus-within:ring-2 focus-within:ring-ring focus-within:ring-offset-2 focus-within:ring-offset-background': true,
-                  })}
-                >
-                  {prefix && <FieldPrefix>{prefix}</FieldPrefix>}
+              <div
+                className={cn('flex group transition-all duration-200 rounded-md', {
+                  'field__input--with-prefix': prefix,
+                  'field__input--with-suffix': suffix,
+                  'focus-within:ring-2 focus-within:ring-ring focus-within:ring-offset-2 focus-within:ring-offset-background': true,
+                })}
+              >
+                {prefix && <FieldPrefix>{prefix}</FieldPrefix>}
+                <FormControl Component={components?.FormControl}>
                   <TextInput
                     {...field}
                     {...props}
@@ -90,9 +90,9 @@ export const TextField = React.forwardRef<HTMLDivElement, TextInputProps>(
                       'rounded-r-none border-r-0': suffix,
                     })}
                   />
-                  {suffix && <FieldSuffix>{suffix}</FieldSuffix>}
-                </div>
-              </FormControl>
+                </FormControl>
+                {suffix && <FieldSuffix>{suffix}</FieldSuffix>}
+              </div>
               {description && <FormDescription Component={components?.FormDescription}>{description}</FormDescription>}
               {fieldState.error && (
                 <FormMessage Component={components?.FormMessage}>{fieldState.error.message}</FormMessage>

From 72adb4cd6c361eb681ea05026d62ee4ea71d0fb4 Mon Sep 17 00:00:00 2001
From: Jake Ruesink <jaruesink@gmail.com>
Date: Thu, 20 Mar 2025 23:24:23 -0500
Subject: [PATCH 13/13] chore: downgrade React and TypeScript dependencies to
 version 18

- Updated package.json files across apps and components to use React and TypeScript version 18.
- Adjusted @types/react and @types/react-dom to align with the downgraded React version.
- Incremented version of @lambdacurry/forms package to 0.14.0 for consistency.
---
 apps/docs/package.json           |  6 +++--
 packages/components/package.json |  6 ++---
 yarn.lock                        | 46 ++++++++++++++++++++------------
 3 files changed, 36 insertions(+), 22 deletions(-)

diff --git a/apps/docs/package.json b/apps/docs/package.json
index 7cfd2a9f..6012b2f5 100644
--- a/apps/docs/package.json
+++ b/apps/docs/package.json
@@ -24,12 +24,14 @@
     "@remix-run/testing": "^2.15.1",
     "@storybook/test-runner": "^0.20.1",
     "@storybook/testing-library": "^0.2.2",
-    "@types/react": "^19.0.0",
+    "@types/react": "^18.0.0",
+    "@types/react-dom": "^18.0.0",
     "@typescript-eslint/eslint-plugin": "^6.21.0",
     "@typescript-eslint/parser": "^6.21.0",
     "autoprefixer": "^10.4.20",
     "postcss": "^8.4.49",
-    "react": "^19.0.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
     "tailwindcss": "^3.4.17",
     "typescript": "^5.7.2",
     "vite": "^5.4.11",
diff --git a/packages/components/package.json b/packages/components/package.json
index d1624ea4..945fa190 100644
--- a/packages/components/package.json
+++ b/packages/components/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@lambdacurry/forms",
-  "version": "0.13.4",
+  "version": "0.14.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -74,14 +74,14 @@
     "@remix-run/dev": "^2.15.1",
     "@remix-run/testing": "^2.15.1",
     "@types/glob": "^8.1.0",
-    "@types/react": "^19.0.0",
+    "@types/react": "^18.0.0",
     "@typescript-eslint/eslint-plugin": "^6.21.0",
     "@typescript-eslint/parser": "^6.21.0",
     "@vitejs/plugin-react": "^4.3.4",
     "autoprefixer": "^10.4.20",
     "glob": "^11.0.0",
     "postcss": "^8.4.49",
-    "react": "^19.0.0",
+    "react": "^18.0.0",
     "tailwindcss": "^3.4.17",
     "typescript": "^5.7.2",
     "vite": "^5.4.11",
diff --git a/yarn.lock b/yarn.lock
index 9be7ebe4..b5af9221 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -1970,12 +1970,14 @@ __metadata:
     "@storybook/test": "npm:^8.4.7"
     "@storybook/test-runner": "npm:^0.20.1"
     "@storybook/testing-library": "npm:^0.2.2"
-    "@types/react": "npm:^19.0.0"
+    "@types/react": "npm:^18.0.0"
+    "@types/react-dom": "npm:^18.0.0"
     "@typescript-eslint/eslint-plugin": "npm:^6.21.0"
     "@typescript-eslint/parser": "npm:^6.21.0"
     autoprefixer: "npm:^10.4.20"
     postcss: "npm:^8.4.49"
-    react: "npm:^19.0.0"
+    react: "npm:^18.0.0"
+    react-dom: "npm:^18.0.0"
     storybook: "npm:^8.4.7"
     tailwindcss: "npm:^3.4.17"
     typescript: "npm:^5.7.2"
@@ -2008,7 +2010,7 @@ __metadata:
     "@remix-run/serve": "npm:^2.15.1"
     "@remix-run/testing": "npm:^2.15.1"
     "@types/glob": "npm:^8.1.0"
-    "@types/react": "npm:^19.0.0"
+    "@types/react": "npm:^18.0.0"
     "@typescript-eslint/eslint-plugin": "npm:^6.21.0"
     "@typescript-eslint/parser": "npm:^6.21.0"
     "@vitejs/plugin-react": "npm:^4.3.4"
@@ -2021,7 +2023,7 @@ __metadata:
     lucide-react: "npm:^0.468.0"
     next-themes: "npm:^0.4.4"
     postcss: "npm:^8.4.49"
-    react: "npm:^19.0.0"
+    react: "npm:^18.0.0"
     react-day-picker: "npm:8.10.1"
     react-hook-form: "npm:^7.53.1"
     remix-hook-form: "npm:5.1.1"
@@ -4374,12 +4376,29 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@types/react@npm:^19.0.0":
-  version: 19.0.2
-  resolution: "@types/react@npm:19.0.2"
+"@types/prop-types@npm:*":
+  version: 15.7.14
+  resolution: "@types/prop-types@npm:15.7.14"
+  checksum: 10c0/1ec775160bfab90b67a782d735952158c7e702ca4502968aa82565bd8e452c2de8601c8dfe349733073c31179116cf7340710160d3836aa8a1ef76d1532893b1
+  languageName: node
+  linkType: hard
+
+"@types/react-dom@npm:^18.0.0":
+  version: 18.3.5
+  resolution: "@types/react-dom@npm:18.3.5"
+  peerDependencies:
+    "@types/react": ^18.0.0
+  checksum: 10c0/b163d35a6b32a79f5782574a7aeb12a31a647e248792bf437e6d596e2676961c394c5e3c6e91d1ce44ae90441dbaf93158efb4f051c0d61e2612f1cb04ce4faa
+  languageName: node
+  linkType: hard
+
+"@types/react@npm:^18.0.0":
+  version: 18.3.19
+  resolution: "@types/react@npm:18.3.19"
   dependencies:
+    "@types/prop-types": "npm:*"
     csstype: "npm:^3.0.2"
-  checksum: 10c0/8992f39701fcf1bf893ef8f94a56196445667baf08fe4f6050a14e229a17aad3265ad3efc01595ff3b4d5d5c69da885f9aa4ff80f164a613018734efcff1eb8f
+  checksum: 10c0/236bfe0c4748ada1a640f13573eca3e0fc7c9d847b442947adb352b0718d6d285357fd84c33336c8ffb8cbfabc0d58a43a647c7fd79857fecd61fb58ab6f7918
   languageName: node
   linkType: hard
 
@@ -11670,7 +11689,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"react-dom@npm:^16.8.0 || ^17.0.0 || ^18.0.0":
+"react-dom@npm:^16.8.0 || ^17.0.0 || ^18.0.0, react-dom@npm:^18.0.0":
   version: 18.3.1
   resolution: "react-dom@npm:18.3.1"
   dependencies:
@@ -11787,7 +11806,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"react@npm:^16.8.0 || ^17.0.0 || ^18.0.0":
+"react@npm:^16.8.0 || ^17.0.0 || ^18.0.0, react@npm:^18.0.0":
   version: 18.3.1
   resolution: "react@npm:18.3.1"
   dependencies:
@@ -11796,13 +11815,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"react@npm:^19.0.0":
-  version: 19.0.0
-  resolution: "react@npm:19.0.0"
-  checksum: 10c0/9cad8f103e8e3a16d15cb18a0d8115d8bd9f9e1ce3420310aea381eb42aa0a4f812cf047bb5441349257a05fba8a291515691e3cb51267279b2d2c3253f38471
-  languageName: node
-  linkType: hard
-
 "read-cache@npm:^1.0.0":
   version: 1.0.0
   resolution: "read-cache@npm:1.0.0"