# @haxtheweb/grid-plate

> a grid element with 1 to 4 columns via slots

Latest version **26.8.0** (published 2026-08-14) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @haxtheweb/grid-plate
pnpm add @haxtheweb/grid-plate
yarn add @haxtheweb/grid-plate
bun add @haxtheweb/grid-plate
```

## Health

**Score 55/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; high maintenance score.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 26.8.0 |
| Published | 2026-08-14 |
| First published | 2024-05-23 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 5 |
| Unpacked size | 82.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 279 |
| Author | haxtheweb |
| Maintainers | btopro |
| Keywords | webcomponents, html, haxtheweb, lit |

## Links

- npm: https://www.npmjs.com/package/@haxtheweb/grid-plate
- Repository: https://github.com/haxtheweb/webcomponents
- Homepage: https://github.com/haxtheweb/webcomponents#readme
- Issues: https://github.com/haxtheweb/webcomponents/issues
- npm.io page: https://npm.io/package/@haxtheweb/grid-plate

## Dependencies (5)

- [lit](https://npm.io/package/lit.md) 3.3.3
- [@haxtheweb/utils](https://npm.io/package/@haxtheweb/utils.md) ^26.8.0
- [@haxtheweb/responsive-grid](https://npm.io/package/@haxtheweb/responsive-grid.md) ^26.8.0
- [@haxtheweb/hax-body-behaviors](https://npm.io/package/@haxtheweb/hax-body-behaviors.md) ^26.8.0
- [@haxtheweb/responsive-utility](https://npm.io/package/@haxtheweb/responsive-utility.md) ^26.8.0

## Alternatives

- [@tsparticles/shape-image](https://npm.io/package/@tsparticles/shape-image.md) — 303.7K weekly downloads
- [@tsparticles/shape-line](https://npm.io/package/@tsparticles/shape-line.md) — 233.7K weekly downloads
- [stringify-attributes](https://npm.io/package/stringify-attributes.md) — 58.6K weekly downloads
- [mobile-drag-drop](https://npm.io/package/mobile-drag-drop.md) — 46.3K weekly downloads
- [@comunica/actor-rdf-parse-html](https://npm.io/package/@comunica/actor-rdf-parse-html.md) — 29.2K weekly downloads

## Recent versions

- 26.8.0 (latest) — 2026-08-14
- 26.0.0 — 2026-05-12
- 25.0.0 — 2026-01-09
- 11.0.5 — 2025-06-18
- 11.0.0 — 2025-06-06
- 10.0.2 — 2025-01-31
- 10.0.1 — 2024-12-23
- 10.0.0 — 2024-12-20
- 9.0.25 — 2024-12-09
- 9.0.24 — 2024-12-09
- 9.0.22 — 2024-12-05
- 9.0.18 — 2024-11-13
- 9.0.7 — 2024-10-18
- 9.0.6 — 2024-08-22
- 9.0.5 — 2024-08-03
- … 5 more at https://npm.io/package/@haxtheweb/grid-plate/versions

## README

# `<grid-plate>`

`@haxtheweb/grid-plate` — a layout container that arranges slotted content into 1–4 responsive columns. Drop material into named `col-1` … `col-4` slots, choose a predefined column layout, and the grid adjusts each column's width across `xs`, `sm`, `md`, `lg`, and `xl` breakpoints. It is the primary column-layout primitive used throughout HAX-authored content and is fully HAX-capable (the "Column layout" gizmo).

## Install / Import

```bash
npm i @haxtheweb/grid-plate
```

```js path=null start=null
// ES module / bare import (npm or CDN)
import '@haxtheweb/grid-plate/grid-plate.js';
```

```html path=null start=null
<script type="module">
  import '@haxtheweb/grid-plate/grid-plate.js';
</script>

<grid-plate layout="1-1">
  <p slot="col-1">Column one</p>
  <p slot="col-2">Column two</p>
</grid-plate>
```

## Layouts

`layout` selects a named column arrangement from the predefined `layouts` map. At the `xs` breakpoint every layout stacks its columns to `100%`; the ratios below apply at `sm`/`md`/`lg`/`xl`.

| Layout key | Columns | Description |
|---|---|---|
| `1` | 1 | Full width |
| `1-1` | 2 | Equal width (50/50) |
| `2-1` | 2 | Wide & narrow (~66.7/33.3) |
| `1-2` | 2 | Narrow & wide (~33.3/66.7) |
| `3-1` | 2 | Wider & narrower (75/25) |
| `1-3` | 2 | Narrower & wider (25/75) |
| `1-1-1` | 3 | Equal width (33.3 each) |
| `2-1-1` | 3 | Wide, narrow, narrow (50/25/25) |
| `1-2-1` | 3 | Narrow, wide, narrow (25/50/25) |
| `1-1-2` | 3 | Narrow, narrow, wide (25/25/50) |
| `1-1-1-1` | 4 | Equal width (25 each) |

Legacy layout names are still accepted and map to the keys above: `12`→`1`, `6/6`→`1-1`, `8/4`→`2-1`, `4/8`→`1-2`, `4/4/4`→`1-1-1`, `3/3/3/3`→`1-1-1-1`.

Supply a custom `layouts` object to add or override layouts. Each entry is `{ columnLayout, xs, sm, md, lg, xl }`, where every size is an array of column-width strings (one per column).

## Properties

| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
| `layout` | `layout` | String | `"1-1"` | Key of the selected layout (see Layouts). |
| `columns` | `columns` | Number | `4` | Number of column slots to display; slots beyond this are hidden. |
| `layouts` | `layouts` | Object | predefined map | Map of layout keys to per-breakpoint column-width arrays. |
| `responsiveSize` | `responsive-size` | String | `"xs"` | Current responsive size (`xs`, `sm`, `md`, `lg`, `xl`); set automatically by ResponsiveUtility. |
| `disableResponsive` | `disable-responsive` | Boolean | `false` | Keep the multi-column layout on larger screens while still stacking at `xs`. |
| `itemMargin` | `item-margin` | Number | `null` | Margin around slotted items (px). Falls back to `16px` via `--grid-plate-item-margin`. |
| `itemPadding` | `item-padding` | Number | `null` | Padding inside slotted items (px). Falls back to `16px` via `--grid-plate-item-padding`. |
| `breakpointSm` | `breakpoint-sm` | Number | `600` | Small breakpoint (px); applied on attach. |
| `breakpointMd` | `breakpoint-md` | Number | `900` | Medium breakpoint (px); applied on attach. |
| `breakpointLg` | `breakpoint-lg` | Number | `1200` | Large breakpoint (px); applied on attach. |
| `breakpointXl` | `breakpoint-xl` | Number | `1500` | Extra-large breakpoint (px); applied on attach. |
| `dataHaxRay` | `data-hax-ray` | String | `null` | Set by the HAX editor to enable layout outlines and drag-and-drop affordances. |
| `ready` | `ready` | Boolean | `false` | Lifecycle flag, set to `true` shortly after first render. Managed internally. |

## Attributes

| Attribute | Type | Default | Description |
|---|---|---|---|
| `layout` | String | `"1-1"` | Key of the selected layout. |
| `columns` | Number | `4` | Number of column slots to display. |
| `layouts` | Object | predefined map | Map of layout keys to per-breakpoint column-width arrays. |
| `responsive-size` | String | `"xs"` | Current responsive size; set automatically by ResponsiveUtility. |
| `disable-responsive` | Boolean | `false` | Lock multi-column layout on larger screens. |
| `item-margin` | Number | `null` | Margin around slotted items (px). |
| `item-padding` | Number | `null` | Padding inside slotted items (px). |
| `breakpoint-sm` | Number | `600` | Small breakpoint (px). |
| `breakpoint-md` | Number | `900` | Medium breakpoint (px). |
| `breakpoint-lg` | Number | `1200` | Large breakpoint (px). |
| `breakpoint-xl` | Number | `1500` | Extra-large breakpoint (px). |
| `data-hax-ray` | String | `null` | HAX editor edit-mode signal. |
| `ready` | Boolean | `false` | Internal lifecycle flag. |

## Slots

| Slot | Description |
|---|---|
| `col-1` | First column content. |
| `col-2` | Second column content. |
| `col-3` | Third column content. |
| `col-4` | Fourth column content. |

The shadow DOM also renders `col-5` and `col-6` slots; they are only visible when `columns` is raised above `4` and a matching entry is supplied via `layouts`.

## Events

| Event | Type | Description |
|---|---|---|
| `disable-responsive-changed` | `CustomEvent` | Fired when `disableResponsive` changes; `detail` is the new boolean value. |

## Methods

| Method | Parameters | Returns | Description |
|---|---|---|---|
| `resize` | — | `void` | Dispatches a global `resize` event so dependents recompute layout. |
| `haxactiveElementChanged` | `el`, `val` | `void` | HAX lifecycle hook invoked when the active editable element changes. |

## CSS Parts

| Part | Description |
|---|---|
| `layout-container` | Each column wrapper (`div.column`). |

## CSS Custom Properties

| Property | Default | Description |
|---|---|---|
| `--grid-plate-item-margin` | `16px` | Margin around slotted items (driven by `itemMargin`). |
| `--grid-plate-item-padding` | `16px` | Padding inside slotted items (driven by `itemPadding`). |
| `--grid-plate-row-margin` | `0px` | Margin on the row container. |
| `--grid-plate-row-padding` | `0px` | Padding on the row container. |
| `--hax-layout-container-outline-width` | `1px` | Outline width of a layout container in HAX edit mode. |
| `--hax-layout-container-hover-outline-width` | `1px` | Hover outline width of a layout container in HAX edit mode. |
| `--hax-layout-container-outline-offset` | `0px` | Outline offset of a layout container in HAX edit mode. |
| `--hax-layout-container-transition` | `0.6s width ease-in-out, 0.6s padding ease-in-out, 0.6s margin ease-in-out` | Transition applied to layout containers when widths change in HAX edit mode. |

## Use in the HAX editor

`grid-plate` registers as a **Column layout** gizmo (`icon: hax:3-3-3-3`, tags: `Layout`, `content`, `grid`) of type `grid`, with `canScale` and `canEditSource` enabled. It advertises DDD `card`, `accent`, and `primary` theming support.

The HAX configuration panel exposes:

| Setting | Control | Description |
|---|---|---|
| Column Layout | select | Chooses a `layout` from the predefined layouts (may reflow on small screens). |
| Disable responsive | boolean | Keeps columns on larger screens while still stacking on the smallest screens. |
| Item Padding | slider (0–120 px, step 4) | Sets `itemPadding`. |
| Item margins | slider (0–120 px, step 4) | Sets `itemMargin`. |

When HAX saves the element, these attributes are stripped (not persisted): `ready`, `layouts`, `columns`, `options`, `responsive-width`, `responsive-size`, and the four `breakpoint-*` attributes.

The HAX demo schema:

```html path=null start=null
<grid-plate item-margin="16" item-padding="16">
  <p slot="col-1">Column one content to replace</p>
  <p slot="col-2">Column two content to replace</p>
</grid-plate>
```

## Demo / Develop

Run the local demo from the element directory:

```bash path=null start=null
npm start
```

This starts the dev server and opens `demo/index.html`, which lets you switch layouts live via a dropdown. The demo composes `grid-plate` with content elements such as `video-player`, `wikipedia-query`, and `media-image` across `col-1` … `col-4`.

## Explanation

`grid-plate` is the standard multi-column layout wrapper for HAX content. It builds on `LitElement` and `@haxtheweb/responsive-utility`: on `firstUpdated` it registers itself with `ResponsiveUtility`, which writes the matching `responsive-size` attribute back onto the element as its width crosses the `breakpoint-*` thresholds. The element then reads the selected layout's column-width array for the current size and applies each width to the corresponding `div.column` wrapper.

Because the column wrappers are flex items with `::slotted(*)` margin/padding driven by `--grid-plate-item-margin` / `--grid-plate-item-padding`, spacing stays consistent across whatever HAX-capable elements you drop into the slots. In HAX edit mode (`data-hax-ray`), the same wrappers gain outlines, active/hover states, and drag-and-drop targets so authors can rearrange material between columns.

## Contributing

1. Fork it! `git clone git@github.com/haxtheweb/webcomponents.git`
2. Create your feature branch: `git checkout -b my-new-feature`
3. Commit your changes: `git commit -m 'Add some feature'`
4. Push to the branch: `git push origin my-new-feature`
5. Submit a pull request :D

## License

Apache-2.0 © The Pennsylvania State University

---
_Source: https://npm.io/package/@haxtheweb/grid-plate · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
