Getting Started

Introduction

Installation

Migration from Flutter

Layout Primitives

Note

Introduction

Layr is a collection of Flutter-inspired layout primitives for React. It provides a declarative, type-safe API for building complex layouts without fighting CSS or memorizing flexbox properties.

If you've built UIs in Flutter, Layr will feel immediately familiar. If you haven't, Layr offers a more intuitive mental model than traditional CSS-based layout systems.

1. Why Layr?

React lacks a standardized, ergonomic layout system. Developers typically choose between:

• Raw CSS/Flexbox — Powerful but verbose, error-prone, and requires deep CSS knowledge
• Utility frameworks (Tailwind) — Fast but produces cluttered JSX and lacks semantic clarity
• Component libraries (MUI, Chakra) — Heavy, opinionated, and come with unwanted UI components

Layr sits between these extremes. It provides layout primitives only — no buttons, no forms, no theming system. Just the building blocks you need to compose layouts.

2. Core Principles

2a. Predictable Layout Behavior

Flutter's layout algorithm is deterministic and well-documented. Layr replicates this behavior in React. Every component has clear layout rules:

• Container defines bounds and decoration
• Row arranges children horizontally
• Column arranges children vertically
• Stack layers children with absolute positioning

No surprises. No magic.

2b. Zero Dependencies

Layr ships as pure React components with no external dependencies. The entire library is fully tree-shakeable — you only ship what you use.

Bundle impact:

- Container only: ~3 KB
- Full library: ~12 KB (gzipped)

2c. TypeScript-First

Every component is written in TypeScript with complete type definitions. Your editor will autocomplete props, catch errors, and show inline documentation.

Tsx

import { Container, MainAxisAlignment } from '@dynshift/layr';

// ✅ TypeScript knows all props
<Container
  width={200}
  padding={16}
  decoration={{
    color: '#1a1a1a',
    borderRadius: 12,
  }}
/>

// ❌ TypeScript catches mistakes
<Container width="invalid" /> // Error: Type 'string' is not assignable to type 'number'

3. Flutter Developers: What You Need to Know

Layr mirrors Flutter's layout API with a few React-specific adjustments:

Flutter	Layr	Notes
Container	Container	Identical API
Row	Row	Identical API
Column	Column	Identical API
Stack	Stack	Identical API
Positioned	Positioned	Identical API
SizedBox	SizedBox	Identical API
Padding	Padding	Identical API
Center	Centre or Center	Both spellings supported
Expanded		Not yet — use CSS flex or file an issue
Flexible		Not yet — use CSS flex or file an issue

4. Non-Flutter Developers: What Makes This Different

Instead of writing CSS:

Tsx

{/*Traditional CSS approach*/}
<div style={{
  display: 'flex',
  flexDirection: 'column',
  justifyContent: 'center',
  alignItems: 'flex-start',
  gap: '16px',
}}>
  <div>Item 1</div>
  <div>Item 2</div>
</div>

{/*Traditional CSS approach*/}
<div style={{
  display: 'flex',
  flexDirection: 'column',
  justifyContent: 'center',
  alignItems: 'flex-start',
  gap: '16px',
}}>
  <div>Item 1</div>
  <div>Item 2</div>
</div>

Preview

NOTE: Previews are not depiction of actual website output.

You write declarative components:

Tsx

{/*Layr approach*/}
<Column
  mainAxisAlignment={MainAxisAlignment.center}
  crossAxisAlignment={CrossAxisAlignment.start}
  spacing={16}
>
  <div>Item 1</div>
  <div>Item 2</div>
</Column>

{/*Layr approach*/}
<Column
  mainAxisAlignment={MainAxisAlignment.center}
  crossAxisAlignment={CrossAxisAlignment.start}
  spacing={16}
>
  <div>Item 1</div>
  <div>Item 2</div>
</Column>

Preview

NOTE: Previews are not depiction of actual website output.

Key differences:

- Explicit intent: mainAxisAlignment is clearer than justifyContent
- Type-safe enums: MainAxisAlignment.center prevents typos
- Spacing built-in: No need to remember CSS gap syntax

5. Quick Example

Here's a production-ready card component built with Layr:

Tsx

import { Container, Column, Row, MainAxisAlignment } from '@dynshift/layr';

export function ProfileCard({ name, role, avatar }) {
  return (
    <Centre style={{ height: '42vh' }}>
        <Container
            color="#ffffff"
            padding={24}
            decoration={{
            borderRadius: 32,
            boxShadow: [
                {
                color: '#3b82f67f',
                offset: { dx: 0, dy: 2 },
                blurRadius: 8,
                spreadRadius: 0,
                },
                {
                color: 'white',
                offset: { dx: 0, dy: 12 },
                blurRadius: 24,
                spreadRadius: -4,
                },
            ],
            }}
        >
            <Column spacing={20} crossAxisAlignment="start">
            {/* Icon Container */}
            <Container
                padding={12}
                color="#eff6ff"
                decoration={{
                borderRadius: 8,
                }}
            >
            <Column spacing={4}>
                <Container width={24} height={3} color="#3b82f6" decoration={{ borderRadius: 1.5 }} />
                <Container width={24} height={3} color="#3b82f6" decoration={{ borderRadius: 1.5 }} />
                <Container width={24} height={3} color="#3b82f6" decoration={{ borderRadius: 1.5 }} />
            </Column>
            </Container>

            {/* Content */}
            <Column spacing={8}>
                <div
                style={{
                    fontSize: 20,
                    fontWeight: 600,
                    color: '#0f172a',
                    letterSpacing: '-0.01em',
                }}
                >
                Flutter-Inspired Layouts
                </div>
                <div
                style={{
                    fontSize: 15,
                    lineHeight: '1.6',
                    color: '#64748b',
                    maxWidth: 280,
                    textAlign: "center",
                }}
                >
                Build complex layouts with predictable, type-safe primitives. No CSS debugging required.
                </div>
            </Column>

            {/* Stats Row */}
            <Row spacing={24} style={{ marginTop: 4 }}>
                <Column spacing={4}>
                <div style={{ fontSize: 18, fontWeight: 600, color: '#0f172a' }}>
                    12 KB
                </div>
                <div style={{ fontSize: 13, color: '#94a3b8' }}>
                    Gzipped
                </div>
                </Column>
                
                <Container width={1} height={40} color="#e2e8f0" />
                
                <Column spacing={4}>
                <div style={{ fontSize: 18, fontWeight: 600, color: '#0f172a' }}>
                    Zero
                </div>
                <div style={{ fontSize: 13, color: '#94a3b8' }}>
                    Dependencies
                </div>
                </Column>
            </Row>
            </Column>
        </Container>
    </Centre>
  );
}

import { Container, Column, Row, MainAxisAlignment } from '@dynshift/layr';

export function ProfileCard({ name, role, avatar }) {
  return (
    <Centre style={{ height: '42vh' }}>
        <Container
            color="#ffffff"
            padding={24}
            decoration={{
            borderRadius: 32,
            boxShadow: [
                {
                color: '#3b82f67f',
                offset: { dx: 0, dy: 2 },
                blurRadius: 8,
                spreadRadius: 0,
                },
                {
                color: 'white',
                offset: { dx: 0, dy: 12 },
                blurRadius: 24,
                spreadRadius: -4,
                },
            ],
            }}
        >
            <Column spacing={20} crossAxisAlignment="start">
            {/* Icon Container */}
            <Container
                padding={12}
                color="#eff6ff"
                decoration={{
                borderRadius: 8,
                }}
            >
            <Column spacing={4}>
                <Container width={24} height={3} color="#3b82f6" decoration={{ borderRadius: 1.5 }} />
                <Container width={24} height={3} color="#3b82f6" decoration={{ borderRadius: 1.5 }} />
                <Container width={24} height={3} color="#3b82f6" decoration={{ borderRadius: 1.5 }} />
            </Column>
            </Container>

            {/* Content */}
            <Column spacing={8}>
                <div
                style={{
                    fontSize: 20,
                    fontWeight: 600,
                    color: '#0f172a',
                    letterSpacing: '-0.01em',
                }}
                >
                Flutter-Inspired Layouts
                </div>
                <div
                style={{
                    fontSize: 15,
                    lineHeight: '1.6',
                    color: '#64748b',
                    maxWidth: 280,
                    textAlign: "center",
                }}
                >
                Build complex layouts with predictable, type-safe primitives. No CSS debugging required.
                </div>
            </Column>

            {/* Stats Row */}
            <Row spacing={24} style={{ marginTop: 4 }}>
                <Column spacing={4}>
                <div style={{ fontSize: 18, fontWeight: 600, color: '#0f172a' }}>
                    12 KB
                </div>
                <div style={{ fontSize: 13, color: '#94a3b8' }}>
                    Gzipped
                </div>
                </Column>
                
                <Container width={1} height={40} color="#e2e8f0" />
                
                <Column spacing={4}>
                <div style={{ fontSize: 18, fontWeight: 600, color: '#0f172a' }}>
                    Zero
                </div>
                <div style={{ fontSize: 13, color: '#94a3b8' }}>
                    Dependencies
                </div>
                </Column>
            </Row>
            </Column>
        </Container>
    </Centre>
  );
}

Preview

NOTE: Previews are not depiction of actual website output.

No CSS files. No class names. No flexbox debugging.

6. When to Use Layr

✅ Use Layr when:

• Building complex layouts (dashboards, admin panels, data visualisations)
• Migrating from Flutter to React
• You prefer declarative APIs over CSS
• You need consistent layout behaviour across browsers
• You're building a design system from scratch

❌ Don't use Layr when:

• You need pre-built UI components (buttons, inputs, modals)
• Your team is deeply invested in Tailwind/CSS Modules
• You need CSS-in-JS features

7. What's Included

Layr ships 8 layout primitives:

7a. Containers & Spacing

• Container — Box with decoration, padding, margin, and constraints
• SizedBox — Fixed-size constraints or spacers
• Padding — Lightweight padding wrapper

7b. Linear Layouts

• Row — Horizontal arrangement with alignment controls
• Column — Vertical arrangement with alignment controls

7c. Layered Layouts

• Stack — Absolute positioning with z-index control
• Positioned — Explicit positioning within a Stack
• PositionedFill — Shorthand for filling the entire Stack

7d. Alignment

• Centre — Centers children horizontally and vertically

8. What's Not Included

Layr is intentionally minimal. It does not provide: (atleast not yet)

• ❌ UI components
• ❌ Theming or design tokens
• ❌ State management
• ❌ Routing or navigation
• ❌ Animation utilities
• ❌ Responsive breakpoints

If you need these, combine Layr with other libraries. It plays nicely with everything.

9. Browser Support

Layr uses modern CSS and requires:

• Chrome/Edge 90+
• Firefox 88+
• Safari 14+
• React 18+ or React 19+

No polyfills required.

10. Philosophy: Layout Is Not Styling

Layr separates layout (how elements are positioned relative to each other) from styling (colors, fonts, shadows).

You handle styling however you want.

• Inline styles
• CSS Modules
• Tailwind utility classes
• Styled-components

Layr only cares about the spatial relationship between elements. Everything else is up to you.

11. Next Steps

• Installation — Add Layr to your project
• Migration from Flutter — Quick reference
• TypeScript Setup — Configure types for optimal DX

Start with Installation to get up and running in under 2 minutes.

Installation

In this document:

1. Why Layr?

2. Core Principles

2a. Predictable Layout Behavior

2b. Zero Dependencies

2c. TypeScript-First

3. Flutter Developers: What You Need to Know

4. Non-Flutter Developers: What Makes This Different

5. Quick Example

6. When to Use Layr

7. What's Included

7a. Containers & Spacing

7b. Linear Layouts

7c. Layered Layouts

7d. Alignment

8. What's Not Included

9. Browser Support

10. Philosophy: Layout Is Not Styling

11. Next Steps