PageLayout

A versatile layout component supporting both flexbox and grid layouts with easy spacing, alignment, and responsive controls.

Installation

npm install @pagedotapp/page-layout

Usage

import { PageLayout } from "@pagedotapp/page-layout"

function App() {
	return (
		// Flexbox layout with gap and padding
		<PageLayout gap="md" padding="lg" align="center">
			<div>Item 1</div>
			<div>Item 2</div>
			<div>Item 3</div>
		</PageLayout>
	)
}

Props

| Prop | Type | Default | Description | | ----------------- | ------------------------------------------------------------------- | ----------- | ------------------------------------------------ | | children | ReactNode | - | Child elements to layout | | type | 'flex' \| 'grid' | 'flex' | Layout type | | gap | SpacingSize \| number | - | Gap between items (works for both flex and grid) | | padding | SpacingSize \| number | - | Padding inside the container | | margin | SpacingSize \| number | - | Margin outside the container | | Flexbox Props | | direction | 'row' \| 'column' \| 'row-reverse' \| 'column-reverse' | 'row' | Flex direction | | align | 'start' \| 'center' \| 'end' \| 'stretch' \| 'baseline' | 'stretch' | Align items on cross axis | | justify | 'start' \| 'center' \| 'end' \| 'between' \| 'around' \| 'evenly' | 'start' | Justify content on main axis | | wrap | 'nowrap' \| 'wrap' \| 'wrap-reverse' | 'nowrap' | Flex wrap behavior | | grow | boolean | false | Whether flex items should grow to fill space | | Grid Props | | columns | number \| string | 'auto' | Number of columns or custom grid template | | rows | number \| string | 'auto' | Number of rows or custom grid template | | minColumnWidth | string | - | Minimum column width for auto-fit grids | | columnGap | SpacingSize \| number | - | Column gap (overrides gap for grid) | | rowGap | SpacingSize \| number | - | Row gap (overrides gap for grid) | | Common Props | | fullWidth | boolean | false | Take full width | | fullHeight | boolean | false | Take full height | | center | boolean | false | Center the container horizontally | | as | string | 'div' | HTML element to render as | | className | string | - | Additional CSS class | | style | CSSProperties | - | Inline styles |

SpacingSize

Spacing sizes can be: 'none', 'xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl', or a number (in pixels).

Examples

Basic Flexbox Layout

// Horizontal layout with gap
<PageLayout gap="md" padding="lg">
  <Card>Card 1</Card>
  <Card>Card 2</Card>
  <Card>Card 3</Card>
</PageLayout>

// Vertical layout
<PageLayout direction="column" gap="sm">
  <Header />
  <Content />
  <Footer />
</PageLayout>

// Centered content
<PageLayout align="center" justify="center" fullHeight>
  <LoginForm />
</PageLayout>

// Space between items
<PageLayout justify="between" padding="md">
  <Logo />
  <Navigation />
  <UserMenu />
</PageLayout>

Grid Layouts

// 3-column grid
<PageLayout type="grid" columns={3} gap="lg">
  {items.map(item => <Card key={item.id} {...item} />)}
</PageLayout>

// Responsive auto-fit grid
<PageLayout
  type="grid"
  columns="auto"
  minColumnWidth="250px"
  gap="md"
>
  {products.map(product => <ProductCard key={product.id} {...product} />)}
</PageLayout>

// Custom grid template
<PageLayout
  type="grid"
  columns="200px 1fr 200px"
  gap="lg"
>
  <Sidebar />
  <MainContent />
  <Aside />
</PageLayout>

// Grid with different row and column gaps
<PageLayout
  type="grid"
  columns={4}
  columnGap="xl"
  rowGap="sm"
>
  {items.map(item => <Item key={item.id} {...item} />)}
</PageLayout>

Spacing Examples

// Using predefined spacing sizes
<PageLayout gap="lg" padding="xl" margin="md">
  <Content />
</PageLayout>

// Using numeric values (pixels)
<PageLayout gap={24} padding={32} margin={16}>
  <Content />
</PageLayout>

// Mixed spacing
<PageLayout gap="lg" padding={20}>
  <Content />
</PageLayout>

Nested Layouts

<PageLayout direction="column" fullHeight>
	<PageLayout as="header" padding="md" justify="between">
		<Logo />
		<Navigation />
	</PageLayout>

	<PageLayout as="main" style={{ flex: 1 }}>
		<PageLayout as="aside" direction="column" style={{ width: "200px" }}>
			<Menu />
		</PageLayout>

		<PageLayout direction="column" gap="lg" padding="lg" style={{ flex: 1 }}>
			<PageLayout type="grid" columns={3} gap="md">
				<StatCard />
				<StatCard />
				<StatCard />
			</PageLayout>

			<Content />
		</PageLayout>
	</PageLayout>

	<PageLayout as="footer" padding="md">
		<FooterContent />
	</PageLayout>
</PageLayout>

Semantic HTML Elements

<PageLayout as="section" direction="column" gap="lg">
	<PageLayout as="header">
		<h1>Page Title</h1>
	</PageLayout>

	<PageLayout as="article" padding="md">
		<p>Article content...</p>
	</PageLayout>

	<PageLayout as="footer">
		<p>Footer information</p>
	</PageLayout>
</PageLayout>

Responsive Behavior

The component includes built-in responsive behavior:

• On mobile (< 640px): Flex rows become columns, grids become single column
• On tablet (641px - 1024px): Grid columns are reduced proportionally

Styling

The component uses CSS modules with CSS custom properties for theming. You can override the default spacing values:

:root {
	--ui-spacing-xs: 0.25rem;
	--ui-spacing-sm: 0.5rem;
	--ui-spacing-md: 1rem;
	--ui-spacing-lg: 1.5rem;
	--ui-spacing-xl: 2rem;
	--ui-spacing-2xl: 3rem;
	--ui-spacing-3xl: 4rem;
}

Development

To run the component in development mode:

npm run storybook

To run tests:

npm test

To lint the component:

npm run lint