Skip to content

OrigamGrid ​

<OrigamGrid> is a thin declarative wrapper around CSS Grid. It exposes every meaningful grid-template-* / grid-auto-* / placement property as a typed prop and forwards the values to inline custom properties on the root element. No JS measurement, no ResizeObserver, no flexbox fallback — CSS Grid has been stable in every evergreen browser since 2017 (Safari 10.1, Edge 16, Firefox 52, Chrome 57) so we lean on the platform.

The bundled <OrigamGridItem> sub-component is optional sugar: it serialises the verbose grid-column / grid-row shorthands from an ergonomic object syntax. Anyone can skip it and put style="grid-area: …" on a plain <div> instead. See packages/docs/components/Grid/OrigamGridItem.md for its own dedicated reference (props, IGridLineSpec serialisation table, behaviour notes); the props/emits/slots tables below stay for convenience since the two components are almost always used together.

Props — OrigamGrid ​

PropTypeDefaultNotes
columnsnumber | string | string[]'auto'number → repeat(N, 1fr). string → passed verbatim. string[] → joined with single space.
rowsnumber | string | string[]'auto'Same accepted shapes as columns.
gap'xs' | 'sm' | 'md' | 'lg' | 'xl' | string | number'md'Tokens resolve to var(--origam-grid---gap-{token}); raw strings pass through; numbers → Npx.
columnGapsame as gapundefinedInline-axis override.
rowGapsame as gapundefinedBlock-axis override.
areasstring | string[]undefinedArray shape: each entry = one row, wrapped in double quotes by the component.
autoFlow'row' | 'column' | 'row dense' | 'column dense''row'Maps 1:1 to grid-auto-flow.
autoColumnsstringundefinedRaw CSS for implicit column tracks.
autoRowsstringundefinedRaw CSS for implicit row tracks.
alignItems'start' | 'center' | 'end' | 'stretch''stretch'Block-axis cell alignment.
justifyItems'start' | 'center' | 'end' | 'stretch''stretch'Inline-axis cell alignment.
alignContent'start' | 'center' | 'end' | 'stretch' | 'space-between' | 'space-around' | 'space-evenly'undefinedAligns the entire grid on the block axis when smaller than its container.
justifyContentsame as alignContentundefinedAligns the entire grid on the inline axis.
inlinebooleanfalseToggles display: inline-grid.
tagstring'div'Rendered HTML element.

Transversal props — OrigamGrid ​

IGridProps also extends the shared surface interfaces, and the component consumes every one of them on its root element. They are driven by the story's controls too.

GroupPropsComposable
Colorcolor, bgColoruseBothColor
Borderborder, borderTop, borderRight, borderBottom, borderLeft, borderBlock, borderInline, borderColor, borderStyle, borderTopColor, borderRightColor, borderBottomColor, borderLeftColoruseBorder
Roundedrounded, roundedTopLeft, roundedTopRight, roundedBottomLeft, roundedBottomRightuseRounded
ElevationelevationuseElevation
Dimensionwidth, height, minWidth, minHeight, maxWidth, maxHeightuseDimension
Paddingpadding, paddingTop, paddingRight, paddingBottom, paddingLeft, paddingBlock, paddingInlineusePadding
Marginmargin, marginTop, marginRight, marginBottom, marginLeft, marginBlock, marginInlineuseMargin
Commonsid, class, style—

Props — OrigamGridItem ​

PropTypeDefaultNotes
columnIGridLineSpec | string | numberundefinedObject { start, end, span } or raw CSS. span wins over end when both are set.
rowIGridLineSpec | string | numberundefinedSame accepted shapes as column.
areastringundefinedNamed area. When set, overrides column / row.
alignSelf'start' | 'center' | 'end' | 'stretch'undefinedPer-item override of the parent's alignItems.
justifySelf'start' | 'center' | 'end' | 'stretch'undefinedPer-item override of the parent's justifyItems.
tagstring'div'Rendered HTML element.
id / class / styleICommonsComponentPropsundefinedPassthrough on the root element. IGridItemProps extends nothing else — no color, border or spacing surface here.

Emits ​

Neither component emits anything. IGridEmits and IGridItemEmits are declared empty on purpose — both are purely presentational containers.

Slots ​

ComponentSlotBindingsDescription
OrigamGriddefault—The grid items.
OrigamGridItemdefault—The cell's content.

Both are typed as ICommonsComponentSlots; there is no named slot on either.

IGridLineSpec ​

ts
interface IGridLineSpec {
    start?: number | string  // grid line index or named line
    end?:   number | string  // grid line index or named line
    span?:  number           // span N tracks from `start` (wins over `end`)
}

Tokens ​

packages/ds/src/assets/css/tokens/light.css / dark.css (SCSS twins under packages/ds/src/assets/scss/tokens/) expose the gap-size matrix:

TokenCSS variableResolves to (primitive tier)
xs--origam-grid---gap-xsspace.1 → 4 px
sm--origam-grid---gap-smspace.2 → 8 px
md--origam-grid---gap-mdspace.4 → 16 px
lg--origam-grid---gap-lgspace.6 → 24 px
xl--origam-grid---gap-xlspace.8 → 32 px

Everything else (track templates, areas, alignment, …) is delegated to the consumer — there are intentionally no grid.template.* tokens because grid templates are layout decisions, not design decisions.

Examples ​

12-column dashboard with OrigamGridItem ​

vue
<template>
    <OrigamGrid :columns="12" gap="lg">
        <OrigamGridItem :column="{ start: 1, span: 8 }">Main content</OrigamGridItem>
        <OrigamGridItem :column="{ start: 9, span: 4 }">Sidebar</OrigamGridItem>
        <OrigamGridItem :column="{ start: 1, end: 13 }">Footer</OrigamGridItem>
    </OrigamGrid>
</template>

<script setup lang="ts">
    import { OrigamGrid, OrigamGridItem } from '@origam/components'
</script>

Holy-grail layout with areas ​

vue
<template>
    <OrigamGrid
            :areas="[
                'header header header',
                'sidebar main aside',
                'footer footer footer'
            ]"
            columns="200px 1fr 200px"
            rows="auto 1fr auto"
            gap="md"
    >
        <header style="grid-area: header">Header</header>
        <aside style="grid-area: sidebar">Sidebar</aside>
        <main style="grid-area: main">Main</main>
        <aside style="grid-area: aside">Aside</aside>
        <footer style="grid-area: footer">Footer</footer>
    </OrigamGrid>
</template>

Magazine layout with autoFlow="row dense" ​

row dense lets the algorithm backfill empty cells with smaller items, producing the classic magazine "puzzle" look. Pair it with per-item column={ span: N } to vary widths.

vue
<template>
    <OrigamGrid :columns="4" autoFlow="row dense" gap="sm">
        <OrigamGridItem :column="{ span: 2 }">Hero</OrigamGridItem>
        <OrigamGridItem :column="{ span: 1 }">A</OrigamGridItem>
        <OrigamGridItem :column="{ span: 1 }">B</OrigamGridItem>
        <OrigamGridItem :column="{ span: 3 }">Featured</OrigamGridItem>
        <OrigamGridItem :column="{ span: 1 }">C</OrigamGridItem>
    </OrigamGrid>
</template>

Browser support ​

CSS Grid is supported by every evergreen browser shipped since March 2017. The component does NOT implement a flex fallback — if you need to support IE 11 or pre-2017 Safari, this component is not the right abstraction. Use <OrigamRow> / <OrigamCol> (flex-based) instead.

Accessibility ​

<OrigamGrid> and <OrigamGridItem> render as plain <div> by default. They have no implicit ARIA role. Pass tag="section" / tag="ul" / tag="ol" if the visual grid maps to a semantic structure (a landmark, a list, …) so screen readers see the right tree.

If a grid carries data semantics (a calendar, a spreadsheet), set role="grid" / role="row" / role="gridcell" explicitly on the relevant elements — the component does not infer ARIA from CSS Grid because the two are independent contracts.