Masonry
Automatically pack differently sized dashboard tiles, then move or resize them in edit mode.
c2-masonry
Automatically packs direct c2-masonry-item children into the first available grid cells.
Use c2-dashboard when the application must choose fixed coordinates instead.
Attributes
| Name | Type | Default | Description |
|---|---|---|---|
editable | boolean | false | Shows separate move and resize controls when every tile has a unique identity. |
save-layout | boolean | true | Saves committed user layouts to localStorage and restores them on load. Use save-layout="false" to opt out. |
storage-key | string | undefined | — | Optional stable localStorage key; otherwise the page URL and element ID or position identify this container. |
Slots
| Name | Description |
|---|---|
default | Direct c2-masonry-item children to pack. |
Events
| Name | Type | Description |
|---|---|---|
layout-error | CustomEvent<MasonryLayoutErrorDetail> | Invalid tile identities, spans, or supplied snapshot; does not bubble. |
layout-change | CustomEvent<MasonryLayoutChangeDetail> | Fired exactly once after a real user move or resize commit; does not bubble. Detail includes a complete restorable snapshot. |
CSS parts
Shadow DOM styling hooks used with ::part(name). Prefer CSS custom properties when they cover the change.
| Name | Description |
|---|---|
grid | Packed grid region. |
placeholder | Candidate occupied area during an edit session. |
CSS custom properties
Grouped by semantic target and state from --c2-<component>__<target>__<state>--<property>. Click a group to collapse it; click a name to copy it.
| Name | Type | Default | Description |
|---|---|---|---|
--c2-masonry--gap | pixel | 8px | Gap between cells and tiles. |
--c2-masonry--row-height | pixel | 8px | Height of one grid row. |
--c2-masonry--padding | padding | 0px | Inset around the grid. |
--c2-masonry--background | color | transparent | Grid background. |
--c2-masonry--border | border | none | Outer border. |
--c2-masonry--border-radius | border-radius | 0px | Outer corner radius. |
--c2-masonry__placeholder--background | color | rgb(37 99 235 / 8%) | Candidate tile fill. |
--c2-masonry__placeholder--border | border | 2px dashed #2563eb | Candidate tile edge. |
--c2-masonry__placeholder--border-radius | border-radius | 6px | Candidate corners. |
--c2-masonry__motion--duration | time | 160ms | Decorative movement duration. |
--c2-masonry__motion--timing-function | timing-function | ease | Decorative movement easing. |
Text and languages
The text the component shows, in English. It shows another language when the app adds one with addTranslations, under masonry, and the nearest lang asks for it; any message not translated stays in English. {0}, {1}… stand for the values a message carries. Languages guide.
| Key | English | Values |
|---|---|---|
tile | Tile | — |
move | Move {0} | {0} label |
resize | Resize {0} | {0} label |
content | {0} content | {0} label |
instructions | Press Enter or Space, use arrow keys, then press Enter to save or Escape to cancel. | — |
started | {0} {1} started. Use arrow keys; Enter saves and Escape cancels. | {0} label {1} kind |
position | {0}: position {1} of {2}. | {0} label {1} position {2} count |
size | {0}: {1} columns, {2} rows. Smallest size reached. | {0} label {1} columns {2} rows {3} atMinimum |
noChange | No layout change. | — |
saved | {0} {1} saved. | {0} label {1} kind |
canceled | {0} edit canceled. | {0} label |
c2-masonry-item
A fixed-span content tile placed by its parent c2-masonry. Tall content scrolls within the tile.
Attributes
| Name | Type | Default | Description |
|---|---|---|---|
item-id | string | undefined | — | Stable identity used for editing and application snapshots. |
label | string | undefined | — | Human-readable name used for the scroll region and edit controls. |
rows | number | 10 | Positive integer row span shared across size ranges. |
cols | number | 3 | Positive integer base column span. |
cols-xs | number | undefined | — | Optional positive column span for containers narrower than 600 px. |
cols-sm | number | undefined | — | Optional positive column span for 600–959.99 px containers. |
cols-md | number | undefined | — | Optional positive column span for 960–1279.99 px containers. |
cols-lg | number | undefined | — | Optional positive column span for containers at least 1280 px wide. |
min-rows | number | 1 | Smallest row span a user resize, by pointer or keyboard, can reach: a positive integer, otherwise 1. It only stops
the tile shrinking while it is resized. An authored rows or a restored layout below it is left as it is, and such
a tile cannot be resized smaller than it already is. |
min-cols | number | 1 | Smallest column span a user resize, by pointer or keyboard, can reach in any size range: a positive integer,
otherwise 1. It is capped at the range's column count (xs 1, sm 6, md 9, lg 12), so on xs it is always 1. Like
min-rows, it never rewrites an authored or restored span below it. |
move-handle | string | undefined | — | Id of an element inside the tile that moves it, in place of the built-in move handle, which is then not drawn: a
button in the tile's own header, for example. Pressing it, or Enter or Space on it, starts a move exactly as on
the built-in handle. The element is the application's: label it ("Move Groceries"), show it only while the
container is editable if it should not show otherwise, and give it touch-action: none so a touch drag moves the
tile instead of scrolling the page. The resize edges stay as they are. |
pinned | boolean | false | Keeps the tile in the group at the start of the container: pinned tiles always come before the others, in their own order. A move keeps a pinned tile among the pinned ones and any other tile after them, and a pinned tile authored or restored after an unpinned one is placed before it. Pin a tile the application keeps in view, such as a pinned note; nothing about the look changes, so show the pin in the tile itself. |
Slots
| Name | Description |
|---|---|
default | Application-owned tile content. |
move-icon | Optional move-handle icon; an inline grip is provided by default. |
actions | Buttons for the tile, such as a menu, in its top-right corner after the move handle. They show with the move handle, while the tile is hovered or has focus (see --c2-masonry-item__actions--opacity), and work whether or not the container is editable. Put them on the item itself, beside its content, so a tile whose content is one link can still carry a menu. |
Events
| Name | Type | Description |
|---|---|---|
c2-masonry-item-pinned | Event | Internal: pinned changed after the tile was placed, so the parent c2-masonry lays the tiles out again. Bubbles. |
CSS parts
Shadow DOM styling hooks used with ::part(name). Prefer CSS custom properties when they cover the change.
| Name | Description |
|---|---|
content | Keyboard-reachable scrolling region containing the application content. |
controls | Group of edit-only move and resize controls. |
actions | Top-right corner holding the move handle and the actions slot. |
move-handle | Button that starts a move operation. |
resize-handle | Keyboard-reachable bottom edge that starts a resize operation. |
resize-edge | Pointer resize target on the right edge. |
resize-corner | Pointer resize target on the bottom-right corner; drags change columns and rows together. |
CSS custom properties
Grouped by semantic target and state from --c2-<component>__<target>__<state>--<property>. Click a group to collapse it; click a name to copy it.
| Name | Type | Default | Description |
|---|---|---|---|
--c2-masonry-item--background | color | transparent | Tile surface. |
--c2-masonry-item--border | border | none | Tile border. |
--c2-masonry-item--border-radius | border-radius | 0px | Tile corner radius. |
--c2-masonry-item--box-shadow | box-shadow | none | Tile elevation. |
--c2-masonry-item__content--padding | padding | 0px | Content inset. |
--c2-masonry-item__controls--gap | pixel | 4px | Move-handle inset from the top and right borders. |
--c2-masonry-item__controls--background | color | transparent | Surface behind the move-handle corner. |
--c2-masonry-item__handle--size | pixel | 32px | Move-handle hit target size. |
--c2-masonry-item__handle--icon-size | pixel | 16px | Built-in move icon size. |
--c2-masonry-item__handle--color | color | #18181b | Move-handle foreground. |
--c2-masonry-item__handle--background | color | transparent | Move-handle surface. |
--c2-masonry-item__handle--border-radius | border-radius | 6px | Edit-control corners. |
--c2-masonry-item__handle__hover--background | color | transparent | Hovered move-handle surface. |
--c2-masonry-item__handle__focus--outline | outline | 2px solid #2563eb | Keyboard focus indicator. |
--c2-masonry-item__actions--gap | pixel | 4px | Space between the move handle and the slotted actions. |
--c2-masonry-item__actions--opacity | opacity | 0 | Opacity of the actions while the tile is neither hovered nor focused; 1 keeps them always visible. |
--c2-masonry-item__resize-handle--size | pixel | 8px | Invisible resize-edge hit-zone depth. |
--c2-masonry-item__resize-edge__hover--color | color | rgb(37 99 235 / 35%) | Right and bottom border color while the tile is hovered or focused. |
--c2-masonry-item__dragging--opacity | opacity | 0.92 | Active tile opacity. |
--c2-masonry-item__dragging--box-shadow | box-shadow | 0 12px 28px rgb(15 23 42 / 24%) | Active tile elevation. |