react-bricks

A tiny (~1 kB gzipped) factory for building composable, Tailwind-friendly React layout component systems. Define your own named layout slots once, then snap them together like bricks anywhere in your codebase.

const MobileLayout = createLayout({
  Main:    { as: 'main',   className: 'flex flex-col min-h-screen' },
  Header:  { as: 'header', className: 'sticky top-0 z-50 h-14 border-b' },
  Content: {               className: 'flex-1 overflow-y-auto px-4 py-6' },
  Footer:  { as: 'footer', className: 'h-16 border-t flex items-center px-4' },
});

function Page() {
  return (
    <MobileLayout.Main>
      <MobileLayout.Header>My App</MobileLayout.Header>
      <MobileLayout.Content>Hello world</MobileLayout.Content>
      <MobileLayout.Footer>© 2025</MobileLayout.Footer>
    </MobileLayout.Main>
  );
}

Features

• Zero config — works with plain CSS classes, Tailwind, or any utility framework
• Tailwind-aware — uses tailwind-merge to resolve class conflicts when installed
• Fully typed — TypeScript generics infer slot names from your config; invalid slot access is a compile error
• Polymorphic — every slot accepts an as prop to swap the rendered element
• Composable — extend layouts, merge layouts, override per-instance
• Tree-shakeable — dual ESM + CJS output, "sideEffects": false
• React 17+ compatible, framework agnostic (Next.js, Vite, Remix…)

Installation

npm install @babajaga3/react-bricks
# or
pnpm add @babajaga3/react-bricks

Optional peer dependencies (recommended)

For Tailwind class-conflict resolution and conditional class support:

npm install tailwind-merge clsx

The package works without them — it falls back to plain space-joined class concatenation.

API

createLayout(config, name?)

Creates a namespaced object of slot components from a config.

function createLayout<T extends LayoutConfig>(
  config: T,
  name?: string,   // shown in React DevTools as "name.SlotKey"
): Layout<T>

Config shape:

| Property | Type | Default | Description | |---------------|-----------------------|----------|------------------------------------------------------| | as | React.ElementType | 'div' | The HTML element or component this slot renders as | | className | string | '' | Default classes applied to every instance | | displayName | string | inferred | Label in React DevTools |

Slot component props:

Every generated slot accepts:

| Prop | Type | Description | |-------------|---------------------|--------------------------------------------------------------------------| | as | React.ElementType | Override the rendered element/component for this single instance | | className | string | Extra classes merged on top of defaults (via tailwind-merge if present)| | children | React.ReactNode | Slot content | | ...rest | element props | All other props forwarded to the underlying element |

extendLayout(base, extension, name?)

Creates a new layout by extending an existing one. Slots in extension override matching slots in base; new keys are added.

const DesktopLayout = extendLayout(
  MobileLayout,
  {
    // Override
    Content: { className: 'flex-1 px-8 max-w-5xl mx-auto' },
    // Add new
    Sidebar: { as: 'aside', className: 'w-64 border-r hidden lg:block' },
  },
  'DesktopLayout',
);

// DesktopLayout.Header  ← from MobileLayout (unchanged)
// DesktopLayout.Content ← overridden
// DesktopLayout.Sidebar ← new

mergeLayouts(a, b)

Merges two already-built layout objects into one. Slots in b win when keys collide.

const CardLayout = createLayout({ Root: { … }, Body: { … } });
const AppLayout  = mergeLayouts(MobileLayout, CardLayout);

// AppLayout.Main / .Header / .Content / .Footer / .Root / .Body

cn(...classes)

The internal class merger is exported in case you want to use it in your own components.

import { cn } from '@babajaga3/react-bricks';

<div className={cn('px-4', isActive && 'bg-blue-500', props.className)} />

Patterns

One layout file per breakpoint / product area

// layouts/mobile.ts
export const MobileLayout = createLayout({ … });

// layouts/desktop.ts
export const DesktopLayout = extendLayout(MobileLayout, { … });

// layouts/dashboard.ts
export const DashboardLayout = createLayout({ … });

Per-page className overrides

Default classes live in the layout definition. Instance overrides are merged at render time — Tailwind conflicts are resolved automatically.

// Default: px-4
<MobileLayout.Content className="px-8">…</MobileLayout.Content>
// Rendered: px-8  (tailwind-merge resolves the conflict)

Polymorphic slot rendering

// Render Content as <article> for semantic HTML
<MobileLayout.Content as="article" className="prose">
  <h2>…</h2>
</MobileLayout.Content>

// Render Content as a third-party motion component
import { motion } from 'motion/react';
<MobileLayout.Content as={motion.div} animate={{ opacity: 1 }}>
  …
</MobileLayout.Content>

TypeScript

Slot names are inferred from your config — accessing a slot that doesn't exist is a compile-time error.

const Layout = createLayout({ Main: { … }, Header: { … } });

<Layout.Main />    // ✅
<Layout.Footer />  // ❌ Property 'Footer' does not exist on type 'Layout<…>'

You can also export the layout type for use in other files:

import type { Layout } from '@babajaga3/react-bricks';
import type { myLayoutConfig } from './layouts/mobile';

type MobileLayoutType = Layout<typeof myLayoutConfig>;

Acknowledgement

The majority of the initial codebase has been generated with Claude Sonnet 4.6 - everything from commit 0b67bb3. I had this idea in my mind and it was a fast way to prototype it. Do what you will with that information.

License

MIT