@uwckit/layouts

Responsive layout primitives for the web — uwc-box, uwc-stack, uwc-grid, and uwc-container as framework-agnostic web components built with Lit.

Compose page structure with declarative HTML attributes instead of writing repetitive flexbox and grid CSS. Breakpoint-aware responsive props are built in.

Live Demo →

Components

| Element | Purpose | |---|---| | uwc-box | Generic block container — padding, gap, display | | uwc-stack | Flex column or row stack with spacing and alignment | | uwc-grid | CSS Grid with responsive column/row control | | uwc-container | Centered max-width page wrapper |

Installation

npm install @uwckit/layouts

pnpm add @uwckit/layouts

yarn add @uwckit/layouts

Peer dependency — lit is required.

npm install lit

Usage

Import all layout components

import '@uwckit/layouts';

Import individually (tree-shakeable)

import '@uwckit/layouts/box';
import '@uwckit/layouts/stack';
import '@uwckit/layouts/grid';
import '@uwckit/layouts/container';

Responsive syntax

All cols, rows, gap, pad, direction, and align props accept a responsive string — space-separated breakpoint:value pairs:

<!-- 1 column by default, 2 at sm, 4 at lg -->
<uwc-grid cols="1 sm:2 lg:4">...</uwc-grid>

<!-- column stack by default, row at md -->
<uwc-stack direction="column md:row">...</uwc-stack>

Breakpoints: sm (640px), md (768px), lg (1024px), xl (1280px).

uwc-box

Generic block-level container. Use it anywhere you need a padded, spaced, or display-controlled wrapper.

| Prop | Type | Default | Description | |---|---|---|---| | pad | string | '' | Inner padding — token or responsive | | gap | string | '' | Gap between children | | display | string | '' | CSS display value | | as | string | '' | Render as a semantic HTML element (main, section, article, header, footer, nav, aside) |

Padding tokens: xs sm md lg xl 2xl

<uwc-box pad="md" gap="sm">
  <p>Content A</p>
  <p>Content B</p>
</uwc-box>

<!-- Render as <main> with correct ARIA role -->
<uwc-box as="main" pad="lg">
  <h1>Page content</h1>
</uwc-box>

uwc-stack

Flexbox stack — vertical (column) or horizontal (row) with spacing, alignment, and optional wrap.

| Prop | Type | Default | Description | |---|---|---|---| | direction | string | 'column' | column or row — responsive | | gap | string | '' | Space between children — token or responsive | | align | string | '' | align-items value | | justify | string | '' | justify-content value | | wrap | boolean | false | Allow children to wrap | | pad | string | '' | Inner padding | | as | string | '' | Semantic HTML element |

<!-- Vertical stack with spacing -->
<uwc-stack gap="md">
  <uwc-card>Card one</uwc-card>
  <uwc-card>Card two</uwc-card>
  <uwc-card>Card three</uwc-card>
</uwc-stack>

<!-- Horizontal nav bar -->
<uwc-stack direction="row" gap="sm" align="center" justify="space-between" as="nav">
  <a href="/">Home</a>
  <a href="/docs">Docs</a>
  <uwc-button>Sign in</uwc-button>
</uwc-stack>

<!-- Responsive: column on mobile, row on desktop -->
<uwc-stack direction="column md:row" gap="lg" align="center">
  <img src="hero.png" alt="Hero" />
  <div>
    <h1>Hello world</h1>
    <p>Subtitle text here.</p>
  </div>
</uwc-stack>

uwc-grid

CSS Grid wrapper with responsive column and row control.

| Prop | Type | Default | Description | |---|---|---|---| | cols | string | '1' | Grid column count — responsive | | rows | string | '' | Grid row count — responsive | | gap | string | '' | Grid gap — token or responsive | | align | string | '' | align-items value | | justify | string | '' | justify-items value | | pad | string | '' | Inner padding | | as | string | '' | Semantic HTML element |

<!-- 1 → 2 → 3 column responsive grid -->
<uwc-grid cols="1 sm:2 lg:3" gap="md">
  <uwc-card>Item 1</uwc-card>
  <uwc-card>Item 2</uwc-card>
  <uwc-card>Item 3</uwc-card>
  <uwc-card>Item 4</uwc-card>
  <uwc-card>Item 5</uwc-card>
  <uwc-card>Item 6</uwc-card>
</uwc-grid>

<!-- Fixed 2-column layout -->
<uwc-grid cols="2" gap="lg" align="start">
  <aside>Sidebar</aside>
  <main>Main content</main>
</uwc-grid>

uwc-container

Centered max-width page wrapper. Keeps content readable on wide screens.

| Prop | Type | Default | Description | |---|---|---|---| | size | string | 'xl' | Max-width — xs sm md lg xl 2xl full | | center | boolean | true | Auto center with margin: 0 auto | | pad | string | '' | Inner padding |

| Size | Max width | |---|---| | xs | 480px | | sm | 640px | | md | 768px | | lg | 1024px | | xl | 1280px | | 2xl | 1536px | | full | 100% |

<uwc-container size="lg" pad="md">
  <h1>Page title</h1>
  <uwc-grid cols="1 md:2" gap="lg">
    <uwc-card>Left</uwc-card>
    <uwc-card>Right</uwc-card>
  </uwc-grid>
</uwc-container>

Semantic HTML with as

All layout components accept an as attribute to render as the correct semantic HTML element. The component sets the appropriate ARIA role automatically:

<uwc-box as="header" pad="md">...</uwc-box>   <!-- role="banner" -->
<uwc-box as="footer" pad="md">...</uwc-box>   <!-- role="contentinfo" -->
<uwc-box as="nav">...</uwc-box>               <!-- role="navigation" -->
<uwc-box as="main">...</uwc-box>              <!-- role="main" -->
<uwc-box as="aside">...</uwc-box>             <!-- role="complementary" -->
<uwc-box as="section">...</uwc-box>           <!-- role="region" -->
<uwc-box as="article">...</uwc-box>           <!-- role="article" -->

React

npm install @uwckit/layouts lit react @lit/react

Import all React wrappers

import { UwcBox, UwcStack, UwcGrid, UwcContainer } from '@uwckit/layouts/react';

Import per-component

import { UwcGrid } from '@uwckit/layouts/grid/react';
import { UwcStack } from '@uwckit/layouts/stack/react';

Example

import { UwcContainer, UwcGrid, UwcStack } from '@uwckit/layouts/react';

export default function Page() {
  return (
    <UwcContainer size="lg" pad="md">
      <UwcStack direction="column" gap="xl">
        <h1>Dashboard</h1>
        <UwcGrid cols="1 sm:2 lg:3" gap="md">
          <div>Card 1</div>
          <div>Card 2</div>
          <div>Card 3</div>
        </UwcGrid>
      </UwcStack>
    </UwcContainer>
  );
}

Vue

npm install @uwckit/layouts lit

<template>
  <uwc-container size="lg" pad="md">
    <uwc-stack direction="column" gap="xl">
      <h1>Dashboard</h1>
      <uwc-grid cols="1 sm:2 lg:3" gap="md">
        <div v-for="item in items" :key="item.id">{{ item.title }}</div>
      </uwc-grid>
    </uwc-stack>
  </uwc-container>
</template>

<script setup>
import '@uwckit/layouts';
</script>

Tip: In vite.config.ts, add compilerOptions: { isCustomElement: tag => tag.startsWith('uwc-') } to silence Vue custom element warnings.

Angular

npm install @uwckit/layouts lit

In app.module.ts, add CUSTOM_ELEMENTS_SCHEMA:

import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import '@uwckit/layouts';

@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

In your template:

<uwc-container size="lg" pad="md">
  <uwc-grid cols="1 sm:2 lg:3" gap="md">
    <div *ngFor="let item of items">{{ item.title }}</div>
  </uwc-grid>
</uwc-container>

Svelte

npm install @uwckit/layouts lit

<script>
  import '@uwckit/layouts';
</script>

<uwc-container size="lg" pad="md">
  <uwc-stack direction="column" gap="lg">
    <h1>Hello</h1>
    <uwc-grid cols="1 sm:2" gap="md">
      {#each items as item}
        <div>{item.title}</div>
      {/each}
    </uwc-grid>
  </uwc-stack>
</uwc-container>

Package exports

| Export | Description | |---|---| | @uwckit/layouts | All four components, Lit bundled — CDN or quick import | | @uwckit/layouts/box | uwc-box only (Lit external) | | @uwckit/layouts/box/react | UwcBox React wrapper | | @uwckit/layouts/stack | uwc-stack only (Lit external) | | @uwckit/layouts/stack/react | UwcStack React wrapper | | @uwckit/layouts/grid | uwc-grid only (Lit external) | | @uwckit/layouts/grid/react | UwcGrid React wrapper | | @uwckit/layouts/container | uwc-container only (Lit external) | | @uwckit/layouts/container/react | UwcContainer React wrapper |

Links

• Documentation & Live Demo
• npm
• GitHub
• Report a bug

License

MIT © UWCKit