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.
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
Sample
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
It is common to use a Sheet in the block-end
value of position
when presenting users options in a narrow viewport - often on a mobile device. At a larger viewport width, you may wish to provide this in an inline-start
or inline-end
position.
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
, --calcite-shell-max-height
css variables. While position
is "inline-start"
or "inline-end"
position, you can instead adjust the width via --calcite-shell-width
, --calcite-shell-min-width
, --calcite-shell-max-width
css variables.
"position"
and displayMode
based on viewport size.Accessibility
It is strongly recommended to have focusable elements cycle through Sheet where focus
is false
(default) to support assistive technology users. The expected behavior for assistive technologies is while the component is open
only the contents and focusable elements are accessible.
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: HTMLCalciteSheetElement) => Promise<void> | ||
displayMode | display-mode | Specifies the display mode - "float" (content is separated detached),
or "overlay" (displays on top of center content). | "float" | "overlay" | "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, and
"extraContainers" specifies additional focusable elements external to the trap (e.g., 3rd-party components appending elements to the document body). | {
initialFocus?: FocusTargetOrFalse | (() => void);
returnFocusOnDeactivate?: boolean;
allowOutsideClick?: boolean | MouseEventToBoolean;
extraContainers?: string | HTMLElement | SVGElement | Array<string | HTMLElement | SVGElement>;
} | ||
height | height | Specifies the height of the component. | "l" | "m" | "s" | |
heightScale | height-scale | height property instead.position is "block-start" or "block-end" , specifies the height of the component. | "l" | "m" | "s" | "m" |
label | label | Specifies the label of the component. | string | |
messageOverrides | Use this property to override individual strings used by the component. | { resizeEnabled?: string; } | ||
open | open | When true , displays and positions the component. | boolean | false |
outsideCloseDisabled | outside-close-disabled | When true , disables the closing of the component when clicked outside. | boolean | false |
position | position | Determines where the component will be positioned. | "block-end" | "block-start" | "inline-end" | "inline-start" | "inline-start" |
resizable | resizable | When true , the component is resizable. | boolean | false |
width | width | Specifies the width of the component. | "l" | "m" | "s" | |
widthScale | width-scale | width property instead.position is "inline-start" or "inline-end" , specifies the width of the component. | "l" | "m" | "s" | "m" |
Slots
Name | Description |
---|---|
default (unnamed) | A slot for adding custom content. |
Styles
Name | Description |
---|---|
--calcite-sheet-scrim-background | Specifies the background color of the sheet scrim. |
--calcite-sheet-width | When position is "inline-start" or "inline-end" , specifies the width of the component. |
--calcite-sheet-max-width | When position is "inline-start" or "inline-end" , specifies the maximum width of the component. |
--calcite-sheet-min-width | When position is "inline-start" or "inline-end" , specifies the minimum width of the component. |
--calcite-sheet-height | When position is "block-start" or "block-end" , specifies the height of the component. |
--calcite-sheet-max-height | When position is "block-start" or "block-end" , specifies the maximum height of the component. |
--calcite-sheet-min-height | When position is "block-start" or "block-end" , specifies the minimum height of the component. |
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<void> |
setFocus | Sets focus on the component's "close" button - the first focusable item. | setFocus(): Promise<void> |
updateFocusTrapElements | Updates the element(s) that are included in the focus-trap of the component. | updateFocusTrapElements(extraContainers?:
FocusTrapOptions["extraContainers"]): Promise<void> |