Grid Submodule

Navigation: uCss > Source > Modules > Layout > Grid

Modules: Config | Base | Layout | Theming | Typography | Patterns | Utilities

Implicit 2D Layouts. A smart, responsive grid engine that uses auto-fit + minmax() to arrange content without manual column classes. Includes an Item Placement API (.gc-*, .gr-*), Subgrid alignment, and Recipes (masonry, carousels, dense).

📑 Contents

🌟 Overview

The Grid Submodule is the heavy lifter of the Layout module. It handles 2-Dimensional layouts (rows and columns).

Top Features

  1. Zero-Config Responsiveness: Just .g. Items wrap automatically based on their minimum width (--g-min). No media queries needed.
  2. Granular Placement Control: Span classes for every breakpoint (.gc-4, .gr-2--md) plus a full CSS-variable API (--gc, --gr, --ga, …).
  3. Fractional Layouts: .g-2-1 (⅔ + ⅓), .g-1-3 (¼ + ¾) and sidebar .sr/.sl for dashboards and docs.
  4. Subgrid Support: .sg / .sgc lets children (like cards) adopt the parent grid's tracks — perfect header/footer alignment across siblings.
  5. Fluid Gaps: Gaps use clamp() — they shrink on mobile and grow on desktop automatically.
  6. Smart Recipes: Masonry galleries, horizontal carousels with snap scrolling, dense packing — pre-packaged.

[!NOTE] Implicit vs Explicit Explicit: "I want 3 columns." Implicit: "I want columns at least 256px wide." uCss defaults to Implicit because it is more robust against content changes.

🤯 Philosophy

The Death of the 12-Column Grid

We don't want to calculate 100% / 12 * 4 anymore. That logic belongs to 2013.

  • Old Way: <div class="col-xs-12 col-md-6 col-lg-4">.
  • uCss Way: <ul class="g">…</ul> (fluid by default) or --g-min: 300px.

The uCss approach declares the intent (needs 300px per item) rather than the implementation (takes 4 columns).

Implicit Resilience

Implicit grids are resilient. Add a 4th item to a 3-column explicit grid and it breaks or looks weird. Add it to an implicit grid and it just wraps to a new row. This fail-safe nature makes uCss grids perfect for CMS content where editors control the item count.

🚀 Getting Started

The "Clicked" Moment (Mobile First)

  1. <ul class="g">.
  2. <li>Item 1</li> — three of them.
  3. It's a 3-column layout on desktop.
  4. Resize: 2-column, then 1-column.
  5. Zero media queries were written.

5-Second Grid System

<ul class="g">
  <li>1</li>
  <li>2</li>
  <li>3</li>
</ul>

ul.g / ol.g get list resets for free (no bullets, no padding, no flow margins).

Overriding the Floor

<!-- Override the minimum item width globally on this grid -->
<ul class="g" style="--g-min: 100px;">…</ul>

💡 How to Use It (Perfect Scenarios)

Each scenario shows an Emmet abbreviation → the expanded HTML → why it's the right choice. The canonical uCss card grid is ul.g > li.clk > article.crd — the li is the grid item (gets the item API + list reset), .clk makes the whole card clickable, and .crd is the card pattern.

1. The Everyday Auto-Fit Card Grid

Emmet: ul.g>li.clk*3>article.crd

<ul class="g">
  <li class="clk"><article class="crd"><h3>Title</h3><p>Body…</p><a>Read more</a></article></li>
  <li class="clk"><article class="crd"><h3>Title</h3><p>Body…</p><a>Read more</a></article></li>
  <li class="clk"><article class="crd"><h3>Title</h3><p>Body…</p><a>Read more</a></article></li>
</ul>

Why: fluid 3 → 2 → 1 columns with no classes; perfect for posts, products, features.

2. Fixed / Responsive Columns

Emmet: ul.g.g-3>li.clk*6>article.crd · ul.g.g-4--lg.g-2--md.g-1--sm>li.clk*8>article.crd

<ul class="g g-3">
  <li class="clk"><article class="crd">…</article></li>  <!-- 6× -->
</ul>

<ul class="g g-4--lg g-2--md g-1--sm">
  <li class="clk"><article class="crd">…</article></li>  <!-- 8× -->
</ul>

Why: .g-3 is 3/2/1 out of the box; the responsive stack is 4 → 2 → 1 per breakpoint.

3. Asymmetric (Editorial)

Emmet: article.g.g-2-1>(div+figure)

<article class="g g-2-1">
  <div>…text column…</div>
  <figure>…media column…</figure>
</article>

Why: ⅔ + ⅓ split for article + media; collapses to a single column on tablet/mobile. Use div.g.g-2-1>(div+aside) for dashboards.

4. Sidebar Layout

Emmet: div.g.sr>(main+aside)

<div class="g sr">
  <main>…content…</main>
  <aside>…sidebar…</aside>
</div>

Why: content auto-sizes, sidebar minmax(16rem, 25%). .sl mirrors it left.

5. Subgrid — Aligned Card Rows (Holy Grail)

Emmet: ul.g.g-3>(li.clk>article.crd.sg.gr-3>(header+div+footer))*3

<ul class="g g-3">
  <li class="clk"><article class="crd sg gr-3"><header>Title</header><div>Body</div><footer>CTA</footer></article></li>
  <li class="clk"><article class="crd sg gr-3"><header>Much longer title…</header><div>Body</div><footer>CTA</footer></article></li>
  <li class="clk"><article class="crd sg gr-3"><header>Title</header><div>Body</div><footer>CTA</footer></article></li>
</ul>

Why: every card's <header> / <div> / <footer> align to the same three rows — titles, bodies and CTA buttons line up regardless of content length.

Emmet: ul.g.g-3>(li.clk.gc-2--lg>article.crd+li.clk+li.clk)

<ul class="g g-3">
  <li class="clk gc-2--lg"><article class="crd">Featured (2 cols on lg)</article></li>
  <li class="clk"><article class="crd">…</article></li>
  <li class="clk"><article class="crd">…</article></li>
</ul>

Why: one hero item spans 2 columns on desktop, normal grid on tablet/mobile.

Emmet: ul.g.g-ms>(li>figure)*6

<ul class="g g-ms">
  <li><figure>…</figure></li>  <!-- 6×, variable heights -->
</ul>

Why: variable-height masonry via CSS multi-column (with a native grid-lanes upgrade when supported). Ideal for galleries.

Emmet: ul.g.scr-3>li.clk*6>article.crd (exact) · ul.g.crs-3>li.clk*6>article.crd (peek) · ul.g.crs-3.ctrs>li.clk*6>article.crd (native buttons)

<ul class="g scr-3">
  <li class="clk"><article class="crd">…</article></li>  <!-- exactly 3 visible -->
</ul>

<ul class="g crs-3">
  <li class="clk"><article class="crd">…</article></li>  <!-- 3 + next peeking -->
</ul>

Why: .scr-N = exact edge-to-edge fits (steps, tiers); .crs-N = peeking cards signaling scrollability (products); add .ctrs for native ::scroll-button() arrows where supported.

9. Dense Packing

Emmet: ul.g.g-4.dense>li*8

<ul class="g g-4 dense">
  <li>…</li>  <!-- 8×, varied sizes -->
</ul>

Why: grid-auto-flow: dense backfills holes with smaller items — great for mosaics and mixed-size media grids.

In a Real Page

<section class="s">
  <div>
    <header>…</header>
    <ul class="g g-3">
      <li class="clk"><article class="crd">…</article></li>
      <li class="clk"><article class="crd">…</article></li>
      <li class="clk"><article class="crd">…</article></li>
    </ul>
  </div>
</section>

Only the ul.g is the grid — the section/container/header just show where it nests.

📦 Installation & Stats

Bundle Stats

This Submodule is part of layout.css.

File Full (Raw) Clean Min Gzip Brotli
grid/base.css 10.4 KB 8.0 KB 6.1 KB 1.9 KB 1.5 KB
grid/columns.css 10.7 KB 10.4 KB 9.0 KB 1.2 KB 1.0 KB
grid/subgrid.css 9.3 KB 8.7 KB 7.2 KB 1.0 KB 0.9 KB
grid/item/base.css 4.7 KB 3.9 KB 3.1 KB 0.8 KB 0.7 KB
grid/item/placement.css 3.9 KB 3.5 KB 2.8 KB 0.7 KB 0.5 KB
grid/recipes/masonry.css 3.2 KB 1.4 KB 1.1 KB 1.1 KB 0.9 KB
grid/recipes/scroll.css 11.1 KB 9.8 KB 8.8 KB 2.1 KB 1.7 KB
grid/recipes/misc.css 0.5 KB 0.4 KB 0.3 KB 0.3 KB 0.2 KB

Stats reflect the last verified build from dist/latest. Run npm run build:latest to regenerate.

HTML Snippets

Since this is a nested module, it is included in layout.min.css:

<link rel="preconnect" href="https://ucss.unqa.dev">
<link rel="stylesheet" href="https://ucss.unqa.dev/latest/lib/layout.min.css">

📂 Files Reference

File Description Download
base.css Engine. The .g class and the auto-fit math. Defines --g-min, --g-g, container-query breakpoints. src
columns.css Explicit. Fixed column presets (.g-2….g-12), fractional layouts (.g-2-1, .g-1-3, …) and sidebars (.sr, .sl). src
subgrid.css Nesting. .sg / .sgr set grid-template-rows: subgrid; .sgc sets grid-template-columns: subgrid (guarded by @supports). src
item/base.css Item API. CSS-variable hooks on every grid item (--gc, --gr, --ga, --gi-*). src
item/placement.css Span Classes. .gc-1….gc-12, .gr-1….gr-5, .gc-f, .gr-f + responsive variants. src
recipes/masonry.css Gallery. .g-ms / .g-gl — CSS multi-column fallback with a native grid-lanes upgrade. src
recipes/scroll.css Scroll. .scr-N exact-fit and .crs-N peeking carousels with snap physics. src
recipes/misc.css Misc. .dense (auto-flow dense), .inline (inline-grid), list resets. src

🧠 Deep Dive

1. The Auto-Fit Algorithm

The magic formula:

grid-template-columns: repeat(auto-fit, minmax(var(--g-min), 1fr))
  1. auto-fit: creates as many columns as fit the available space.
  2. minmax: enforces a minimum item-width floor. Default: clamp(16rem, calc(16rem + 4 * (100cqi - 33rem) / 55), 20rem) (≈256–320px).
    • Container is 1024px and --g-min is 200px → 5 columns.
    • Container is 500px and --g-min is 200px → 2 columns.
  3. 1fr: distributes remaining space equally.

Override per grid:

<ul class="g" style="--g-min: 200px; --g-g: 1rem;">…</ul>

2. Subgrid Magic (.sg)

Subgrid is one of the most important CSS layout features of the decade.

Problem: A row of cards. Card A has a short title, card B a long one — bodies start at different heights, CTAs drift.

Solution: the parent defines rows, cards adopt them:

<ul class="g g-3">
  <li class="clk"><article class="crd sg gr-3">
    <header>Short title</header>
    <div>Body</div>
    <footer>CTA</footer>
  </article></li>
  <li class="clk"><article class="crd sg gr-3">
    <header>A much longer multi-line title here!</header>
    <div>Body</div>
    <footer>CTA</footer>
  </article></li>
</ul>
Class Sets Purpose
.sg, .sgr, .subgrid, .subrow grid-template-rows: subgrid Align header/body/footer rows across cards
.sgc, .subcol grid-template-columns: subgrid Align columns across children

Both are applied inside @supports, so browsers without subgrid fall back to normal block flow.

3. Asymmetrical Grids (.g-2-1)

Sometimes you don't want equal columns. Available ratios:

Class Columns Breakdown
.g-2-1 3 2fr + 1fr
.g-1-2 3 1fr + 2fr
.g-3-1 4 3fr + 1fr
.g-1-3 4 1fr + 3fr
.g-2-3 5 2fr + 3fr
.g-3-2 5 3fr + 2fr
.sr 2 content + sidebar (minmax(16rem, 25%))
.sl 2 sidebar + content

All asymmetric layouts collapse to 1 column on tablet (--md) and below.

4. Density Engine (.dense)

By default, CSS Grid leaves holes when an item is too big to fit the remaining space in a row. Adding .dense enables grid-auto-flow: dense so the browser backfills those holes with smaller items.

<ul class="g g-4 dense">
  <li class="gc-2 gr-2">Big featured item</li>
  <li>…</li>
  <li>…</li>
  <li>…</li>  <!-- auto-backfills -->
</ul>

⚙️ Base Grid & Modifiers

The .g class governs the entire grid. It integrates with a parent container-query context established automatically by any non-grid ancestor.

Container Breakpoints

Responsive classes use the --sm / --smd / --md / --mdl / --lg suffix system, driven by container queries:

Suffix Container width
--sm < 30rem (480px)
--smd < 60rem (small + medium)
--md 30rem – 60rem (480–960px)
--mdl > 30rem (medium + large)
--lg > 60rem (960px+)

An extra-small behavior also kicks in at ≤ 20rem (320px): the minimum item width shrinks so items still fit.

Fixed Column Presets

Class Desktop (lg) Tablet (md) Mobile (sm)
.g-1 1 col 1 col 1 col
.g-2 2 cols 1 col 1 col
.g-3 3 cols 2 cols 1 col
.g-4 4 cols 2 cols 1 col
.g-5 5 cols 3 cols 1 col
.g-6 6 cols 4 cols 2 cols
.g-8 8 cols 4 cols 2 cols
.g-9 9 cols 6 cols 3 cols
.g-12 12 cols 6 cols 3 cols

Use responsive suffixes for per-breakpoint control: .g-3--lg, .g-2--md, .g-1--sm.

🧩 Grid Item Placement

Located in grid/item/. Every element inside .g (or .sg, .sgr, .sgc) automatically inherits this API.

Column & Row Spans — Utility Classes

All utilities support --sm, --smd, --md, --mdl, --lg responsive suffixes:

Column Classes Row Classes Effect
.gc-1 … .gc-12 .gr-1 … .gr-5 grid-column / grid-row: span N
.gc-f .gr-f full: 1 / -1
.gc-2--lg .gr-3--md breakpoint-specific spans 
<ul class="g g-3">
  <li class="clk gc-2--lg"><article class="crd">Featured (spans 2 on lg)</article></li>
  <li class="clk"><article class="crd">Normal</article></li>
  <li class="clk"><article class="crd">Normal</article></li>
</ul>

CSS Variable API (Inline Control)

Every grid item exposes these variables at every breakpoint:

Variable Breakpoint variants Controls
--gc / --gi-col --gc--sm, --md, --lg grid-column
--gr / --gi-row --gr--sm, --md, --lg grid-row
--ga / --area --ga--sm, --md, --lg grid-area
--as / --gi-as --gi-as--sm, --md, --lg align-self
--js / --gi-js --gi-js--sm, --md, --lg justify-self
--o / --gi-o --gi-o--sm, --md, --lg order
--gi-mbs — min-block-size
--gi-mis — min-inline-size 
<!-- Inline CSS-variable override — no utility class needed -->
<li class="clk" style="--gc--lg: span 3; --as--sm: center;"><article class="crd">…</article></li>

🍲 Grid Recipes

1. Masonry Layout

A dense variable-height gallery. Uses the CSS multi-column fallback with a native grid-lanes upgrade when supported.

  • Classes: .g-ms, .g-gl, .grid-lanes · Attributes: [data-recipe~="masonry|gallery|grid-lanes|lanes"]
  • Native Upgrade: @supports (display: grid-lanes) → display: grid-lanes.
  • Fallback: column-width: var(--g-min) with break-inside: avoid on children. column-count is deliberately auto (via --g-cols: initial) so column-width drives the column count.
<ul class="g g-ms">
  <li><figure>Short card</figure></li>
  <li><figure>A longer card with more content…</figure></li>
  <li><figure>Short again</figure></li>
</ul>

2. Scrollable Grids (Carousels)

A single-axis horizontal scroll layout with native CSS scroll snapping.

  • Classes: .slr, .scr(-1…4), .crs(-1…4), .ctrs · Attributes: [data-recipe~="slider|scroll|scroll-N|carousel|carousel-N"]

Exact Fit Modifiers (.scr-N)

Shows exactly N items at once, mathematically subtracting gap widths.

Class Items visible
.slr / .slider / .scr / .scr-1 1 (full width)
.scr-2 2 exact
.scr-3 3 exact
.scr-4 4 exact

Peek Modifiers (.crs-N)

Shows N items with the next one peeking to signal scrollability.

Class Items + peek
.crs-1 1 card + peek
.crs-2 2 cards + peek
.crs-3 3 cards + peek
.crs-4 4 cards + peek 
<!-- 3 cards visible, 4th peeking from the right -->
<ul class="g crs-3">
  <li class="clk"><article class="crd">Slide 1</article></li>
  <li class="clk"><article class="crd">Slide 2</article></li>
  <li class="clk"><article class="crd">Slide 3</article></li>
  <li class="clk"><article class="crd">Slide 4 (peeking)</article></li>
</ul>

Add .ctrs (or .scr-ctrs / .crs-ctrs) to enable native ::scroll-button() arrows where supported.

3. Dense & List Integration

  • .dense / .g-d: grid-auto-flow: dense — backfills empty holes with smaller items.
  • .inline / .g-i: display: inline-grid.
  • ul.g / ol.g: automatically removes list-style, padding-inline-start, and flow margins.

📍 Reference: Content Map

Base Classes

Class Alias Description
.g [data-display~="grid"] Auto-fit grid. Default min ≈ 256–320px.
.dense .g-d Enable dense packing (backfills holes).
.inline .g-i display: inline-grid.

Column Presets

Class Desktop Tablet Mobile
.g-1 1 col 1 col 1 col
.g-2 2 cols 1 col 1 col
.g-3 3 cols 2 cols 1 col
.g-4 4 cols 2 cols 1 col
.g-6 6 cols 4 cols 2 cols
.g-12 12 cols 6 cols 3 cols
.g-2-1 ⅔ + ⅓ 1 col 1 col
.g-1-2 ⅓ + ⅔ 1 col 1 col
.g-3-1 ¾ + ¼ 1 col 1 col
.g-2-3 ⅖ + ⅗ 1 col 1 col
.sr sidebar right stacks stacks
.sl sidebar left stacks stacks

Gap Overrides

Gaps are fluid clamp() values by default. Override inline:

Variable Controls
--g-g all gaps (row + column)
--g-cg column gap only
--g-rg row gap only

Per-breakpoint variants: --g-g--sm, --g-cg--md, --g-rg--lg.

Subgrid Modifiers

Class Aliases Effect
.sg .subgrid, .sgr, .subrow grid-template-rows: subgrid
.sgc .subcol grid-template-columns: subgrid

All support responsive variants: .sg--md, .sgc--lg, etc.

Item Placement Classes

Column span Row span Full
.gc-1 … .gc-12 .gr-1 … .gr-5 .gc-f / .gr-f

Add --sm, --smd, --md, --mdl, --lg suffixes for breakpoint control.

💡 Best Practices & Customization

  • Use ul.g / ol.g for repetitive card/content grids — list resets come free and each li is a grid item.
  • Use .g-ms for galleries, .scr-N for steps/tiers, .crs-N for product carousels.
  • Use .sr / .sl for docs and blog layouts; .g-2-1 for editorial article + figure.
  • Combine with Flex: a card is a Grid item, but its inner content is Flex.

🔧 For Developers

Extending Columns

To add a custom .g-7:

.g-7 {
  --g-cols--lg: 7;
  --g-cols--md: 4;
  --g-cols--sm: 2;
  --g-min--lg: 0px; /* Force fit — don't apply the floor on large screens */
}

Customizing Min-Width Per Grid

<!-- Breaks at 120px instead of the default ~256px -->
<ul class="g" style="--g-min: 120px">…</ul>

Named Grid Areas

<div class="g" style="
  --gta: 'hero hero sidebar'
         'main main sidebar'
         'footer footer footer';
  --gtr: 200px 1fr auto;
  --gtc: 1fr 1fr 300px;
">
  <header style="--ga: hero">Hero</header>
  <main style="--ga: main">Main</main>
  <aside style="--ga: sidebar">Sidebar</aside>
  <footer style="--ga: footer">Footer</footer>
</div>

Navigation: uCss > Source > Modules > Layout > Grid

Modules: Config | Base | Layout | Theming | Typography | Patterns | Utilities

Back to top

License: MPL-2.0 Copyright: © 2026 Shukhrat (Alive 🜁) ⤻ UNQA

🗺️ Visual Map

src/lib/
├── config/                  # 1. CONFIGURATION (The Brain)
│   ├── root/                #    - Semantic Modules
│   │   ├── colors.css       #    - Palettes & Themes
│   │   ├── typography.css   #    - Fonts & Scales
│   │   ├── layout.css       #    - Radius & Spacing
│   │   └── patterns.css     #    - Component Vars
│   ├── adapters/            #    - CMS Adapters
│   │   ├── blocksy.css      #    - Blocksy Theme
│   │   └── gutenberg.css    #    - WordPress Block Editor
│   └── root.css             #    - Entry Point
│
├── base/                    # 2. BASE (The Foundation)
│   ├── html/                #    - HTML Engine
│   │   ├── reset.css        #    - Normalization
│   │   ├── typography.css   #    - Text Defaults
│   │   ├── flow.css         #    - Smart Flow Engine
│   │   ├── lists.css        #    - List Styles
│   │   ├── forms.css        #    - Input Styling
│   │   └── helpers.css      #    - HTML Utilities
│   └── html.css             #    - Entry Point
│
├── layout/                  # 3. LAYOUT (The Skeleton)
│   ├── grid/                #    <== YOU ARE HERE
│   │   ├── base.css         #    - Core `.g` engine & container queries
│   │   ├── columns.css      #    - Explicit presets & asymmetric layouts
│   │   ├── subgrid.css      #    - `.sg` / `.sgc` subgrid alignment
│   │   ├── item/
│   │   │   ├── base.css     #    - CSS variable API for all grid items
│   │   │   └── placement.css#    - `.gc-*` / `.gr-*` span utility classes
│   │   └── recipes/
│   │       ├── masonry.css  #    - `.g-ms` / `.g-gl` masonry gallery
│   │       ├── scroll.css   #    - `.scr` / `.crs` carousels with snap
│   │       └── misc.css     #    - `.dense`, `.inline`, list resets
│   ├── flex/                #    - Flex Engine
│   ├── section/             #    - Structural Sections
│   └── query.css            #    - Container Query Helper (`.cq` / `.cquery`)
│
├── patterns/                # 4. PATTERNS (The Components)
│   ├── button/
│   ├── card/
│   └── ...
│
├── theming/                 # 5. THEMING (The Skin)
│   ├── set/
│   └── ...
│
├── typography/              # 6. TYPOGRAPHY (The Voice)
│   ├── title.css
│   ├── text.css
│   └── controls/
│
└── utilities/               # 7. UTILITIES (The Tools)
    ├── display.css
    ├── position.css
    ├── size.css
    └── ...