calcite-shell decides where things go, not when they move — the Calcite 5.x layout frame, and the small-screen code it leaves to you

Every one of the 30 ATS builds that declare @esri/calcite-components in their package.json ships calcite-shell. Twenty-three of them also ship their own matchMedia code. That second number is the subject of this post. The shell is a layout frame: it puts a header, a footer, up to four shell-panels and your map in fixed, named places, and it keeps slotted dialogs, alerts and sheets inside its own box. In Esri’s words, it “doesn’t automatically hide content within slots on smaller screens.” Every change to where the shell’s panels sit, or whether they are open, is code you write.

Everything below was checked against the Calcite documentation and run in headless Chrome on Calcite 5.0.2 and 5.1.2 on October 12, 2026. 5.0.2 is the version the ArcGIS Maps SDK for JavaScript 5.0 CDN entry loads, and 5.1.2 is the current release on npm. The published API of the shell and the shell-panel is identical in the two versions, so what follows applies to both. Where a statement rests on our own test rather than on Esri’s documentation, the text says so.

What the shell is: ten named regions

Esri describes Shell as “a foundational layout component in Calcite.” It can fill the page, or it can be “given defined width and height to enable you to embed applications in other experiences or narrative content.” It is not the “app shell” of progressive web apps: nothing on its page concerns caching, offline use or service workers. It is a set of slots.

At 5.x the shell has exactly ten documented slots. The 5.1.2 type declarations carry the same ten, and in our test the 5.0.2 and 5.1.2 shells exposed all ten as slots (plus an undocumented modals, below).

The shell itself has one property, contentBehind, which “positions the center content behind any calcite-shell-panels.” In our test, a 240 px docked panel in an 800 px shell left the center content 560 px wide; with contentBehind set, the center content took the full 800 px and the panel sat on top of it. The shell fires no events and has no methods beyond componentOnReady. The docs do not say that contentBehind moves anything inside a map, such as its zoom buttons. In our Aurora Watch app we offset the map’s top-left controls by hand. If you set contentBehind, check where your map’s controls end up.

One more name that misleads: the header slot is a place, not a landmark. It positions content “at the top of the component.” The accessibility section below says what that means.

Panels are placed by slot, not by property

A shell-panel is “expected to be used within the ‘panel-start’, ‘panel-end’, ‘panel-top’, and ‘panel-bottom’ slots of Shell.” The slot decides where it goes. Its position and layout properties were deprecated in 5.0.0, with a removal target of 6.0.0, and the reason given for both is “No longer necessary.” In our test, a panel written as slot="panel-end" position="start" rendered at the end, and its position property read back "end".

Do not confuse calcite-shell-panel with calcite-panel. The shell-panel “defines a dockable or floating region within a Shell.” The panel groups UI and “can be used independently or within a Shell or Shell Panel.” Esri’s expected pattern is one inside the other: “It is expected to slot a single Panel, most often containing one or more Block components, inside the Shell Panel,” and, as “a common use case,” an Action Bar in the shell-panel’s action-bar slot.

How a shell-panel sits next to the center content is its displayMode:

• dock (the default) “pushes content slotted in the default slot of Shell to the side.”
• overlay “places the Shell Panel on top of content slotted in the default slot of Shell.” It is not a modal surface.
• float-content detaches the content from the action bar, and float-all detaches both the panel and the action bar; both sit on top of the center content. Plain float is deprecated.

Esri notes that the display modes look “slightly different” depending on the shell’s contentBehind.

resizable needs care, because the sources disagree. The property text on the shell-panel page still reads “When true and displayMode is ‘dock’ or ‘overlay’, the component’s content area is resizable.” The May 2025 release summary added float: “Panels can now be resized when displayMode is ‘float’.” The component changelog says the change allowed resizing “for all displayMode values.” In our test on 5.1.2, the resize handle rendered in all five modes.

Three more shell-panel facts that are easy to miss on its documentation page:

• collapsed “hides the component’s content area.” It is a property only. The shell-panel has no built-in collapse button; that is calcite-panel’s collapsible.
• The shell-panel page has no Events section, but the 5.1.2 type declarations ship two events, calciteShellPanelCollapse and calciteShellPanelExpand. In our test both fired, with a null detail.
• Since 5.0, shell-panels have an updateSize() method “to programmatically update dimensions after initial render via the inline and block parameters.” “Pass null to clear the override and revert to the default or CSS variable size.”

Overlays that stay inside the box

The three overlay slots are what make an embedded shell work. Esri: “For example, you can display a Dialog within the bounds of an embedded Shell without it taking over the whole page.” We tested it against the same dialog placed outside the slot. In a 1200 × 800 page holding an 800 × 500 shell, a dialog in the dialogs slot rendered exactly inside the shell’s box. The same dialog outside the slot covered the whole viewport.

The docs give alerts and sheets the same rule: each, “when placed in this slot,” is “constrained to the extent of the calcite-shell.” We tested only the dialog.

What the shell does not do: adapt to small screens

This is the sentence the post is built on, from the Shell page:

We measured what that means on a phone. A shell with a 240 px docked panel, loaded at a 375 px viewport with no script, kept the panel open and left the map 135 px wide. The shell did nothing. The same page with a few lines of script collapsed the panel and gave the map all 375 px.

Esri files moving shell-panels by screen size under adaptive design, the programmatic kind, and lists “Slot relocation: Programmatically move a Shell Panel from Shell’s ‘panel-start’ slot to the ‘panel-bottom’ slot based on screen size.” Responsive design, in the same guide, means components with “internal logic … used to automatically adjust the display and functionality based on the available width.” The examples it gives are Action Bar, Carousel and Card Group. That is an example list, not a complete one.

Action Bar matters here, because it lives inside a shell-panel: by default it “dynamically collapses Actions into an ellipsis overflow menu” on its own. So the code you write is about where the shell-panels sit and whether they are open, not about everything inside them.

Esri’s Shell and Shell Panel pages suggest three moves for small screens:

• Switch displayMode from dock to overlay: “At smaller viewport sizes, it may be useful to change displayMode from ‘dock’ to ‘overlay’.”
• Collapse panels that are not in use: “It can also at times be appropriate to programmatically collapse open Shell Panels that are not currently in use by a user.”
• Move the panel to the bottom: “For mobile devices, consider moving a Panel from the horizontal edge slots of panel-start or panel-end to the bottom of the viewport via panel-bottom to better fit the thumb zone of a phone.”

The minimum we measured, not a pattern to ship

This is the page we tested: a minimal page, not Aurora Watch’s own code. Loaded at 1200 px, the panel is open at 240 px and the map is 960 px wide. Loaded at 375 px, the script collapses the panel and the map gets the full width. The 600 px threshold is simply the one we tested. If your page also loads the ArcGIS Maps SDK for JavaScript 5.0 CDN entry, note that the entry already loads Calcite 5.0.2, while this sample loads 5.1.2; we did not test the two together on one page.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Shell layout</title>
  <script type="module" src="https://js.arcgis.com/calcite-components/5.1.2/index.js"></script>
  <link rel="stylesheet" href="https://js.arcgis.com/calcite-components/5.1.2/main.css">
  <style>html, body { margin: 0; height: 100%; } #view { width: 100%; height: 100%; }</style>
</head>
<body>
  <calcite-shell id="shell">
    <calcite-navigation slot="header">
      <calcite-navigation-logo slot="logo" heading="Aurora Watch"></calcite-navigation-logo>
    </calcite-navigation>
    <calcite-shell-panel slot="panel-start" id="ps" display-mode="dock" resizable>
      <calcite-panel heading="Layers" heading-level="2">Panel content</calcite-panel>
    </calcite-shell-panel>
    <div id="view">Map goes here</div>
  </calcite-shell>
  <script type="module">
    // Shell does not collapse panels for you on small screens; this does.
    const panel = document.getElementById("ps");
    const narrow = window.matchMedia("(max-width: 600px)");
    const apply = () => { panel.collapsed = narrow.matches; };
    narrow.addEventListener("change", apply);
    apply();
  </script>
</body>
</html>

What our 30 builds do

Of the 30 ATS builds, 23 call matchMedia. The source build for this topic, our Aurora Watch app, checks (max-width: 768px) and moves its inner panel into a dock of its own. Several of our apps move the panel to panel-top on phones; none use panel-bottom, which is the slot Esri suggests for the thumb zone. Both work. If you are starting fresh, Esri’s suggestion is the one with a stated reason. None of our builds use the overlay display mode, the collapse and expand events or updateSize(), and 14 set content-behind on the shell.

5.0 leftovers to clean up

Calcite 5.0 removed two things around the shell, and its release summary says what replaces them:

• calcite-shell-center-row is gone: “Use the Shell Panel component in the Shell’s panel-bottom slot instead.”
• The shell’s center-row slot is gone, with the same replacement. In our test on 5.0.2 and 5.1.2, content placed in it was not rendered at all, and nothing was written to the console.

The modals slot is a different case. It was the slot for the removed calcite-modal, and at 5.x it is no longer in the Shell page or the type declarations. It is also not in the 5.0 list of removed slots, and in our test the 5.0.2 and 5.1.2 shells still rendered content placed in it. Treat it as undocumented and use dialogs.

Then the deprecated properties that still work until their 6.0.0 removal target:

None of our builds use modals, center-row, calcite-shell-center-row or calcite-modal. In our test, the deprecated position and float logged no console warning, which is why a list like this is worth keeping: a cleanup before 6.0, not a defect today.

Accessibility is on you

Neither the Shell page nor the Shell Panel page has an accessibility section; the Panel page does. Four things we would check in any shell app:

• Heading levels. Set heading-level on each calcite-panel. Esri: it “specifies the heading level number of the component’s heading for proper document structure, without affecting visual styling.” In our test, without it the heading rendered as a div; with heading-level="2" it rendered as an h2.
• Landmarks. Esri’s Navigation page says to use Navigation with Navigation Logo and, when applicable, Navigation User “to provide landmarks to the user.” In our test of the sample above (logo only, no Navigation User), Chrome’s accessibility tree held no main, banner or navigation landmark. Check yours in the accessibility tree; do not assume the shell’s header slot provides one.
• A way back from collapse. See the caveat on the sample: a collapsed panel with no control to reopen it is gone for every user.
• Focus order. Calcite’s accessibility guidance: “Focus order should be logical, and generally follow the visual order of the page.” If your code moves a panel between slots, check focus order again at the width where it moves.

One positive result, from our test only: the shell-panel resize handle was a separator that takes keyboard focus, named “Resize”, and the Right Arrow key widened the panel from 240 px to 250 px. The docs do not describe this, so treat it as observed behavior in 5.1.2, not a documented guarantee.

Cost and licensing

The shell and the shell-panel make no service requests: the API reference lists no property or method that calls a service. That is our reading of the API, not an Esri pricing statement. The licensing page: “Calcite is available with either an ArcGIS Online, ArcGIS Enterprise, or ArcGIS Location Platform account. If you don’t have an account, you can create an ArcGIS Location Platform account for free.” Use is “subject to the terms of use found in the Esri Master Services Agreement.”

The short version

• The shell places things: a header, a footer, four shell-panel slots, a center slot for the map, and three overlay slots that keep dialogs, alerts and sheets inside its box.
• The slot decides where a shell-panel goes. position and layout are deprecated as “No longer necessary.”
• The shell does not adapt to small screens. Collapsing, switching to overlay and moving panels between slots are code you write; Action Bar overflow is built in.
• If you collapse a panel, leave a way to reopen it.
• Clean up width-scale, position and float before 6.0, and use dialogs, not modals.

References

• Calcite Design System — Shell (the ten slots, contentBehind, pinned header and footer, overlays constrained to the shell, and the sentence that Shell does not hide slotted content on smaller screens)
• Calcite Design System — Shell Panel (slot placement, displayMode, resizable, collapsed, updateSize, and the deprecated position, layout, widthScale and heightScale)
• Calcite Design System — Panel (headingLevel, collapsible, and Panel versus Shell Panel)
• Calcite Design System — Navigation (Navigation with Navigation Logo and Navigation User to provide landmarks)
• Calcite Design System — Layouts (responsive versus adaptive design, Action Bar overflow, and slot relocation)
• Calcite Design System — Accessibility (focus order)
• Calcite Design System — release summary, February 2026 (5.0) (removed components and slots, and updateSize)
• Calcite Design System — release summary, May 2025 (shell-panel resizing when displayMode is float)
• Calcite Design System — 5.1 release notes (the only shell-panel change in 5.1 is a resize fix)
• Calcite components — CHANGELOG (resizable allowed for all displayMode values (#11983))
• Calcite Design System — Licensing (the account requirement and the Esri Master Services Agreement)