API Reference
Complete contract for the <pattern-grid> custom element. For background and design rationale, see the spec.
Attributes
All attributes reflect to JS properties of the same camelCase name.
| Attribute |
Type |
Default |
Description |
cols |
integer |
1 |
Number of columns. Range: 1–256. Values outside the range are clamped. |
rows |
integer |
1 |
Number of rows. Range: 1–256. Values outside the range are clamped. |
cells |
string |
— |
Shorthand for cols × rows. Accepts "8x8" (2D) or "64" (1D shorthand for cols=64 rows=1). When present, overrides cols / rows. |
cell |
tag name |
i |
Tag used for generated cells. Must be a valid HTML tag. Ignored when a <template> child is provided. |
shim |
string |
— |
Set to "sibling" to opt into the sibling-index() JS fallback (writes --i per cell and --n on the host). |
seed |
string | number |
— |
Observed and reflected. Not interpreted by <pattern-grid> itself; the companion <seed-context> reads its own seed attribute to drive per-cell randomness. |
Properties
| Property |
Type |
Description |
cols |
number |
Resolved column count (clamped). Setter writes the attribute. |
rows |
number |
Resolved row count (clamped). Setter writes the attribute. |
cell |
string |
Cell tag name. Setter writes the attribute. |
total |
number (readonly) |
cols * rows. |
cellElements |
Element[] (readonly) |
Live array of generated cells (excludes any <template> child). |
Methods
| Method |
Returns |
Description |
render() |
void |
Force regeneration of cells. Idempotent if count and tag haven't changed. |
cellAt(i) |
Element | null |
Returns the i-th cell (0-indexed). Returns null if out of range. |
cellAt(x, y) |
Element | null |
Returns the cell at column x, row y (both 0-indexed). |
Events
| Event |
Detail |
When |
Bubbles |
pattern-grid:render |
{ cols, rows, total } |
After regeneration completes. |
Yes |
CSS Custom Properties — Set by the Component
The component writes these as inline styles on the host element. Author CSS reads them.
| Property |
Type |
Description |
--pg-cols |
<integer> |
Resolved column count. |
--pg-rows |
<integer> |
Resolved row count. |
--n |
<integer> |
Only set when shim="sibling". Equals total. |
--i |
<integer> |
Only set on each cell when shim="sibling". 1-indexed (matches native sibling-index()). |
CSS Custom Properties — Optional Stylesheet
Honored if you import @profpowell/pattern-grid/css (an opt-in stylesheet with sensible defaults). Otherwise inert.
| Property |
Default |
Description |
--pg-gap |
0 |
Grid gap. |
--pg-aspect |
calc(var(--pg-cols) / var(--pg-rows)) |
Aspect ratio of the grid container. |
--pg-cell-aspect |
1 |
Aspect ratio of each cell. |
--pg-bg |
transparent |
Default cell background. |
Progressive Enhancement
| Layer |
Without it |
Result |
| HTML only |
No CSS, no JS |
Empty <pattern-grid> element; no visual. |
| HTML + CSS |
No JS |
Hand-authored cells render as styled. |
| HTML + CSS + JS |
Full functionality |
Cells auto-generated; attributes reactive. |
<seed-context>
Companion element that wraps one or more <pattern-grid> elements and writes per-cell --rand-N (float) and --randi-N (integer) custom properties using a seeded PRNG.
Attributes
| Attribute | Type | Default | Description |
|---|
seed |
string | number |
"" |
Seed value. Same seed produces the same randoms across reloads. Hashed to a 32-bit integer for the PRNG. |
count |
integer |
8 |
Number of --rand-N slots per cell. Range 1–32, clamped. |
Properties & Methods
| Member | Type | Description |
|---|
seed | string | Read/write, reflects attribute. |
count | number | Read/write, reflects attribute (clamped on read). |
seedHash | number (readonly) | 32-bit hash of seed. |
prng | () => number (readonly) | Factory: returns a fresh seeded generator. |
reseed() | void | Re-writes randoms on all known cells without changing attributes. |
Events
| Event | Detail | When | Bubbles |
|---|
seed-context:populated |
{ target, count } |
After a grid's cells are populated. target is the populated pattern-grid. |
Yes |
CSS Custom Properties Written per Cell
For count = N:
| Property | Range | Description |
|---|
--rand-0 … --rand-{N-1} | [0, 1) | Float, suitable for continuous values. |
--randi-0 … --randi-{N-1} | [0, 99] | Integer, equals floor(rand-N * 100). |