Docs

Main site

Installation Browser support Extend config MCP server
Validation Page speed testing Responsive design
Accordion Aspect Ratio Avatar Badge Banner Bento Grid Blockquote Breadcrumbs Button Callout Card Drawer Dropdown Link Modal Navbar Navblock Pagination Popover Progress Separator Tabs Timeline Toast Tooltip
Checkbox Datepicker File upload Form field Input Label OTP Radio Range Select Textarea Toggle
Header Footer
Accordion Auth Checkbox & Radio Content Drawers Features Modals Statistics & Metrics Teams
Address Contact number Currency symbol Date Emirates ID Name
Close
Home Documentation Components Bento Grid

Bento Grid

A Bento Grid arranges aegov-card elements into a balanced-but-non-uniform "bento box" layout. It owns the column count, the gap between tiles, and the responsive stacking behaviour, while each card declares its own column and row span via simple data attributes.

Layout
Status
Active
Introduced
4.0.x
View source code

Responsive columns

The cols property accepts a single positive integer, or a Tailwind-style responsive string such as cols="1 md:2 lg:4". Values are clamped to 1–12. Start the base token at 1 so tiles stack in one column on narrow viewports.

One

Two

Three

Four

Five

Six

<aegov-bento-grid cols="1 md:2 lg:3" gap="md">
  <aegov-card appearance="light"><p class="text-base">One</p></aegov-card>
  <aegov-card appearance="light"><p class="text-base">Two</p></aegov-card>
  <aegov-card appearance="light"><p class="text-base">Three</p></aegov-card>
  <aegov-card appearance="light"><p class="text-base">Four</p></aegov-card>
  <aegov-card appearance="light"><p class="text-base">Five</p></aegov-card>
  <aegov-card appearance="light"><p class="text-base">Six</p></aegov-card>
</aegov-bento-grid>

Per-card spans

Each direct child can opt into a larger footprint with data-col-span and data-row-span (both 1–12 / 1–6 respectively, and both clamped to the grid's own resolved cols/row limits). Unset attributes fall back to span 1.

Featured

A larger tile draws the eye to the most important content.

Quick stat

Quick stat

Wide footer tile

<aegov-bento-grid cols="1 md:3" gap="md">
  <aegov-card data-col-span="2" data-row-span="2" appearance="light" hover="standard">
    <h3 class="font-bold text-lg">Featured</h3>
    <p class="text-base mt-2">A larger tile draws the eye to the most important content.</p>
  </aegov-card>
  <aegov-card appearance="light"><p class="text-base">Quick stat</p></aegov-card>
  <aegov-card appearance="light"><p class="text-base">Quick stat</p></aegov-card>
  <aegov-card data-col-span="3" appearance="light"><p class="text-base">Wide footer tile</p></aegov-card>
</aegov-bento-grid>

Gap

The gap property accepts a named size and supports responsive syntax. none=0, xs=0.25rem, sm=0.5rem, md=1rem (default), lg=1.5rem, xl=2rem.

gap="sm"

One

Two

gap="md" (default)

One

Two

gap="lg"

One

Two

<aegov-bento-grid cols="2" gap="sm">…</aegov-bento-grid>
<aegov-bento-grid cols="2" gap="md">…</aegov-bento-grid>
<aegov-bento-grid cols="2" gap="lg">…</aegov-bento-grid>

Auto-flow — dense vs. row

The flow property controls how the browser places tiles when spans leave gaps. dense (default) back-fills earlier holes with later, smaller tiles — the classic bento packing. row keeps strict DOM order — a tile that doesn't fit the current row pushes to the next, leaving the gap behind it. In this 3-column example, A and B both span 2 columns, so B cannot fit next to A on row one and moves to row two — leaving a 1-column gap in row one. dense fills that gap with C (the next tile that fits); row leaves the gap empty and places C strictly after B instead.

flow="dense" (default) — back-fills holes

A (span 2)

B (span 2)

C

D

flow="row" — strict order, may leave gaps

A (span 2)

B (span 2)

C

D

<aegov-bento-grid cols="3" gap="md" flow="dense">
  <aegov-card data-col-span="2" appearance="light">A (span 2)</aegov-card>
  <aegov-card data-col-span="2" appearance="light">B (span 2)</aegov-card>
  <aegov-card appearance="light">C</aegov-card>
  <aegov-card appearance="light">D</aegov-card>
</aegov-bento-grid>

RTL support

The grid uses no directional CSS of its own — it renders through native CSS Grid, so column order mirrors automatically inside a dir="rtl" ancestor exactly as the browser's own grid direction handling dictates. No extra configuration is required.

بطاقة رئيسية

تمتد هذه البطاقة عبر عمودين لجذب الانتباه.

إحصائية سريعة

<div dir="rtl">
  <aegov-bento-grid cols="1 md:3" gap="md">
    <aegov-card data-col-span="2" appearance="light">
      <h3 class="font-bold text-lg">بطاقة رئيسية</h3>
      <p class="text-base mt-2">تمتد هذه البطاقة عبر عمودين لجذب الانتباه.</p>
    </aegov-card>
    <aegov-card appearance="light"><p class="text-base">إحصائية سريعة</p></aegov-card>
  </aegov-bento-grid>
</div>

Usage

Here is the recommended usage of a bento grid on any website or application. These are recommended usage guides, however the developer must use the best practices of web and application development to accurately use this component.

Reserve the largest tile for the single most important item

A bento layout works because it establishes a visual hierarchy. Give one or two tiles a real data-col-span/data-row-span and leave the rest at the default 1×1 — spanning every tile defeats the purpose.

Start cols at 1 for mobile

Set the base token to 1 (e.g. cols="1 md:2 lg:4") so tiles stack in a single readable column on narrow viewports, then step up at wider breakpoints.

Use flow="row" when reading order must match visual order

dense (the default) can visually reorder tiles ahead of their DOM position to fill gaps. If the tiles tell a sequential story, switch to flow="row" so what a sighted user sees left-to-right matches what a screen reader announces.

Do not use a bento grid for a simple, uniform card list

If every tile is meant to be the same size, a bento grid's variable-span machinery is unnecessary complexity — a plain CSS grid or flex wrap is simpler and communicates "these are all equally weighted" more honestly.

Do not span a tile wider than the grid can ever resolve to

A data-col-span="4" tile inside a grid whose cols never exceeds 3 is silently clamped to 3 — the tile still renders, just not as designed. Keep spans consistent with the largest cols value the grid actually reaches.

Do not put unrelated content in the same bento cluster

role="group" announces the tiles as one collection. Mixing, say, a marketing tile with an unrelated form field inside the same grid confuses that grouping — start a new grid instead.

API reference

The following are the properties and references of a bento grid

aegov-bento-grid default properties

AttributeDescriptionTypeDefault

field-id

DOM id reflected on the inner grid wrapper. Auto-generated if omitted.

string

auto-generated

cols

Number of columns. Single integer or a Tailwind-style responsive string. Clamped to 1–12.

string

1 md:2 lg:3

gap

Gap between tiles. Named token, responsive string supported.

none | xs | sm | md | lg | xl

md

flow

Auto-placement mode. dense back-fills holes left by larger spans; row keeps strict DOM order.

dense | row

dense

Per-child data attributes

AttributeDescriptionRange

data-col-span

Columns for this child to span. Responsive syntax supported. Clamped to the grid's current resolved cols value.

1–12

data-row-span

Rows for this child to span. Responsive syntax supported.

1–6

Slots

ComponentSlotDescription

aegov-bento-grid

(default)

Place one or more aegov-card elements (or any direct children) here.

Events

EventsDescription

(none)

The component emits no custom events — it is a pure layout primitive.

Pass-through attributes

AttributeNotesForwards to

aria-*

Forwarded to the inner grid wrapper. Use aria-label to describe the cluster (e.g. aria-label="Service highlights").

inner <div>

data-*

Forwarded to the inner wrapper (this is separate from data-col-span/data-row-span, which are read from each direct child, not the host).

inner <div>

id

Not forwarded. The inner wrapper's id always comes from field-id, which overrides any plain id set on the host.

n/a

Verified directly in aegov-bento-grid.tsx's render(): getPassThroughAttributes(this.el, new Set(['id'])) collects aria-*/data-*/id from the host, but the JSX spreads it before the explicit id={this.fieldId} — so any host-level id attribute is immediately overwritten. Use field-id to control the wrapper's actual id.

Notes

The following notes are applicable of this component.

Built-in accessibility

  • The inner wrapper has role="group", so assistive technologies announce the cluster as a single unit.
  • Tab order follows DOM order regardless of visual placement. Cards remain individually focusable and behave exactly as they would outside a grid.
  • The grid itself introduces no interactive semantics — there is no keyboard handling layered on top of the cards it contains.

Developer responsibility

The following is required for a developer to add additionally or pay attention to regarding this component.

  • Add aria-label (or aria-labelledby) on the host when the cluster has a meaningful name — the default role="group" alone is generic.
  • If a tile is meant to be clickable, make sure it is itself a focusable element (a link or button inside the card) — the bento grid does not wrap children in an interactive element.
  • Do not rely on visual ordering alone to communicate priority. Screen readers follow DOM order regardless of how flow="dense" re-shuffles the visual layout.

Additional notes

  • Per-card spans are applied as inline styles (grid-column, grid-row) directly on each direct child, and cleared entirely once resolved span is 1.
  • A MutationObserver watches data-col-span/data-row-span on direct children, so updating a span from JavaScript re-applies the layout automatically — no manual re-render call needed.
  • Only direct children receive layout treatment. A nested aegov-card inside a tile is unaffected by the grid's span logic.