Shell Panel | Calcite Design System

Child component of Shell

Shell Panel is expected to be used within the "panel-start", "panel-end", "panel-top", and "panel-bottom" slots of Shell.

Overview

Shell Panels often contain configuration, controls, and selection workflows that drive the user experience within the Shell, most frequently containing Panel, Block, and Action Bar components.

Shell Panels should be used to display content to a user that is contextually related to the contents of the default content slot of Shell.

Sample

Usage

House primary application functionality and configuration options that drive interaction.
Create consistent, repeatable application layouts when combined with Panel, Block, and Action Bar components.

Display mode

There are multiple displayMode options available in Shell Panel. The default, "dock", pushes content slotted in the default slot of Shell to the side. The "overlay" value places the Shell Panel on top of content slotted in the default slot of Shell. These types of Shell Panels can be combined within the same application to accommodate different workflows.

Note that the displayMode property will yield slightly different visual displays based upon the presence of the parent Shell component's contentBehind property. When true, Shell Panel will position on top of content slotted within the default slot of Shell.

Component comparison

Shell Panel and Panel components may look similar, but each have different use cases.

Shell Panel

This component

A content container used within Shell, intended to hold primary application functionality and configuration options.

Defines a dockable or floating region within a Shell.

Panel

Alternative

A content container used to group and organize specific UI elements like headers, footers, and Blocks.

Can be used independently or within a Shell or Shell Panel.

Recommendations

Layout

It is expected to slot a single Panel, most often containing one or more Block components, inside the Shell Panel. A common use case is to slot an Action Bar component into the "action-bar" slot to contain Actions that correspond to an open Panel.

Smaller viewports

At smaller viewport sizes, it may be useful to change displayMode from "dock" to "overlay". It can also at times be appropriate to programmatically collapse open Shell Panels that are not currently in use by a user.

API reference

Properties

Property	Attribute	Description	Type	Default
collapsed	collapsed	When `true`, hides the component's content area.	`boolean`	`false`
displayMode	display-mode	Specifies the component's display mode, where: `"dock"` displays at full height adjacent to center content, `"overlay"` displays at full height on top of center content, and `"float"` [Deprecated] does not display at full height with content separately detached from `calcite-action-bar` on top of center content. `"float-content"` does not display at full height with content separately detached from `calcite-action-bar` on top of center content. `"float-all"` detaches the `calcite-panel` and `calcite-action-bar` on top of center content.	`DisplayMode`	`"dock"`
height	height	Specifies the component's height.	`Height`
heightScale	height-scale	deprecatedin v3.0.0, removal target v6.0.0 - Use the `height` property instead. When `layout` is `horizontal`, specifies the component's maximum height.	`Scale`
layout	layout	deprecatedin v5.0.0, removal target v6.0.0 - No longer necessary. Specifies the component's direction.	`Extract<"horizontal" \| "vertical", Layout>`	`"vertical"`
messageOverrides		Overrides individual strings used by the component.	`Record<string, unknown> \| undefined`
position	position	deprecatedin v5.0.0, removal target v6.0.0 - No longer necessary. Specifies the component's position. Will be flipped when the element direction is right-to-left (`"rtl"`).	`Extract<"start" \| "end", Position>`	`"start"`
resizable	resizable	When `true` and `displayMode` is `"dock"` or `"overlay"`, the component's content area is resizable.	`boolean`	`false`
width	width	Specifies the component's width.	`Extract<Width, Scale>`
widthScale	width-scale	deprecatedin v3.0.0, removal target v6.0.0 - Use the `width` property instead. When `layout` is `vertical`, specifies the component's width.	`Scale`	`"m"`

Slots

Name	Description
default (unnamed)	A slot for adding custom content.
action-bar	A slot for adding a `calcite-action-bar` to the component.

Styles

Name	Description
--calcite-shell-panel-background-color	Specifies the component's background color.
--calcite-shell-panel-border-color	When `displayMode` is `"float-all"`, specifies the component's border color.
--calcite-shell-panel-corner-radius	When `displayMode` is `"float-all"`, specifies the component's corner radius.
--calcite-shell-panel-height	When `layout` is `horizontal`, or `layout` is `vertical` and `displayMode` is `float-content` or `float` or `float-all`, specifies the component's height.
--calcite-shell-panel-max-height	When `layout` is `horizontal`, or `layout` is `vertical` and `displayMode` is `float-content` or `float`, specifies the component's maximum height.
--calcite-shell-panel-min-height	When `layout` is `horizontal`, or `layout` is `vertical` and `displayMode` is `float-content` or `float`, specifies the component's minimum height.
--calcite-shell-panel-max-width	Specifies the component's maximum width.
--calcite-shell-panel-resize-icon-color	Specifies the resize handle's text color.
--calcite-shell-panel-shadow	When `displayMode` is `float-all`, `float-content`, or `overlay`, specifies the component's shadow.
--calcite-shell-panel-text-color	Specifies the component's text color.
--calcite-shell-panel-width	Specifies the component's width.
--calcite-shell-panel-z-index	Specifies the component's z-index value.

Methods

Name Description Signature

Name	Description	Signature
componentOnReady	Creates a promise that resolves once the component is fully loaded.	`componentOnReady(): Promise<this>`
updateSize	Updates the component's size by setting its inline and/or block dimensions. Use this method to programmatically override the component's width (inline) and/or height (block). Pass `null` to clear the override and revert to the default or CSS variable size.	`updateSize(size: { inline?: number \| null; block?: number \| null; }): Promise<void>`

componentOnReady

Creates a promise that resolves once the component is fully loaded.

componentOnReady(): Promise<this>

updateSize

Updates the component's size by setting its inline and/or block dimensions.

Use this method to programmatically override the component's width (inline) and/or height (block). Pass null to clear the override and revert to the default or CSS variable size.

updateSize(size: {
inline?: number | null;
block?: number | null;
}): Promise<void>