title: media-queries note: Do not remove this. This is important metadata and will not be shown on the actual page. confluencePath: dashboard-editor
Dashboard Media Queries — User Manual
Responsive dashboard layouts let an author tailor a dashboard to different container widths so it looks right whether it is rendered full-screen, alongside a sidebar, or embedded in a narrow panel. Instead of one fixed layout, each dashboard can store a separate layout per breakpoint tier, and the viewer automatically picks the matching one based on the dashboard container's measured width.
This manual covers the editor controls, the per-tier behaviors, and what the viewer does at runtime.
1. Breakpoint tiers
The system uses six fixed tiers based on the container's rendered pixel width. The boundaries are not configurable.
| Tier | Container width | Typical surface |
|---|---|---|
| XS | < 576 px | Mobile portrait |
| SM | 576 px – 767 px | Mobile landscape |
| MD | 768 px – 991 px | Tablet |
| LG | 992 px – 1199 px | Small desktop |
| XL | 1200 px – 1439 px | Large desktop (default) |
| XXL | ≥ 1440 px | Ultra-wide |
Boundaries are inclusive-lower and exclusive-upper.
Why XL is special
XL is the default tier. The layout you edit on XL is stored as the dashboard's base layout (layoutConfig) and is used as the fallback for any tier that has not been explicitly customized. Edits on any other tier produce a per-tier override and never touch the XL layout.
2. The breakpoint selector (editor)
When you open a dashboard in the editor and the device type is DESKTOP, a breakpoint selector appears centered above the grid. The selector is hidden on the MOBILE device-type view — the existing mobile editor experience is unchanged.
The selector contains:
- One pill per tier: XS · SM · MD · LG · XL · MD · XXL. The XL pill carries a
(Default)suffix. - An info icon on the right that opens a "Breakpoint rules" dialog summarizing the rules below.
Click any pill to switch the editor into that tier. The grid immediately re-renders to show that tier's layout.
3. Editing rules per tier
The active tier governs how your changes are persisted.
3.1 Editing on XL (default)
- Move/resize/add/remove operations update the dashboard's base layout.
- All other tiers that have not been customized continue to inherit from XL.
- Boardlet visibility is always on at XL — there is no per-boardlet hide/show toggle on this tier.
3.2 Editing on XS, SM, MD, LG, or XXL
- A boardlet's first move/resize on a non-XL tier creates a per-tier override for that boardlet.
- Edits on this tier never modify the XL layout.
- Boardlets that have not yet been customized for this tier render at their XL position as a starting point — the grid is never empty.
- Each boardlet shows a visibility toggle (eye icon) so it can be hidden for this tier only.
3.3 Adding a boardlet on a non-XL tier
A boardlet dropped while a non-XL tier is active is shown only on that tier and hidden on every other tier by default. Switch to another tier and toggle the eye icon to enable it there.
3.4 Hide / show per tier
- The visibility toggle is per-tier. Hiding a boardlet on SM does not affect MD, LG, etc.
- Hidden boardlets are dimmed in the editor (not removed) so they can be restored.
- Hidden boardlets are not rendered in the viewer for that tier and do not occupy grid space.
- Other boardlets are not automatically repositioned to fill the gap.
4. Authoring workflow
A typical end-to-end flow for adding responsive variants to an existing dashboard:
- Open the dashboard in the editor. The selector defaults to XL.
- Confirm the XL layout is what you want every other tier to inherit by default. Adjust if needed — these edits update the base layout.
- Click LG. The grid re-renders showing each boardlet at its XL position. Drag/resize the boardlets that need to differ on a small desktop. Untouched boardlets continue to inherit from XL.
- Repeat for MD, SM, XS, and XXL as needed. Use the eye icon to hide boardlets that should not appear at narrower widths.
- Save the dashboard.
You can re-enter the editor later and every tier's configuration will be intact.
5. Runtime behavior (viewer)
The viewer never asks the user which tier to render — it picks one automatically.
5.1 Container-width measurement
The viewer attaches a ResizeObserver to the dashboard container and re-measures whenever the container's box changes. This means the layout reacts to any width change, including:
- Application sidebar opening or closing.
- Browser window resize.
- A surrounding panel being dragged to a new size.
Window-level resize events are not used directly — the measurement is taken from the dashboard container's actual rendered width.
5.2 Tier resolution algorithm
For a measured container width W, the active tier is chosen by walking the table in section 1 from the smallest to the largest range and picking the first match. Then, for each boardlet:
- Look up the active tier in the boardlet's
responsiveLayouts. - If the entry has
hidden: true, the boardlet is not rendered. - If the entry has a layout override, that layout is applied.
- If no entry exists for the active tier, the boardlet falls back to the base
layoutConfig(the XL layout).
5.3 Legacy dashboards
Dashboards saved before this feature have no responsiveLayouts field. They render exactly as before at every container width — the base layoutConfig is used unconditionally. No data migration is required.
6. Data model
The feature extends the existing BoardletEntityDto with one optional field. The base layoutConfig is unchanged and remains the authoritative default.
interface BoardletEntityDto {
// ...existing fields
layoutConfig: BoardletLayoutConfig; // unchanged — XL / fallback
responsiveLayouts?: ResponsiveLayoutEntry[]; // new — per-tier overrides
}
interface ResponsiveLayoutEntry {
breakpointId: 'xs' | 'sm' | 'md' | 'lg' | 'xxl';
layout?: BoardletLayoutConfig; // absent ⇒ inherit from layoutConfig (XL)
hidden?: boolean; // true ⇒ omit from this tier
}There is no entry for xl — the base layoutConfig is the XL value by definition.
8. Troubleshooting
| Symptom | Likely cause | What to check |
|---|---|---|
| Selector is missing in the editor | The editor is in MOBILE device-type mode | Switch to DESKTOP — the breakpoint selector is intentionally hidden on the MOBILE view. |
| Switching tiers in the editor shows the same layout | No per-tier override exists yet | This is correct: untouched tiers inherit from XL. Move/resize a boardlet to create the override. |
| A boardlet I added on SM is missing from LG | Boardlets dropped on a non-XL tier are hidden on other tiers by default | Switch to LG and toggle the eye icon to show it there. |
| Viewer does not re-layout when a sidebar opens | The dashboard container's offsetWidth is not actually changing | Confirm the container's CSS width is responding to the sidebar; the ResizeObserver only fires on real layout changes. |
| A legacy dashboard renders differently than before | A responsiveLayouts entry was inadvertently saved | Re-open in the editor on XL and verify; a dashboard with no overrides should render identically to pre-feature behavior. |