@layout-lib/react

v0.3.0

Published

a month ago

Responsive layout grid overlay for React, Next.js and Vite.

Downloads

416

0High
0Medium
0Low

amezir

react nextjs grid overlay layout responsive

@layout-lib/react

A responsive design grid overlay for development, for React, Next and Vite.

The config is versioned in your repo, the overlay follows your real breakpoints, and it leaves your production bundle untouched.

npm install -D @layout-lib/react
# or: pnpm add -D @layout-lib/react
# or: yarn add -D @layout-lib/react

import { LayoutGrid } from "@layout-lib/react";

export function App() {
  return (
    <>
      <LayoutGrid />
      {/* your app */}
    </>
  );
}

Ctrl + Shift + G shows or hides the grid. Ctrl + Shift + P hides the settings panel outright, or brings it back. The panel's own button just folds it.

Both shortcuts are rebindable to any combination:

<LayoutGrid toggleKey="alt+g" panelKey="alt+p" />

Next.js (App Router)

The package already carries the "use client" directive, so a server component renders it as is.

// app/layout.tsx
import { LayoutGrid } from "@layout-lib/react";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <LayoutGrid />
        {children}
      </body>
    </html>
  );
}

Theming the panel

Ten built-in themes, plus auto (the default), which follows the operating system live: dark, light, midnight, slate, solar, mono, blue, pink, red, green.

<LayoutGrid theme="midnight" />

Every colour can be replaced on top of the theme. Anything you leave out keeps the theme's value, and accent defaults to the grid colour:

<LayoutGrid
  theme="dark"
  palette={{
    bg: "#101828",
    field: "#1d2939",
    rail: "#344054",
    line: "#1d2939",
    text: "#f9fafb",
    muted: "#98a2b3",
    accent: "#7c5cff",
  }}
/>

Options

| Option | Default | Role | |---|---|---| | breakpoints | mobile / tablet / desktop | One grid per breakpoint. | | visible | false | Show the grid on load. | | theme | "auto" | Panel theme (see above). | | palette | {} | Override any panel colour. | | panel | true | Mount the settings panel. | | panelOpen | true | Start with the panel unfolded. | | panelShown | true | Start with the panel on screen. | | baseline | 8 | Vertical rhythm in px, or false. | | color | "#ff3b6b" | Grid colour. | | opacity | 0.12 | Column opacity. | | toggleKey | "ctrl+shift+g" | Grid shortcut, any combo: "alt+g", "cmd+shift+g"... | | panelKey | "ctrl+shift+p" | Panel hide shortcut, same format. | | cssVars | false | Mirror the active grid as --ll-* variables on <html>. | | persist | true | Remember tweaks in localStorage. | | storageKey | "layout-lib:overlay" | Storage key. | | zIndex | 2147483000 | Above everything, by default. | | container | document.body | Where the shadow host is appended. | | enabled | dev only | Force the overlay on or off. |

Your config, versioned

Tune the grid with the mouse, hit "copy config", paste the result into your repo:

// layout.config.ts
import type { Breakpoint } from "@layout-lib/core";

export const breakpoints: Breakpoint[] = [
  { name: "mobile",  minWidth: 0,    grid: { columns: 4,  gutter: 16, margin: 16, maxWidth: null } },
  { name: "tablet",  minWidth: 768,  grid: { columns: 8,  gutter: 24, margin: 32, maxWidth: null } },
  { name: "desktop", minWidth: 1280, grid: { columns: 12, gutter: 24, margin: 64, maxWidth: 1440 } },
];

<LayoutGrid breakpoints={breakpoints} />

A breakpoint applies from its minWidth upwards, and maxWidth: null keeps the grid fluid. Panel tweaks are remembered in the browser, but the code wins: edit that file and the stored settings are dropped.

The same grid in your CSS

With cssVars, the active grid is mirrored as --ll-columns, --ll-gutter, --ll-margin and --ll-max-width on <html>, live: drag a slider and any CSS reading them follows.

<LayoutGrid cssVars />

.cards {
  display: grid;
  grid-template-columns: repeat(var(--ll-columns), minmax(0, 1fr));
  gap: var(--ll-gutter);
}

Once the config is frozen, the panel's css button (or overlay.exportCss()) writes the same variables as static CSS to paste into your global stylesheet, and overlay.exportTailwind() generates a Tailwind config fragment that reads them.

Driving it from your code

import { useLayoutOverlay } from "@layout-lib/react";

const overlay = useLayoutOverlay({ panel: false });

overlay?.toggle();
overlay?.updateActiveGrid({ columns: 6 }); // only the current breakpoint
overlay?.exportConfig(); // the TypeScript file, as a string
overlay?.exportCss(); // the CSS variables, as a string

In production

The component only runs in development, and the core is pulled in through a dynamic import: the main chunk of a production build contains not a line of the overlay. Pass enabled to force the behaviour either way.

Options, breakpoint config and the full API are documented at the root of the repo: https://github.com/amezir/layout-lib

MIT.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@layout-lib/react

Next.js (App Router)

Theming the panel

Options

Your config, versioned

The same grid in your CSS

Driving it from your code

In production