---
name: Form Layout
description: Design recommendations for form layouts with proper field organization, validation, and user experience
---

# Form Layout Design Guidance

Prioritize clarity, efficiency, and error prevention. Forms should guide users smoothly with clear expectations, helpful feedback, and minimal friction.

## Layout & Structure

**Single Column Layout (Recommended)**

- Stack fields vertically in single column
- Optimal width: 400-600px container
- 20-40% faster completion than multi-column
- Best for mobile and desktop

**Two Column Layout (Sparingly)**

- Only for related field pairs (First Name | Last Name)
- Avoid for 6+ fields total
- Stack vertically on mobile

**Spacing**

- 16-24px between fields
- 32-48px between sections
- 8-12px for grouped related fields

**Field Width**

- Proportional to expected content length
- Short inputs: zip codes, dates
- Medium inputs: names, emails (300-400px)
- Full width: addresses, descriptions

## Labels & Fields

**Label Position: Top-Aligned (Recommended)**

- Fastest completion, fewest errors
- Best for responsive design
- Use for most forms

**Label Best Practices**

- Clear, concise, descriptive
- Sentence case
- Mark required fields with asterisk (\*)
- Help text below field, not in label
- Placeholders for examples only, not instructions

## Input Types

- **Text Input**: Short free-form text (names, email). Use appropriate type (email, tel, url)
- **Textarea**: Long text (3-5 lines minimum). Show character count if limited
- **Select**: 5-15 options. Consider searchable for 10+
- **Radio**: 2-5 mutually exclusive options, stacked vertically
- **Checkbox**: Multiple selections or boolean, stacked vertically
- **Date Picker**: Calendar for future dates, dropdowns for birth dates
- **Number Input**: Numeric with min/max/step
- **Combobox**: Long lists with search and type-ahead

## Validation & Errors

**Validation Timing**

- Validate on blur (after user leaves field)
- Don't validate while typing
- Re-validate on change after initial error
- Always validate on submit

**Error Display**

- Place errors directly below field
- Clear, actionable language ("Email must include @")
- Red border + icon + text (don't rely on color alone)
- Error summary at top on submit
- Focus first error automatically
- Keep modal open on error

**Success & Loading**

- Subtle success indicators (optional checkmark)
- Disable submit during loading
- Show loading text ("Submitting...")
- Success message or redirect after submit

## Buttons & Actions

**Button Layout**

- Primary action at end of form
- Left-align buttons (more accessible)
- [Cancel] [Previous] [Next/Submit]

**Button Styling**

- Primary: Filled/solid, action-oriented label
- Secondary: Outline/ghost for Cancel, Reset, Back
- Destructive: Red for dangerous actions

**Modal Forms - IMPORTANT**

- **Submit (success)**: MUST close modal after successful submission
- **Cancel/Close (X)/Escape**: Close without saving
- **Warn before closing** if unsaved changes exist
- **Submit (error)**: Keep modal open, show error

## Multi-Step Forms (Wizards)

**IMPORTANT: Always use Stepper component**

```tsx
import { Stepper } from "@glide/glide-ui/stepper";

const steps = [
  { label: "Account", description: "Basic information" },
  { label: "Profile", description: "Tell us about yourself" },
  { label: "Review", description: "Confirm information" },
];

<Stepper
  steps={steps}
  currentStep={currentStep}
  clickable
  onStepClick={handleStepClick}
/>;
```

**State Management**

```tsx
const [currentStep, setCurrentStep] = useState(0);
const [formData, setFormData] = useState({
  /* all fields */
});
```

**Navigation**

```tsx
const handleNext = () => {
  if (!validateCurrentStep()) return;
  if (currentStep < steps.length - 1) setCurrentStep(currentStep + 1);
};

const handlePrevious = () => {
  if (currentStep > 0) setCurrentStep(currentStep - 1);
};

const handleStepClick = (index: number) => {
  if (index < currentStep) setCurrentStep(index);
};
```

**Best Practices**

- 3-7 steps maximum (more = higher abandonment)
- Validate before advancing
- Use `error` property on Step objects for validation errors
- Allow navigation back to previous steps
- Add review/summary as final step
- Save progress (consider localStorage)
- Mobile: use `size="sm"` or `size="minimal"`

## Accessibility

- Associate labels with inputs (`for`/`id`)
- Clear focus indicators
- Keyboard navigation (Tab, Enter, Escape)
- ARIA attributes (aria-required, aria-invalid, aria-describedby)
- WCAG AA contrast minimum
- Don't rely on color alone

## Mobile

- Stack columns vertically
- 44x44px minimum touch targets
- Appropriate input types for keyboards (email, tel, number)
- Avoid horizontal scrolling
- Test on actual devices

## Other Patterns

**Inline Editing**: Edit icon, save/cancel actions, loading state
**Dynamic Forms**: Clear Add/Remove actions, animate changes
**Search/Filter**: Place at top, Enter to submit, show active filters with clear option