GitHub - texodus/regular-layout: A regular CSS `grid` container

A library for resizable & repositionable panel layouts.

Zero depedencies, pure TypeScript, tiny.
Implemented as a Web Component, interoperable with any framework.
Zero DOM mutation at runtime, implemented entirely by generating using CSS grid rules.
Supports arbitrary theming via CSS variables and ::part.
Supports async-aware container rendering for smooth animations even when rendering ovvurs over an event loop boundary.
Covered in bees.

Demo

Installation

npm install regular-layout

Quick Start

Import the library and add <regular-layout> to your HTML. Children are matched to layout slots by their name attribute.

<script type="module" src="regular-layout/dist/index.js"></script>

<regular-layout>
    <div name="main">Main content</div>
    <div name="sidebar">Sidebar content</div>
</regular-layout>

For draggable, tabbed panels, use <regular-layout-frame>:

<regular-layout>
    <regular-layout-frame name="main">
        Main content
    </regular-layout-frame>
    <regular-layout-frame name="sidebar">
        Sidebar content
    </regular-layout-frame>
</regular-layout>

Panels must be added and remove programmatically (e.g they are not auto-registered):

const layout = document.querySelector("regular-layout");

// This adds the panel definition to the layout (and makes it visible via CSS),
// but does not mutat the DOM.
layout.insertPanel("main");
layout.insertPanel("sidebar");

// This removes the panel from the layout (and hides it via CSS) but does not
// mutate the DOM.
layout.removePanel("sidebar");

Save/Restore

Layout state serializes to a JSON tree of splits and tabs, which can be persisted and restored:

const state = layout.save();
localStorage.setItem("layout", JSON.stringify(state));

// Later...
layout.restore(JSON.parse(localStorage.getItem("layout")));

restore() dispatches a cancelable regular-layout-before-resize event before applying the new state. Call preventDefault() to suspend the update, then layout.resumeResize() when ready:

layout.addEventListener("regular-layout-before-resize", (event) => {
    event.preventDefault();
    // ... prepare for resize ...
    layout.resumeResize();
});

The restore() API can also be used as an alternative to insertPanel/removePanel for initializing a <regular-layout>.

Theming

Themes are plain CSS files that style the layout and its ::part() selectors, scoped by a class on <regular-layout>. Apply a theme by adding its stylesheet and setting the class:

<link rel="stylesheet" href="regular-layout/themes/chicago.css">

<regular-layout class="chicago">
    ...
</regular-layout>

<regular-layout-frame> exposes these CSS parts:

Part	Description
`titlebar`	Tab bar container
`tab`	Individual tab
`active-tab`	Currently selected tab
`close`	Close button
`active-close`	Close button on the active tab
`container`	Content area

regular-layout.mytheme regular-layout-frame::part(titlebar) {
    background: #333;
}

regular-layout.mytheme regular-layout-frame::part(active-tab) {
    background: #fff;
    color: #000;
}

See the example themes/ directory for examples of how to write a complete theme for <regular-layout> and regular-layout-frame>.

Events

Event	Detail	Cancelable	Description
`regular-layout-before-resize`	`{ calculatePresizePaths() }`	Yes	Fired before any layout change. Cancel to suspend until `resumeResize()`.
`regular-layout-update`	`Layout`	No	Fired after layout state is updated.

layout.addEventListener("regular-layout-update", (event) => {
    console.log("New layout:", event.detail);
});