Layout Configuration

Configure layout dimensions and breakpoints using uizy.layout(). This method can be called at startup via start() or anytime at runtime to update layout settings.

Basic Usage

import uizy from "@dufeut/uizy";
import "@dufeut/uizy/index.css";

uizy.layout({
  layout: {
    header: 56,
    footer: 48,
    left: 240,
    right: 240,
  },
});

Full Configuration

uizy.layout({
  // Dimensions
  layout: {
    system: 24, // System bar height (px)
    header: 56, // Header height (px)
    footer: 48, // Footer height (px)
    left: 240, // Left drawer width (px)
    right: 240, // Right drawer width (px)
    leftMini: 64, // Left mini drawer width (px)
    rightMini: 64, // Right mini drawer width (px)
    drawerSpeed: 0.2, // Animation speed (seconds)
  },

  // Overlay styling
  overlay: {
    opacity: 0.45,
    color: "black",
  },

  // Responsive breakpoint
  breakpoint: {
    name: "md", // Breakpoint name (sm, md, lg, xl, xxl)
    width: 768, // Or custom width in pixels
    main: true, // Adjust main content margins
    header: true, // Adjust header margins
    top: true, // Adjust top clipping
    bottom: false, // Adjust bottom clipping
    left: true, // Reset left margins on mobile
    right: true, // Reset right margins on mobile
    drawer: true, // Close open drawers on mobile, re-open on desktop
  },
});

Configuration Options

Layout Options

Property	Type	Default	Description
system	number	0	System bar height in pixels
header	number	56	Header height in pixels
footer	number	48	Footer height in pixels
left	number	240	Left drawer width in pixels
right	number	240	Right drawer width in pixels
leftMini	number	64	Left mini drawer width in pixels
rightMini	number	64	Right mini drawer width in pixels
drawerSpeed	number	0.2	Drawer animation speed in seconds

Overlay Options

Property	Type	Default	Description
opacity	number	0.45	Overlay opacity (0-1)
color	string	"black"	Overlay background color

Breakpoint Options

Property	Type	Default	Description
name	string	""	Named breakpoint (sm, md, lg, xl, xxl)
width	number	0	Custom breakpoint width in pixels
main	boolean	true	Adjust main content margins
header	boolean	true	Adjust header margins
top	boolean	false	Adjust top clipping
bottom	boolean	false	Adjust bottom clipping
left	boolean	false	Reset left margins below breakpoint
right	boolean	false	Reset right margins below breakpoint
drawer	boolean	true	Close open drawers below breakpoint, re-open above

Named Breakpoints

Name	Width
sm	576px
md	768px
lg	992px
xl	1200px
xxl	1400px

Examples

Mobile-First Layout

uizy.layout({
  layout: {
    header: 56,
    footer: 48,
    left: 280,
    leftMini: 56,
  },
  breakpoint: {
    name: "md",
    main: true,
    header: true,
    left: true,
  },
});

Dark Overlay

uizy.layout({
  overlay: {
    opacity: 0.7,
    color: "#000",
  },
});

Slower Animations

uizy.layout({
  layout: {
    drawerSpeed: 0.4,
  },
});

Runtime Updates

Call uizy.layout() anytime to update layout configuration. Only the properties you provide will be updated; others retain their current values.

// Update header height at runtime
uizy.layout({ layout: { header: 72 } });

// Update overlay appearance
uizy.layout({ overlay: { opacity: 0.6 } });

// Update multiple settings
uizy.layout({
  layout: { left: 300, drawerSpeed: 0.3 },
  overlay: { color: "#1a1a1a" },
});

tip

Use runtime updates to implement features like collapsible headers, dynamic drawer widths, or user-customizable layouts.

Example: Collapsible Header

let headerExpanded = true;

function toggleHeader() {
  headerExpanded = !headerExpanded;
  uizy.layout({
    layout: { header: headerExpanded ? 56 : 0 },
  });
}

Example: Responsive Drawer Width

function setDrawerWidth(width) {
  uizy.layout({ layout: { left: width } });
}

// Expand drawer on hover
drawer.addEventListener("mouseenter", () => setDrawerWidth(280));
drawer.addEventListener("mouseleave", () => setDrawerWidth(64));

Using with start()

Configure layout through the unified start() method for initial setup:

uizy.start({
  layout: {
    layout: {
      header: 56,
      footer: 48,
      left: 240,
    },
    breakpoint: {
      name: "md",
      left: true,
    },
  },
  onReady: () => {
    console.log("Layout configured!");
  },
});

Ready Gate

The <uizy-app> element is hidden (visibility: hidden) until initialization completes. This prevents a layout flash where drawers briefly appear before being closed by the breakpoint logic.

• All transitions are disabled until ready (no slide-in animations on load)
• After uizy.start() runs, the uizy-ready class is added and the layout becomes visible
• If you're using only the CSS without the JS engine, add uizy-ready manually:

<uizy-app class="uizy-ready">...</uizy-app>

Drawer Responsive Behavior

When breakpoint.drawer is true (default), drawers declared with the open attribute automatically respond to viewport changes:

• Below breakpoint: Open drawers are closed (the open class is removed)
• Above breakpoint: Previously open drawers are restored
• Manual toggle: The action() method still works normally at any size

uizy.start({
  layout: {
    breakpoint: {
      name: "lg",
      drawer: true, // Drawers auto-close on mobile
      left: true,
      main: true,
      header: true,
    },
  },
});

<!-- This drawer will be open on desktop (>=992px) and closed on mobile -->
<uizy-drawer open clip-top clip-bottom>Navigation</uizy-drawer>

Generated CSS Variables

uizy.layout() injects CSS custom properties that control the layout:

Variable	Description
--uizy-system-bar-height	System bar height
--uizy-header-height	Header height
--uizy-footer-height	Footer height
--uizy-left-width	Left drawer width
--uizy-right-width	Right drawer width
--uizy-left-mini-width	Left mini drawer width
--uizy-right-mini-width	Right mini drawer width
--uizy-drawer-speed	Drawer animation duration
--uizy-overlay-color	Overlay background color
--uizy-overlay-opacity	Overlay opacity