Sheet

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.

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 have focusable elements cycle through Sheet where focusTrapDisabled 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

KeyFunction
TabMoves 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 ShiftMoves focus to previous focusable element. If the current focus is the first element and focusTrapDisabled is false, focus will cycle to the last element.
EscIf escapeDisabled is false, closes the component.

API reference

Properties

PropertyAttributeDescriptionTypeDefault
beforeClosePasses a function to run before the component closes.(el: HTMLCalciteSheetElement) => Promise<void>
displayModedisplay-modeSpecifies the display mode - "float" (content is separated detached), or "overlay" (displays on top of center content)."float" | "overlay""overlay"
escapeDisabledescape-disabledWhen true, disables the default close on escape behavior.booleanfalse
focusTrapDisabledfocus-trap-disabledWhen true, prevents focus trapping.booleanfalse
focusTrapOptionsSpecifies 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>; }
heightheightSpecifies the height of the component."l" | "m" | "s"
heightScaleheight-scale
deprecatedUse the height property instead.
When position is "block-start" or "block-end", specifies the height of the component.
"l" | "m" | "s""m"
labelrequiredlabelSpecifies the label of the component.string
messageOverridesUse this property to override individual strings used by the component.{ resizeEnabled?: string; }
openopenWhen true, displays and positions the component.booleanfalse
outsideCloseDisabledoutside-close-disabledWhen true, disables the closing of the component when clicked outside.booleanfalse
positionpositionDetermines where the component will be positioned."block-end" | "block-start" | "inline-end" | "inline-start""inline-start"
resizableresizableWhen true, the component is resizable.booleanfalse
widthwidthSpecifies the width of the component."l" | "m" | "s"
widthScalewidth-scale
deprecatedUse the width property instead.
When position is "inline-start" or "inline-end", specifies the width of the component.
"l" | "m" | "s""m"

Slots

NameDescription
default (unnamed)A slot for adding custom content.

Styles

NameDescription
--calcite-sheet-scrim-backgroundSpecifies the background color of the sheet scrim.
--calcite-sheet-widthWhen position is "inline-start" or "inline-end", specifies the width of the component.
--calcite-sheet-max-widthWhen position is "inline-start" or "inline-end", specifies the maximum width of the component.
--calcite-sheet-min-widthWhen position is "inline-start" or "inline-end", specifies the minimum width of the component.
--calcite-sheet-heightWhen position is "block-start" or "block-end", specifies the height of the component.
--calcite-sheet-max-heightWhen position is "block-start" or "block-end", specifies the maximum height of the component.
--calcite-sheet-min-heightWhen position is "block-start" or "block-end", specifies the minimum height of the component.

Events

NameDescriptionBehavior
calciteSheetBeforeCloseFires when the component is requested to be closed and before the closing transition begins.bubblescomposed
calciteSheetBeforeOpenFires when the component is added to the DOM but not rendered, and before the opening transition begins.bubblescomposed
calciteSheetCloseFires when the component is closed and animation is complete.bubblescomposed
calciteSheetOpenFires when the component is open and animation is complete.bubblescomposed

Methods

NameDescriptionSignature
componentOnReadyCreate a promise that resolves once component is fully loaded.componentOnReady(): Promise<void>
setFocusSets focus on the component's "close" button - the first focusable item.setFocus(): Promise<void>
updateFocusTrapElementsUpdates the element(s) that are included in the focus-trap of the component.updateFocusTrapElements(extraContainers?: FocusTrapOptions["extraContainers"]): Promise<void>

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.

You can no longer sign into this site. Go to your ArcGIS portal or the ArcGIS Location Platform dashboard to perform management tasks.

Your ArcGIS portal

Create, manage, and access API keys and OAuth 2.0 developer credentials, hosted layers, and data services.

Your ArcGIS Location Platform dashboard

Manage billing, monitor service usage, and access additional resources.

Learn more about these changes in the What's new in Esri Developers June 2024 blog post.

Close