Block

Block provides a way to organize and group related controls or content.

Overview

Blocks should be used to house content and controls within Panel, most often as part of an application layout comprised of Shell Panels and Shell.

Usage

  • Organize and group controls or interactive elements.
  • Provide consistent spacing, placement, and arrangement of content within a Panel.

Sample

2 samples
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<calcite-shell>
    <calcite-shell-panel slot="panel-start" width="l">
        <calcite-panel heading="Block example">
            <calcite-block collapsible open heading="Layer effects" description="Adjust blur, highlight, and more"
                icon-start="effects">
                <calcite-notice open>
                    <div slot="message">Use layer effects sparingly, for emphasis</div>
                </calcite-notice>
                <calcite-action slot="control" text="Information" icon="information"></calcite-action>
                <div slot="header-menu-actions">
                    <calcite-action text="Information" icon="information" text-enabled></calcite-action>
                </div>
            </calcite-block>
        </calcite-panel>
    </calcite-shell-panel>
    <calcite-panel heading="Content"></calcite-panel>
</calcite-shell>
v3.0.2

Best Practices

While similar to an Accordion, Blocks are unique in that they are intended to be the primary method of organization within a Panel. Conversely, Accordion can be used to organize non-critical or text-heavy content, outside of a Panel.

Blocks often contain application-specific functionality, controls, or information. While this frequently includes form controls or other interactive elements, it is also appropriate to use a Block to contain static or descriptive text-based content.

Blocks can also be collapsible - when enabled, ensure proper context is provided with the heading and description properties. Additional context can be provided by using an Icon in the icon slot.

Do use one or more Block(s) within Panel to house application controls and interactive elements.
Do make Block collapsible to save space when the content contained is non-critical.
Do make use of heading and description properties to provide context to a user.
Avoid using Block outside of a Panel.
Avoid making Block collapsible when critical information or crucial controls are present.

Accessibility

Keyboard navigation

KeyFunction
EnterToggles the "Expand"/"Collapse" focused component.
SpaceToggles the "Expand"/"Collapse" focused component.
TabMoves focus into/out of the component or moves between calcite-block-sections. If the currently focused step is the last step, focus will leave the component
Tab and ShiftMoves focus into/out of the component or moves between calcite-block-sections. If the currently focused step is the first step, focus will leave the component

API reference

Properties

PropertyAttributeDescriptionTypeDefault
collapsiblecollapsibleWhen true, the component is collapsible.booleanfalse
descriptiondescriptionA description for the component, which displays below the heading.string
disableddisabledWhen true, interaction is prevented and the component is displayed with lower opacity.booleanfalse
dragDisableddrag-disabledWhen true, and a parent Block Group is dragEnabled, the component is not draggable.booleanfalse
dragHandledrag-handle
deprecatedNo longer necessary. Use Block Group for draggable functionality.
When true, the component displays a draggable button.
booleanfalse
headingheadingThe component header text.string
headingLevelheading-levelSpecifies the heading level of the component's heading for proper document structure, without affecting visual styling.1 | 2 | 3 | 4 | 5 | 6
iconEndicon-endSpecifies an icon to display at the end of the component.string
iconFlipRtlicon-flip-rtlDisplays the iconStart and/or iconEnd as flipped when the element direction is right-to-left ("rtl")."both" | "end" | "start"
iconStarticon-startSpecifies an icon to display at the start of the component.string
labellabelSpecifies an accessible name for the component.string
loadingloadingWhen true, a busy indicator is displayed.booleanfalse
menuFlipPlacementsSpecifies the component's fallback menu placement when it's initial or specified placement has insufficient space available.Array<"top" | "bottom" | "right" | "left" | "top-start" | "top-end" | "bottom-start" | "bottom-end" | "right-start" | "right-end" | "left-start" | "left-end" | "leading-start" | "leading" | "leading-end" | "trailing-end" | "trailing" | "trailing-start">
menuPlacementmenu-placementDetermines where the action menu will be positioned."auto" | "auto-end" | "auto-start" | "bottom" | "bottom-end" | "bottom-start" | "leading" | "leading-end" | "leading-start" | "left" | "left-end" | "left-start" | "right" | "right-end" | "right-start" | "top" | "top-end" | "top-start" | "trailing" | "trailing-end" | "trailing-start""bottom-end"
messageOverridesUse this property to override individual strings used by the component.{ collapse?: string; expand?: string; loading?: string; options?: string; }
openopenWhen true, expands the component and its contents.booleanfalse
overlayPositioningoverlay-positioningDetermines the type of positioning to use for the overlaid content. Using "absolute" will work for most cases. The component will be positioned inside of overflowing parent containers and will affect the container's layout. "fixed" should be used to escape an overflowing parent container, or when the reference element's position CSS property is "fixed"."absolute" | "fixed""absolute"
sortHandleOpensort-handle-openWhen true, displays and positions the sort handle.booleanfalse
statusstatus
deprecatedUse icon-start instead.
Displays a status-related indicator icon.
"idle" | "invalid" | "valid"

Slots

NameDescription
default (unnamed)A slot for adding custom content.
actions-endA slot for adding actionable calcite-action elements after the content of the component. It is recommended to use two or fewer actions.
icon
deprecated A slot for adding a leading header icon with calcite-icon. Use icon-start instead.
content-startA slot for adding non-actionable elements before content of the component.
control
deprecated A slot for adding a single HTML input element in a header. Use actions-end instead.
header-menu-actionsA slot for adding an overflow menu with calcite-actions inside a dropdown menu.

Styles

NameDescription
--calcite-block-border-colorSpecifies the component's border color.
--calcite-block-header-background-colorSpecifies the component's heading background color.
--calcite-block-header-background-color-hoverSpecifies the component's heading background color when hovered.
--calcite-block-heading-text-colorSpecifies the component's heading text color.
--calcite-block-heading-text-color-pressWhen the component is open, specifies the heading text color.
--calcite-block-padding
deprecated Specifies the padding of the component's default slot.
--calcite-block-text-colorSpecifies the component's text color.

Events

NameDescriptionBehavior
calciteBlockBeforeCloseFires when the component is requested to be closed and before the closing transition begins.bubblescomposed
calciteBlockBeforeOpenFires when the component is added to the DOM but not rendered, and before the opening transition begins.bubblescomposed
calciteBlockCloseFires when the component is closed and animation is complete.bubblescomposed
calciteBlockOpenFires when the component is open and animation is complete.bubblescomposed
calciteBlockSortHandleBeforeCloseFires when the sort handle is requested to be closed and before the closing transition begins.bubblescomposed
calciteBlockSortHandleBeforeOpenFires when the sort handle is added to the DOM but not rendered, and before the opening transition begins.bubblescomposed
calciteBlockSortHandleCloseFires when the sort handle is closed and animation is complete.bubblescomposed
calciteBlockSortHandleOpenFires when the sort handle is open and animation is complete.bubblescomposed
calciteBlockToggle
deprecatedUse openClose events such as calciteBlockOpen, calciteBlockClose, calciteBlockBeforeOpen, and calciteBlockBeforeClose instead.
Fires when the component's header is clicked.
bubblescomposed

Methods

NameDescriptionSignature
componentOnReadyCreate a promise that resolves once component is fully loaded.componentOnReady(): Promise<void>
setFocusSets focus on the component's first tabbable element.setFocus(): 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