Layout Grid Mode Example

Layout Grid Mode Example

The Advanced mode (grid) gives you full control over columns and breakpoints. Use this when you need precise control over the layout, such as in complex dashboards or admin forms.

Key Features

• Exact column control: Set specific number of columns per breakpoint
• Custom gap sizes: Control spacing with semantic sizes (xs, sm, md, lg, xl)
• Breakpoint override: Customize Tailwind breakpoint mappings if needed
• Semantic field widths: Still use "full", "half", "third" for fields

Example Configuration

import { FormFactory } from "@enlolab/forms";
import { z } from "zod";

const GridLayoutForm = FormFactory({
  formId: "grid-layout-example",
  layout: {
    mode: "grid",
    grid: {
      columns: {
        mobile: 1, // 1 column on mobile
        tablet: 2, // 2 columns on tablet (md:)
        desktop: 4, // 4 columns on desktop (lg:)
      },
      gap: {
        mobile: "sm", // Small gap on mobile
        tablet: "md", // Medium gap on tablet
        desktop: "lg", // Large gap on desktop
      },
    },
  },
  fields: {
    header: {
      type: "html",
      html: "<h2>Form Header</h2>",
      layout: {
        width: {
          desktop: "full", // Spans all 4 columns on desktop
        },
      },
    },
    field1: {
      type: "text",
      label: "Field 1",
      layout: {
        width: {
          desktop: "half", // Spans 2 of 4 columns on desktop
        },
      },
      schema: z.string(),
    },
    field2: {
      type: "text",
      label: "Field 2",
      layout: {
        width: {
          desktop: "half", // Spans 2 of 4 columns on desktop
        },
      },
      schema: z.string(),
    },
    field3: {
      type: "text",
      label: "Field 3",
      layout: {
        width: {
          desktop: "third", // Spans ~1.33 of 4 columns (rounded to 1)
        },
      },
      schema: z.string(),
    },
  },
});

Breakpoint Mapping

The system uses semantic breakpoints that map to Tailwind breakpoints:

• mobile: Maps to default (no prefix) - mobile devices
• tablet: Maps to md: - tablets (≥768px)
• desktop: Maps to lg: - desktop (≥1024px)

Custom Breakpoint Override

You can override the default breakpoint mappings:

layout: {
  mode: "grid",
  grid: {
    columns: {
      mobile: 1,
      tablet: 2,
      desktop: 4,
    },
    breakpoints: {
      tablet: "sm:",   // Override: use sm: instead of md:
      desktop: "xl:", // Override: use xl: instead of lg:
    },
  },
}

Gap Sizes

Gap sizes are semantic and map to Tailwind spacing:

• xs: gap-1 (0.25rem / 4px)
• sm: gap-2 (0.5rem / 8px)
• md: gap-4 (1rem / 16px)
• lg: gap-6 (1.5rem / 24px)
• xl: gap-8 (2rem / 32px)

Field Width Calculation

In grid mode, field widths are calculated based on the number of columns:

• "full": Spans all columns (e.g., 4 columns → col-span-4)
• "half": Spans half the columns (e.g., 4 columns → col-span-2)
• "third": Spans one third (e.g., 4 columns → col-span-1 or col-span-2 rounded)

Complex Example

const ComplexGridForm = FormFactory({
  formId: "complex-grid-form",
  layout: {
    mode: "grid",
    grid: {
      columns: {
        mobile: 1,
        tablet: 3,
        desktop: 6,
      },
      gap: {
        mobile: "sm",
        desktop: "md",
      },
    },
  },
  fields: {
    // Full width header
    title: {
      type: "html",
      html: "<h1>Complex Form</h1>",
      layout: {
        width: {
          desktop: "full", // 6 columns
        },
      },
    },
    // Two fields, each taking half
    firstName: {
      type: "text",
      label: "First Name",
      layout: {
        width: {
          desktop: "half", // 3 columns
        },
      },
      schema: z.string(),
    },
    lastName: {
      type: "text",
      label: "Last Name",
      layout: {
        width: {
          desktop: "half", // 3 columns
        },
      },
      schema: z.string(),
    },
    // Three fields, each taking third
    field1: {
      type: "text",
      label: "Field 1",
      layout: {
        width: {
          desktop: "third", // 2 columns
        },
      },
      schema: z.string(),
    },
    field2: {
      type: "text",
      label: "Field 2",
      layout: {
        width: {
          desktop: "third", // 2 columns
        },
      },
      schema: z.string(),
    },
    field3: {
      type: "text",
      label: "Field 3",
      layout: {
        width: {
          desktop: "third", // 2 columns
        },
      },
      schema: z.string(),
    },
  },
});

When to Use Grid Mode

✅ Use grid mode when:

• You need exact control over columns per breakpoint
• You’re building a complex dashboard or admin form
• You need specific layout requirements that auto mode can’t handle
• You want to customize breakpoint mappings

❌ Don’t use grid mode when:

• You want automatic adaptation to container width
• You’re building a standard form (contact, registration, etc.)
• You want the simplest possible configuration

Best Practices

1. Start with auto mode: Only use grid mode if you need the extra control
2. Use semantic field widths: Still use "full", "half", "third" instead of calculating colSpan manually
3. Consistent gaps: Use consistent gap sizes across breakpoints
4. Test responsiveness: Make sure your layout works well on all screen sizes
5. Document your choices: Grid mode requires more decisions, document why you chose specific values

Next Steps

• Layout Auto Mode Example - For automatic adaptation
• Layout Guide - Complete layout documentation
• Comprehensive Form Example - Full example with all features