docs(dashboards): document the Grid container widget

[mngr]

What

Documents the Grid container dashboard widget — a widget that holds other widgets in its own independent cols × rows grid so authors can group, arrange, move, and resize related tiles (and nest containers) on a dashboard.

Adds docs-mintlify/docs/explore-analyze/dashboards/widgets/container.mdx and wires it into:

• the Widgets navigation group in docs.json
• the widgets index page (widget-types list + toolbar sentence)

The page covers: adding a Grid container, the inner grid (independent cols×rows, auto-growing rows), dragging widgets in, arranging (move/resize the container, resize children, move a child out), Distribute evenly, nesting containers, and the Edit/Delete menu — matching the existing charts / text / controls / AI-summary widget pages in tone and structure.

Companion to the feature PR

This documents the Grid container shipped in cubejs-enterprise PR #13919 (Linear CUB-3811). That feature is currently in review and gated behind the useBoardDashboards flag.

Draft on purpose — please hold merge until the feature PR lands and the container is enabled for users, so the public docs don't describe a feature that isn't live yet.

Validation

• mintlify broken-links --check-anchors --check-redirects --check-snippets → no broken links found
• docs.json is valid JSON
• Follows docs-mintlify/CLAUDE.md conventions (Widget taxonomy under the dashboard builder; no legacy "Cube Cloud" naming; <Steps> for procedures)

Known follow-up

Drop-sizing refinements (keep dragged size / downscale-to-fit / swap-on-collision) are tracked separately in CUB-3892 and intentionally not documented here — today dropped widgets snap to grid cells, which the page describes accurately.

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
cubed3	🟢 Ready	View Preview	Aug 14, 2026, 1:29 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[claude]

Claude finished @mngr's task in 1m 21s —— View job

---

Docs review: approve with nits — 0 high, 2 medium, 2 low

Full review

• Read PR diff
• Compare with sibling widget pages & docs conventions
• Verify docs.json wiring and link targets
• Post review

Docs-only change, so no security/perf/test surface. Prose is clear, well-structured, and reads like the existing widget pages. Two consistency issues are worth resolving before this ships.

Medium

1. Toolbar naming disagrees with the sibling pages (container.mdx:10,14,34, index.mdx:18) — posted inline. This page introduces an Add Widgets toolbar group and implies text/AI-summary widgets live in it, while text.mdx, ai-summary.mdx, and controls.mdx describe a flat toolbar ("click Add Text"). The new index.mdx sentence mixes both models. Since the feature is still in review, this is exactly the kind of thing that should be pinned against the shipped UI before merge — and if the toolbar really did regroup, the sibling pages need updating in the same PR.

2. spacers and dividers are undefined terms (container.mdx:32) — posted inline. Only mention of either word anywhere in docs-mintlify/; not in the index.mdx widget-types list, no page. Drop them or add them to the taxonomy.

Low

3. No ## Use cases section. Every sibling widget page (charts, text, controls, ai-summary) has one, and it's the section that tells a reader why to reach for the widget. Three bullets — group a chart with its controls, a row of comparable KPIs, a bordered dashboard section — would slot in right after the intro and match the house pattern.

4. Slug vs. title. File is container.mdx / URL .../widgets/container, but the title, nav label, and index link text are all "Grid container". grid-container.mdx would line the URL up with the label. Not worth a redirect if the page hasn't shipped yet — but it hasn't, so now is the free moment to rename.

Verified correct

• docs.json — valid JSON, container added to the Widgets group in the same order as the index.mdx list. ✅
• All internal links resolve: /docs/explore-analyze/workbooks, /docs/explore-analyze/dashboards/widgets/container. ✅
• In-page anchor #adding-widgets-to-a-container matches the ## Adding widgets to a container heading. ✅
• Frontmatter uses title + description per docs-mintlify/CLAUDE.md; <Steps>/<Step> used for the procedure; no legacy "Cube Cloud" naming; link-reference style ([ref-workbooks]) matches siblings. ✅

On the merge hold

Worth restating that nothing in the repo gates this — merging publishes the page immediately, so the "hold until CUB-3811 lands" note in the description is the only safeguard. Also, the description mentions CUB-3892 (drop-sizing refinements) will change how dropped widgets behave; container.mdx:38 ("Dropped widgets snap to the container's grid cells") is accurate today but will need a revisit when that lands.

• [`mngr/dashboard-grid-container-widget-docs`](https://github.com/cube-js/cube/tree/mngr/dashboard-grid-container-widget-docs)

[claude]

Claude finished @mngr's task in 1m 47s —— View job

---

Docs review: approve with nits — 0 high, 2 medium, 3 low

Full review

• Read updated PR diff
• Re-check the two prior medium findings (toolbar naming, spacer/divider)
• Compare with sibling widget pages & conventions
• Verify docs.json wiring and link targets
• Check existing review threads (both prior threads already resolved — nothing stale to close)
• Post review

Docs-only change — no security, performance, or test surface. Both findings from my earlier pass are now genuinely resolved, not just papered over:

• Toolbar naming — text.mdx, ai-summary.mdx, layout.mdx, and index.mdx all now say "the Add Widgets menu", and controls.mdx says "under Add Controls". The model is consistent across every widget page. ✅
• spacers / dividers — now defined by layout.mdx (landed via docs(dashboards): document Spacer & Divider layout widgets #11557) and listed in the index.mdx widget-types list, so line 38 no longer introduces undefined terms. ✅

Medium

1. Dragging is the only documented way to add a container, but drag-to-place is itself in preview (container.mdx:16,19,20 — posted inline). index.mdx:19-32 explains that toolbar items can be clicked or dragged, and warns that dragging to place is a separate preview feature requiring account activation, while clicking "is available to everyone." layout.mdx:26 uses the click phrasing. This page says drag three times and never mentions clicking — so a reader with the container enabled but not drag-to-place follows the steps, they don't work, and nothing on the page explains why. The same gap applies to container.mdx:40 ("drag a widget … and drop it directly onto the container, in one step") — if that's the only way to fill a container, say so; if clicking can target a selected container, document it.

2. The Widget taxonomy in docs-mintlify/CLAUDE.md wasn't updated. The taxonomy under Dashboard builder → Widget lists Charts / Text / Controls / AI summary / Layout (Spacer, Divider) — no Grid container. docs(dashboards): document Spacer & Divider layout widgets #11557 added Layout there when it added layout.mdx; this PR should do the equivalent so the canonical naming source stays complete. One line under Widget:

          - Grid container
   

Low

3. index.mdx intro paragraph wasn't updated. Line 6 enumerates what a widget can be — "a chart, a block of text, a control …, an AI-generated summary, or a layout element such as a spacer or divider" — and the frontmatter description lists the same set. Both now omit grid containers, while the list below them includes it.

4. Add Widgets menu vs. group (container.mdx:40 — posted inline). Every other page calls Add Widgets a menu and Add Controls a group; this line calls both "group."

5. Slug vs. label. File is container.mdx → /widgets/container, but the title, nav label, and index link text are all "Grid container". grid-container.mdx would line the URL up with the label, and since the page hasn't shipped there's no redirect cost. Raised before and non-blocking — flagging only because this is still the free moment.

I'm not re-raising the missing ## Use cases section from my earlier pass. docs-mintlify/CLAUDE.md explicitly says "Do not pad. No 'Overview' / 'Use cases' / 'Best practices' scaffolding" — the house guidance outranks the pattern in text.mdx / ai-summary.mdx, and the intro paragraph on line 12 already carries that job.

Verified correct

• Preview <Warning> is present, placed right after the frontmatter, and follows the required "in preview" + "reach out to the Cube support team to activate it for your account" shape. ✅
• docs.json — container added to the Widgets group in the same order as the index.mdx list; the two-line diff is well-formed (trailing comma added to the preceding entry). I could not run a JSON parser in this environment, so this is by inspection, not a parse. ⚠️
• Internal links resolve: /docs/explore-analyze/workbooks (via [ref-workbooks]), /admin/account-billing/support. ✅
• In-page anchor #adding-widgets-to-a-container matches the ## Adding widgets to a container heading. ✅
• Frontmatter uses title + description; no body H1; <Steps>/<Step> for the procedure; no legacy "Cube Cloud" naming; no internal feature-flag names exposed; link-reference style matches siblings. ✅
• No images committed. ✅

On the merge hold

Still nothing in the repo gates this page — merging publishes it immediately, so the "hold until CUB-3811 lands" note in the description remains the only safeguard. And per the description, CUB-3892 will change drop behavior; container.mdx:44 ("Dropped widgets snap to the container's grid cells") is accurate today but will need a revisit when that lands.

• [`mngr/dashboard-grid-container-widget-docs`](https://github.com/cube-js/cube/tree/mngr/dashboard-grid-container-widget-docs)

[claude]

Claude finished @mngr's task in 1m 6s —— View job

---

Docs review: approve with nits — 0 high, 1 medium, 3 low

Full review

• Read updated diff (2 new commits since last pass)
• Re-check prior findings (toolbar naming, spacer/divider, drag-only, menu-vs-group)
• Compare with index.mdx / layout.mdx / controls.mdx conventions and docs-mintlify/CLAUDE.md
• Check existing review threads — all four prior threads are already resolved, nothing stale to close
• Post review

Docs-only change; no security, performance, or test surface. Both items I flagged last pass are now fixed in the file:

• Drag-only adding — line 20 now leads with "open the Add Widgets menu … and choose Grid" and mentions drag-to-place as the optional, account-gated path. ✅
• Menu vs. group — line 40 now reads "the Add Widgets menu or the Add Controls group," matching index.mdx:21. ✅

Medium

1. Applying the fix left two artifacts in the adding section (container.mdx:16-21 — posted inline). The lead-in paragraph on line 16 and the body of Step 1 now say the same thing verbatim, and Step 1 lost its title while Steps 2–3 keep theirs — every other <Step> in the dashboards docs (controls.mdx:49,52,55) is titled, so an untitled one renders with a blank heading. Suggestion inline folds the lead-in into a titled first step.

Low

2. docs-mintlify/CLAUDE.md taxonomy still omits Grid container. The list under Dashboard builder → Widget (lines 121–130) is Charts / Text / Controls / AI summary / Layout (Spacer, Divider). docs(dashboards): document Spacer & Divider layout widgets #11557 added Layout there when it added layout.mdx; the equivalent one-line addition keeps the canonical naming source complete:

          - Grid container
   

3. index.mdx intro and frontmatter weren't updated. Line 6 enumerates what a widget can be — "a chart, a block of text, a control …, an AI-generated summary, or a layout element such as a spacer or divider" — and the description lists the same set. Both omit grid containers while the list directly below them includes it.

4. Slug vs. label. File is container.mdx → /widgets/container, but the title, nav label, and index link text are all "Grid container". grid-container.mdx would line the URL up; no redirect cost while the page is unshipped. Raised twice now and non-blocking — last free moment to do it.

Not re-raising the missing ## Use cases section: docs-mintlify/CLAUDE.md explicitly says not to add "Overview / Use cases / Best practices" scaffolding, and the intro on line 12 already does that job.

One open question rather than a finding: line 40 documents filling a container only via drag ("drop it directly onto the container"). If clicking a toolbar item can also target a selected container, that's worth a clause — otherwise the only documented way to put anything into a container is gated behind the separate drag-to-place preview. You resolved the earlier thread on this, so I've left it as a note here instead of reposting.

Verified correct

• Preview <Warning> present, immediately after frontmatter, using the standard "in preview" + "reach out to the Cube support team" shape. ✅
• docs.json — container added to the Widgets group in the same order as the index.mdx list; the two-line diff is well-formed (trailing comma added to the preceding entry). Verified by inspection; no JSON parser available in this environment. ⚠️
• Internal links resolve: /docs/explore-analyze/workbooks (via [ref-workbooks]), /admin/account-billing/support, /docs/explore-analyze/dashboards/widgets. ✅
• In-page anchor #adding-widgets-to-a-container matches the ## Adding widgets to a container heading. ✅
• spacers / dividers on line 38 are now defined by layout.mdx and listed in the index.mdx widget-types list. ✅
• Frontmatter uses title + description; no body H1; no legacy "Cube Cloud" naming; no internal feature-flag names exposed; link-reference style matches siblings; no images committed. ✅

On the merge hold

Nothing in the repo gates this page — merging publishes it immediately, so the "hold until CUB-3811 lands" note in the description is still the only safeguard. Per the description, CUB-3892 will change drop behavior; container.mdx:44 ("Dropped widgets snap to the container's grid cells") is accurate today but will need a revisit then.

• [`mngr/dashboard-grid-container-widget-docs`](https://github.com/cube-js/cube/tree/mngr/dashboard-grid-container-widget-docs)

[claude]

Two small artifacts from applying my earlier suggestion:

1. The lead-in paragraph and Step 1 now say the same thing. Line 16 ("open the Add Widgets menu in the toolbar and choose Grid") is repeated verbatim as the first step. Sibling pages either use a lead-in or a <Steps> block, not both with duplicate content.
2. Step 1 has no title. Steps 2 and 3 do, and every <Step> elsewhere in the dashboards docs (controls.mdx:49,52,55) is titled — an untitled step renders with a blank heading next to two titled ones.

Folding the lead-in's outcome into the step body fixes both:

Suggested change

	In the [dashboard builder][ref-workbooks], open the **Add Widgets** menu in the toolbar and choose **Grid**. The container is added with an empty inner grid, and its settings panel opens so you can size the grid right away.
	<Steps>
	<Step>
	Open the **Add Widgets** menu in the toolbar and choose **Grid**. If [drag-to-place](/docs/explore-analyze/dashboards/widgets) is enabled for your account, you can instead drag the **Grid** entry to drop the container exactly where you want it.
	</Step>
	<Steps>
	<Step>
	In the [dashboard builder][ref-workbooks], open the **Add Widgets** menu in the toolbar and choose **Grid**. The container is added with an empty inner grid, and its settings panel opens so you can size the grid right away. If [drag-to-place](/docs/explore-analyze/dashboards/widgets) is enabled for your account, you can instead drag the **Grid** entry to drop the container exactly where you want it.
	</Step>

Fix this →