Grid - Front-end Project

Overview

The Grid component provides a powerful and flexible layout system based on CSS Grid. It makes it easy to create responsive, multi-column layouts without manual media queries.

Basic Usage

import { Grid } from '@yourproject/components';

function Example() {
  return (
    <Grid cols={3}>
      <div>Item 1</div>
      <div>Item 2</div>
      <div>Item 3</div>
      <div>Item 4</div>
      <div>Item 5</div>
      <div>Item 6</div>
    </Grid>
  );
}

Column Configuration

Fixed Columns

<Grid cols={2}>
  {/* 2 equal columns */}
</Grid>

<Grid cols={4}>
  {/* 4 equal columns */}
</Grid>

Responsive Columns

<Grid 
  cols={{ 
    mobile: 1, 
    tablet: 2, 
    desktop: 4 
  }}
>
  {/* 1 column on mobile, 2 on tablet, 4 on desktop */}
</Grid>

Custom Column Widths

<Grid template="1fr 2fr 1fr">
  <div>Sidebar</div>
  <div>Main Content (2x wider)</div>
  <div>Sidebar</div>
</Grid>

Gap Spacing

Uniform Gap
Custom Gap
Row and Column Gap

<Grid cols={3} gap="md">
  {/* Equal gap between all items */}
</Grid>

<Grid cols={3} gap="20px">
  {/* Custom pixel gap */}
</Grid>

<Grid 
  cols={3} 
  rowGap="lg" 
  columnGap="sm"
>
  {/* Different gaps for rows and columns */}
</Grid>

Grid Item Spans

Control how many columns/rows individual items span:

import { Grid, GridItem } from '@yourproject/components';

function Example() {
  return (
    <Grid cols={4}>
      <GridItem colSpan={2}>
        This spans 2 columns
      </GridItem>
      <GridItem colSpan={2}>
        This spans 2 columns
      </GridItem>
      <GridItem colSpan={3}>
        This spans 3 columns
      </GridItem>
      <div>Regular item</div>
    </Grid>
  );
}

Row Spans

<Grid cols={3} rows={3}>
  <GridItem rowSpan={2}>
    This spans 2 rows
  </GridItem>
  <div>Item 2</div>
  <div>Item 3</div>
  <div>Item 4</div>
  <div>Item 5</div>
</Grid>

Alignment

Horizontal Alignment

<Grid cols={3} justifyItems="center">
  {/* Items centered horizontally */}
</Grid>

<Grid cols={3} justifyItems="start">
  {/* Items aligned to start */}
</Grid>

<Grid cols={3} justifyItems="end">
  {/* Items aligned to end */}
</Grid>

Vertical Alignment

<Grid cols={3} alignItems="center">
  {/* Items centered vertically */}
</Grid>

<Grid cols={3} alignItems="start">
  {/* Items aligned to top */}
</Grid>

<Grid cols={3} alignItems="end">
  {/* Items aligned to bottom */}
</Grid>

Props

Grid Props

number | object

Number of columns or responsive object: { mobile: 1, tablet: 2, desktop: 3 }

number

Number of rows

string

Custom grid-template-columns value (e.g., "1fr 2fr 1fr")

string

default:"md"

Gap between all items: none, sm, md, lg, xl, or custom value

string

Gap between rows (overrides gap for rows)

string

Gap between columns (overrides gap for columns)

string

Horizontal alignment: start, center, end, or stretch

string

Vertical alignment: start, center, end, or stretch

ReactNode

required

Grid items

string

Additional CSS class names

GridItem Props

number

Number of columns this item should span

number

Number of rows this item should span

number

Column line where item starts

number

Column line where item ends

number

Row line where item starts

number

Row line where item ends

ReactNode

required

Item content

TypeScript Interfaces

type ResponsiveCols = {
  mobile?: number;
  tablet?: number;
  desktop?: number;
};

interface GridProps {
  cols?: number | ResponsiveCols;
  rows?: number;
  template?: string;
  gap?: 'none' | 'sm' | 'md' | 'lg' | 'xl' | string;
  rowGap?: 'none' | 'sm' | 'md' | 'lg' | 'xl' | string;
  columnGap?: 'none' | 'sm' | 'md' | 'lg' | 'xl' | string;
  justifyItems?: 'start' | 'center' | 'end' | 'stretch';
  alignItems?: 'start' | 'center' | 'end' | 'stretch';
  children: React.ReactNode;
  className?: string;
}

interface GridItemProps {
  colSpan?: number;
  rowSpan?: number;
  colStart?: number;
  colEnd?: number;
  rowStart?: number;
  rowEnd?: number;
  children: React.ReactNode;
  className?: string;
}

Layout Examples

Card Grid

import { Grid, Card } from '@yourproject/components';

function CardGrid() {
  return (
    <Grid cols={{ mobile: 1, tablet: 2, desktop: 3 }} gap="lg">
      <Card>Card 1</Card>
      <Card>Card 2</Card>
      <Card>Card 3</Card>
      <Card>Card 4</Card>
      <Card>Card 5</Card>
      <Card>Card 6</Card>
    </Grid>
  );
}

Dashboard Layout

import { Grid, GridItem, Card } from '@yourproject/components';

function Dashboard() {
  return (
    <Grid cols={4} rows={3} gap="md">
      <GridItem colSpan={4}>
        <Card>Header Widget (Full Width)</Card>
      </GridItem>
      
      <GridItem colSpan={2} rowSpan={2}>
        <Card>Main Chart (Large)</Card>
      </GridItem>
      
      <GridItem colSpan={2}>
        <Card>Stats Widget</Card>
      </GridItem>
      
      <GridItem>
        <Card>Small Widget 1</Card>
      </GridItem>
      
      <GridItem>
        <Card>Small Widget 2</Card>
      </GridItem>
    </Grid>
  );
}

Holy Grail Layout

import { Grid, GridItem } from '@yourproject/components';

function Layout() {
  return (
    <Grid 
      template="200px 1fr 200px" 
      rows={3}
      gap="md"
      style={{ minHeight: '100vh' }}
    >
      <GridItem colSpan={3}>
        <header>Header</header>
      </GridItem>
      
      <aside>Left Sidebar</aside>
      <main>Main Content</main>
      <aside>Right Sidebar</aside>
      
      <GridItem colSpan={3}>
        <footer>Footer</footer>
      </GridItem>
    </Grid>
  );
}

Use responsive column configuration to automatically adapt your layout for different screen sizes without media queries.

For simple column layouts, Grid is often simpler than Flexbox. For single-direction layouts with dynamic sizing, consider using Flexbox instead.

Accessibility

Uses semantic HTML structure
Maintains logical reading order for screen readers
Keyboard navigation works naturally with document flow
Consider using order property carefully to avoid disconnecting visual and DOM order

​Overview

​Basic Usage

​Column Configuration

​Fixed Columns

​Responsive Columns

​Custom Column Widths

​Gap Spacing

​Grid Item Spans

​Row Spans

​Alignment

​Horizontal Alignment

​Vertical Alignment

​Props

​Grid Props

​GridItem Props

​TypeScript Interfaces

​Layout Examples

​Card Grid

​Dashboard Layout

​Holy Grail Layout

​Accessibility

Overview

Basic Usage

Column Configuration

Fixed Columns

Responsive Columns

Custom Column Widths

Gap Spacing

Grid Item Spans

Row Spans

Alignment

Horizontal Alignment

Vertical Alignment

Props

Grid Props

GridItem Props

TypeScript Interfaces

Layout Examples

Card Grid

Dashboard Layout

Holy Grail Layout

Accessibility