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

Importing regular-layout registers <regular-layout>, <regular-layout-frame> and <regular-layout-tab>. Tag names that are already defined are skipped, so it's safe to import more than once. If another copy of the library loaded first, that copy's elements are used.

Manual registration

To control when (or into which CustomElementRegistry) the elements are registered, import from regular-layout/components instead. This entry point exports the same API but has no side effects:

import { defineCustomElements } from "regular-layout/components";

defineCustomElements(); // or defineCustomElements(registry)

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);
});