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.
"position" and displayMode based on viewport size.Accessibility
It is strongly recommended to keep focus trapping enabled on Sheet (focus 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.
Keyboard navigation
| Key | Function |
|---|---|
Tab | Moves focus to next focusable element. If the current focus is the last element and focus 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 focus is false, focus will cycle to the last element. |
Esc | If escape 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 | height property instead.position is "block-start" or "block-end", specifies the component's height. | Scale | "m" |
| label | 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 | width property instead.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. | |
| calciteSheetBeforeOpen | Fires when the component is added to the DOM but not rendered, and before the opening transition begins. | |
| calciteSheetClose | Fires when the component is closed and animation is complete. | |
| calciteSheetOpen | Fires when the component is open and animation is complete. |
Methods
| Name | Description | Signature |
|---|---|---|
| componentOnReady | Create a promise that resolves once 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 components'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> |