React Layout Primitives

Flexible and type-safe React layout components inspired by Jetpack Compose's Row and Column.

Features

• Type-safe - Full TypeScript support with exported constants for arrangement and alignment
• React 19+ - Uses modern ref-as-prop pattern
• Lightweight - Zero dependencies, minimal bundle size
• Motion compatible - Works seamlessly with Motion for animations

Requirements

• React 19.0.0 or later
• Node.js 22.0.0 or later
• TypeScript 5.7 or later (recommended)

Installation

npm install @a4banana/react-layout-primitives

Usage

Basic Usage

import {
  Row,
  Column,
  HorizontalArrangement,
  VerticalArrangement,
  HorizontalAlignment,
  VerticalAlignment,
} from '@a4banana/react-layout-primitives';

function App() {
  return (
    <Column
      gap={20}
      arrangement={VerticalArrangement.Center}
      alignment={HorizontalAlignment.Center}
    >
      <h1>Title</h1>
      <Row
        gap={10}
        arrangement={HorizontalArrangement.SpaceBetween}
        alignment={VerticalAlignment.Center}
      >
        <button>Left</button>
        <button>Right</button>
      </Row>
    </Column>
  );
}

With Motion

You can easily add animations using Motion:

npm install motion

import { motion } from 'motion/react';
import { Row, Column, HorizontalArrangement } from '@a4banana/react-layout-primitives';

// Create motion-enabled components
const MotionRow = motion.create(Row);
const MotionColumn = motion.create(Column);

function AnimatedLayout() {
  return (
    <MotionRow
      initial={{ opacity: 0, y: 20 }}
      animate={{ opacity: 1, y: 0 }}
      transition={{ duration: 0.3 }}
      gap={16}
      arrangement={HorizontalArrangement.SpaceBetween}
    >
      <MotionColumn
        initial={{ scale: 0.9 }}
        animate={{ scale: 1 }}
        gap={8}
      >
        <span>Item 1</span>
        <span>Item 2</span>
      </MotionColumn>
    </MotionRow>
  );
}

API

Row

Arranges children horizontally (flex-direction: row).

| Prop | Type | Default | Description | |------|------|---------|-------------| | arrangement | HorizontalArrangement | 'start' | Main axis distribution | | alignment | VerticalAlignment | 'stretch' | Cross axis alignment | | gap | number | 0 | Gap between children (px) | | as | ElementType | 'div' | Element to render as | | ref | Ref<HTMLElement> | - | Ref to DOM element |

Column

Arranges children vertically (flex-direction: column).

| Prop | Type | Default | Description | |------|------|---------|-------------| | arrangement | VerticalArrangement | 'top' | Main axis distribution | | alignment | HorizontalAlignment | 'stretch' | Cross axis alignment | | gap | number | 0 | Gap between children (px) | | as | ElementType | 'div' | Element to render as | | ref | Ref<HTMLElement> | - | Ref to DOM element |

Arrangement & Alignment Values

// Row arrangement (horizontal)
HorizontalArrangement.Start        // 'start'
HorizontalArrangement.End          // 'end'
HorizontalArrangement.Center       // 'center'
HorizontalArrangement.SpaceBetween // 'space-between'
HorizontalArrangement.SpaceAround  // 'space-around'
HorizontalArrangement.SpaceEvenly  // 'space-evenly'

// Column arrangement (vertical)
VerticalArrangement.Top            // 'top'
VerticalArrangement.Bottom         // 'bottom'
VerticalArrangement.Center         // 'center'
VerticalArrangement.SpaceBetween   // 'space-between'
VerticalArrangement.SpaceAround    // 'space-around'
VerticalArrangement.SpaceEvenly    // 'space-evenly'

// Row alignment (vertical)
VerticalAlignment.Top              // 'top'
VerticalAlignment.Center           // 'center'
VerticalAlignment.Bottom           // 'bottom'
VerticalAlignment.Stretch          // 'stretch'

// Column alignment (horizontal)
HorizontalAlignment.Start          // 'start'
HorizontalAlignment.Center         // 'center'
HorizontalAlignment.End            // 'end'
HorizontalAlignment.Stretch        // 'stretch'

License

MIT