Sheet | Calcite Design System

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

Overview

Sheet provides an ephemeral container for focused workflows and tasks. By default, it prevents interaction with the main application content through the use of a page-blocking Scrim. Set modalDisabled to true to allow interaction with the main application content while the Sheet is open.

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

Component comparison

Sheet, Dialog, and Shell Panel provide containers for workflows, but differ in how long they remain open, where they appear, and whether users can interact with the main application content.

Sheet

This component

Best for brief, focused interactions such as filtering, preferences and settings, or choices. Often is dismissed after use.

Appears at an edge of the viewport.

Blocks interaction with the main application content by default. Set modalDisabled to allow interaction.

Dialog

Alternative

Supports prompts and focused workflows, including complex, multi-step interactions.

Floats over application content with configurable placement.

Allows interaction with the main application content by default. Set modal to block interaction.

Shell Panel

Alternative

Best for persistent primary application functionality and configuration. Can remain open indefinitely.

Defines a docked or overlaid region within a Shell.

Displays alongside interactive main application content.

Best practices

Use Sheet for short-lived interactions that users dismiss when finished. For persistent tools that users need alongside the main application content, use Shell Panel. For complex, multi-step workflows that require more space, consider Dialog.

Avoid opening multiple Sheets at once or opening another Sheet from within an open Sheet.

Recommendations

Position

On a narrow viewport, such as a mobile device, use Sheet with the position property set to "block-end". For larger viewport widths, consider setting position to either "inline-start" or "inline-end".

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

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

A bottom-positioned Sheet with dinner choices, sized to fit its content.

Do consider using Sheet's CSS variables to size the container appropriately for its content.

A bottom-positioned Sheet with dinner choices filling the viewport despite its short content.

Avoid leaving excessive empty space around a brief choice or short menu.

Sheet is modal by default. This is appropriate when users must finish or dismiss a task before returning to the main application content.

Set modalDisabled to true, to remove the page-blocking Scrim and allow interaction with the main application content while the Sheet remains open. Use this for brief interactions that benefit from access to the surrounding application, such as adjusting filters while inspecting a map.

A modal confirmation Sheet blocks the main application content until users confirm or cancel the changes.

Do keep modal behavior enabled when users need to resolve a decision before continuing.

A non-modal confirmation Sheet leaves the main application visible while users are asked to resolve a decision before continuing.

Avoid disabling modal behavior for a decision that must be resolved before users continue interacting with the application.

Accessibility

For modal Sheets, keep focus trapping enabled (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. Focus trapping ensures that when a modal Sheet is open, only its contents and interactive elements are focusable, which is the expected default behavior for keyboard navigation.

For non-modal Sheets, ensure users can navigate between the Sheet and the main application content with a keyboard. Provide an accessible label and a clear way to dismiss the Sheet.

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>) \| undefined`
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. `"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. `"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> \| undefined`
height	height	Specifies the component's height.	`Height \| undefined`
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		Replace localized message strings with your own strings. Note: Individual message keys may change between releases.	`Record<string, unknown> \| undefined`
modalDisabled	modal-disabled	When `true`, disables the default modal behavior, allowing interaction with content outside the component.	`boolean`	`false`
open	open	When `true`, displays and positions the component.	`boolean`	`false`
outsideCloseDisabled	outside-close-disabled	When `true` and `modalDisabled` is `false`, disables the closing of the component when clicked outside.	`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> \| undefined`
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>`