Sheet | Calcite Design System

Sheet is a page-blocking content container intended for focused, fleeting workflows or tasks.

Overview

Sheet provides an ephemeral container for focused workflows and tasks, while preventing interaction with the main application content through the use of a page-blocking Scrim.

Sample

Usage

Display focused, ephemeral content to a user
Present short dialogues or choice sets to a user
Contain navigation and menu regions, administrative or platform settings

Best practices

While visually similar to the Shell Panel and Dialog components, Sheet has distinct capabilities and intended use cases.

The primary difference is in each's ephemerality - Sheet and Dialog should command the attention of the user for a focused task - preventing interaction with other application content while open - before being dismissed.

Conversely, Shell Panels can be open and persist in that way indefinitely - in some cases never being collapsed. Shell Panels should be displayed alongside visible and interactive primary application content.

Dialog should be used for complex, multi-step interactions and workflows invoked from the primary application. Sheet should be used for more ephemeral but still focused interactions like navigating menus, displaying user or platform settings, or presenting brief choices or decisions to a user.

Recommendations

On narrow viewports, such as a mobile device, use Sheet with the position property set to "block-end" to improve touch interactions. For larger viewport widths, you may wish to setup the component's position to either "inline-start" or "inline-end".

To limit the height of the component while position is "block-start" or "block-end", you can use the --calcite-shell-height, --calcite-shell-min-height, and --calcite-shell-max-height CSS variables.

Conversely, to limit the width while position is "inline-start" or "inline-end", you can use the --calcite-shell-width, --calcite-shell-min-width, and --calcite-shell-max-width CSS variables.

Do use css variables to constrain the height of content of vertically short content.

Do adjust "position" and displayMode based on viewport size.

Avoid opening multiple Sheets at once.

Avoid using a Sheet for tasks that may affect primary application content.

Accessibility

It is strongly recommended to keep focus trapping enabled on Sheet (focusTrapDisabled is false by default). With focus trapping enabled, tabbing forward or backward cycles through the component's interactive elements instead of focus proceeding outside the component. This ensures that when the Sheet is open, only its contents and interactive elements are focusable, which is the expected default behavior for keyboard navigation.

Key	Function
`Tab`	Moves focus to next focusable element. If the current focus is the last element and `focusTrapDisabled` is `false`, focus will cycle to the first element.
`Tab` and `Shift`	Moves focus to previous focusable element. If the current focus is the first element and `focusTrapDisabled` is `false`, focus will cycle to the last element.
`Esc`	If `escapeDisabled` is `false`, closes the component.

API reference

Properties

Property	Attribute	Description	Type	Default
beforeClose		Passes a function to run before the component closes.	`(el: Sheet) => Promise<void>`
displayMode	display-mode	Specifies the display mode - `"float"` separates content from main layout, and `"overlay"` displays on top of center content.	`DisplayMode`	`"overlay"`
escapeDisabled	escape-disabled	When `true`, disables the default close on escape behavior.	`boolean`	`false`
focusTrapDisabled	focus-trap-disabled	When `true`, prevents focus trapping.	`boolean`	`false`
focusTrapOptions		Specifies custom focus trap configuration on the component, where `"allowOutsideClick"` allows outside clicks, `"initialFocus"` enables initial focus, `"returnFocusOnDeactivate"` returns focus when not active, `"extraContainers"` specifies additional focusable elements external to the trap, such as 3rd-party components appending elements to the document body, and `"setReturnFocus"` customizes the element to which focus is returned when the trap is deactivated. Return `false` to prevent focus return, or `undefined` to use the default behavior (returning focus to the element focused before activation).	`Partial<FocusTrapOptions>`
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 `position` is `"block-start"` or `"block-end"`, specifies the component's height.	`Scale`	`"m"`
labelrequired	label	Specifies an accessible label for the component.	`string`
messageOverrides		Overrides individual strings used by the component.	`Record<string, unknown> \| undefined`
open	open	When `true`, displays and positions the component.	`boolean`	`false`
outsideCloseDisabled	outside-close-disabled	When `true`, disables closing the component when the area outside of the component is clicked.	`boolean`	`false`
position	position	Determines where the component will be positioned.	`LogicalFlowPosition`	`"inline-start"`
resizable	resizable	When `true`, the component is resizable.	`boolean`	`false`
topLayerDisabled	top-layer-disabled	When `true` and the component is `open`, disables top layer placement. Only set this if you need complex z-index control or if top layer placement causes conflicts with third-party components.	`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 `position` is `"inline-start"` or `"inline-end"`, specifies the component's width.	`Scale`	`"m"`

Slots

Name	Description
default (unnamed)	A slot for adding custom content.

Styles

Name	Description
--calcite-sheet-background-color	Specifies the component's background color.
--calcite-sheet-corner-radius	Specifies the component's corner radius.
--calcite-sheet-shadow	Specifies the component's shadow.
--calcite-sheet-text-color	Specifies the component's text color.
--calcite-sheet-resize-background-color	Specifies the resize handle's background color.
--calcite-sheet-resize-icon-color	Specifies the resize handle's text color.
--calcite-sheet-scrim-background	Specifies the background color of the component's scrim.
--calcite-sheet-width	When `position` is `"inline-start"` or `"inline-end"`, specifies the component's width.
--calcite-sheet-max-width	When `position` is `"inline-start"` or `"inline-end"`, specifies the component's maximum width.
--calcite-sheet-min-width	When `position` is `"inline-start"` or `"inline-end"`, specifies the component's minimum width.
--calcite-sheet-height	When `position` is `"block-start"` or `"block-end"`, specifies the component's height.
--calcite-sheet-max-height	When `position` is `"block-start"` or `"block-end"`, specifies the component's maximum height.
--calcite-sheet-min-height	When `position` is `"block-start"` or `"block-end"`, specifies the component's minimum height.

Events

Name	Description	Behavior
calciteSheetBeforeClose	Fires when the component is requested to be closed and before the closing transition begins.	bubblescomposed
calciteSheetBeforeOpen	Fires when the component is added to the DOM but not rendered, and before the opening transition begins.	bubblescomposed
calciteSheetClose	Fires when the component is closed and animation is complete.	bubblescomposed
calciteSheetOpen	Fires when the component is open and animation is complete.	bubblescomposed

Methods

Name	Description	Signature
componentOnReady	Creates a promise that resolves once the component is fully loaded.	`componentOnReady(): Promise<this>`
setFocus	Sets focus on the component's "close" button - the first focusable item.	`setFocus(options?: FocusOptions): Promise<void>`
updateFocusTrapElements	Updates the element(s) that are included in the component's focus-trap.	`updateFocusTrapElements(extraContainers?: FocusTrapOptions["extraContainers"]): Promise<void>`
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>`