Block | Calcite Design System

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

Overview

Blocks are often used in application layouts within Panel, and support hiding and showing sections of related content. Refer to layout patterns to learn more about Calcite's foundational layout components.

Sample

Usage

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

Best practices

Block is a foundational layout component. Consider using Block within components intended to house content such as Panel and Flow Item. For additional layout considerations, refer to layout patterns and layout samples.

An expandable Block that contains a list of supplemental reading resources. The Block is shown in its collapsed and expanded states to toggle the visual representation of supplemental GIS readings.

Do consider using expandable Blocks to save space when content is not essential.

Do use heading and description properties to provide context to a user when Block content is collapsed.

An expandable Block that contains a terms and conditions form. When expanded, the Block provides context. When collapsed, essential information on the terms and conditions is not displayed.

Avoid using expandable Blocks to display essential information. When the component is collapsed slotted content will not be visible.

Accessibility

Key	Function
`Enter`	Toggles the "Expand"/"Collapse" focused component.
`Space`	Toggles the "Expand"/"Collapse" focused component.
`Tab`	Moves focus into/out of the component or moves between `calcite-block-section`s. If the currently focused step is the last step, focus will leave the component
`Tab` and `Shift`	Moves focus into/out of the component or moves between `calcite-block-section`s. If the currently focused step is the first step, focus will leave the component

API reference

Properties

Property	Attribute	Description	Type	Default
collapsible	collapsible	deprecatedin v5.2.0, removal target v7.0.0 - Use the `expandable` property instead. When `true`, the component can be expanded and collapsed.	`boolean`	`false`
description	description	Specifies a description for the component. Displays below the `heading`.	`string \| undefined`
disabled	disabled	When `true`, interaction is prevented and the component is displayed with lower opacity.	`boolean`	`false`
dragDisabled	drag-disabled	When `true`, and a parent `calcite-block-group` is `dragEnabled`, the component is not draggable.	`boolean`	`false`
dragHandle	drag-handle	deprecatedin v3.0.0, removal target v6.0.0 - No longer necessary. Use Block Group for draggable functionality. When `true`, the component displays a draggable button.	`boolean`	`false`
expandable	expandable	When `true`, the component can be expanded and collapsed.	`boolean`	`false`
expanded	expanded	When `true`, expands the component and its contents.	`boolean`	`false`
heading	heading	Specifies the component's heading text.	`string \| undefined`
headingLevel	heading-level	Specifies the heading level number of the component's `heading` for proper document structure, without affecting visual styling.	`HeadingLevel \| undefined`
iconEnd	icon-end	Specifies an icon to display at the end of the component.	`IconName \| undefined`
iconFlipRtl	icon-flip-rtl	Displays the `iconStart` and/or `iconEnd` as flipped when the element direction is right-to-left (`"rtl"`).	`FlipContext \| undefined`
iconStart	icon-start	Specifies an icon to display at the start of the component.	`IconName \| undefined`
label	label	Specifies an accessible label for the component.	`string \| undefined`
loading	loading	When `true`, a busy indicator is displayed.	`boolean`	`false`
menuFlipPlacements		Specifies the component's fallback `menuPlacement` when its initial or specified `menuPlacement` has insufficient space available.	`FlipPlacement[] \| undefined`
menuPlacement	menu-placement	Determines where the action menu will be positioned.	`LogicalPlacement`	`"bottom-end"`
messageOverrides		Replace localized message strings with your own strings. Note: Individual message keys may change between releases.	`Record<string, unknown> \| undefined`
open	open	deprecatedin v3.1.0, removal target v6.0.0 - Use the `expanded` property instead. When `true`, expands the component and its contents.	`boolean`	`false`
overlayPositioning	overlay-positioning	Specifies the type of positioning to use for overlaid content. `"absolute"` works for most cases - positioning the component inside of overflowing parent containers, which affects the container's layout. `"fixed"` is used to escape an overflowing parent container, or when the reference element's `position` CSS property is `"fixed"`.	`OverlayPositioning`	`"absolute"`
scale	scale	Specifies the size of the component.	`Scale`	`"m"`
sortHandleOpen	sort-handle-open	When `true`, displays and positions the sort handle.	`boolean`	`false`
status	status	deprecatedin v3.0.0, removal target v6.0.0 - Use the `icon-start` property instead. Displays a status-related indicator icon.	`Status \| undefined`
toggleDisplay	toggle-display	Specifies how the component's toggle is displayed, where: `"button"` sets the toggle to a selectable header, and `"switch"` sets the toggle to a switch.	`BlockToggleDisplay`	`"button"`
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`

Slots

Name	Description
default (unnamed)	A slot for adding custom content.
actions-end	A slot for adding actionable `calcite-action` elements after the content of the component. It is recommended to use two or fewer actions.
content-end	A slot for adding non-actionable elements after the component's header text.
content-start	A slot for adding non-actionable elements before the component's header text.
header-menu-actions	A slot for adding an overflow menu with `calcite-action`s inside a dropdown menu.
children	A slot for adding `calcite-block` & `calcite-block-group` elements.

Styles

Name	Description
--calcite-block-border-color	Specifies the component's border color.
--calcite-block-content-space	Specifies the space of the component's `default` slot.
--calcite-block-background-color	Specifies the component's background color.
--calcite-block-header-background-color	deprecated in v5.2.0, removal target v7.0.0 - Use `--calcite-block-background-color` instead. Specifies the component's `heading` background color.
--calcite-block-header-background-color-hover	Specifies the component's `heading` background color when hovered.
--calcite-block-header-background-color-press	Specifies the component's `heading` background color when pressed.
--calcite-block-heading-text-color	Specifies the component's `heading` text color.
--calcite-block-heading-text-color-press	deprecated in v3.3.0, removal target v6.0.0 - Use `--calcite-block-heading-text-color` instead. When the component is `expanded`, specifies the `heading` text color.
--calcite-block-padding	deprecated in v3.3.0, removal target v6.0.0 - Use `--calcite-block-content-space` instead. Specifies the padding of the component's `default` slot.
--calcite-block-text-color	deprecated in v3.3.0, removal target v6.0.0. Specifies the component's text color.
--calcite-block-description-text-color	Specifies the component's `description` text color.
--calcite-block-icon-color	deprecated in v5.1.0, removal target v7.0.0 - Use `--calcite-block-expandable-icon-color`, `--calcite-block-icon-start-color` and `--calcite-block-icon-end-color` instead. Specifies the component's `expandable` icon, `iconStart` and `iconEnd` color.
--calcite-block-icon-color-hover	deprecated in v5.1.0, removal target v7.0.0 - Use `--calcite-block-expandable-icon-color-hover` instead. Specifies the component's `expandable` icon color when hovered.
--calcite-block-icon-start-color	Specifies the component's `iconStart` color.
--calcite-block-icon-end-color	Specifies the component's `iconEnd` color.
--calcite-block-expandable-icon-color	Specifies the component's `expandable` icon color.
--calcite-block-expandable-icon-color-hover	Specifies the component's `expandable` icon color when hovered.
--calcite-block-collapsible-icon-color	deprecated in v5.2.0, removal target v7.0.0 - Use `--calcite-block-expandable-icon-color` instead. Specifies the component's `expandable` or `collapsible` (deprecated) icon color.
--calcite-block-collapsible-icon-color-hover	deprecated in v5.2.0, removal target v7.0.0 - Use `--calcite-block-expandable-icon-color-hover` instead. Specifies the component's `expandable` or `collapsible` (deprecated) icon color when hovered.

Events

Name	Description	Behavior
calciteBlockBeforeClose	deprecatedin v3.1.0, removal target v6.0.0 - No direct replacement. Use `calciteBlockCollapse` to respond when the component's `expanded` state changes. Fires when the component is requested to be closed and before the closing transition begins.	bubblescomposed
calciteBlockBeforeOpen	deprecatedin v3.1.0, removal target v6.0.0 - No direct replacement. Use `calciteBlockExpand` to respond when the component's `expanded` state changes. Fires when the component is added to the DOM but not rendered, and before the opening transition begins.	bubblescomposed
calciteBlockClose	deprecatedin v3.1.0, removal target v6.0.0 - Use `calciteBlockCollapse` instead. Fires when the component is closed and animation is complete.	bubblescomposed
calciteBlockCollapse	Fires when the component's content area is collapsed.	bubblescomposed
calciteBlockExpand	Fires when the component's content area is expanded.	bubblescomposed
calciteBlockOpen	deprecatedin v3.1.0, removal target v6.0.0 - Use `calciteBlockExpand` instead. Fires when the component is open and animation is complete.	bubblescomposed
calciteBlockSortHandleBeforeClose	Fires when the sort handle is requested to be closed and before the closing transition begins.	bubblescomposed
calciteBlockSortHandleBeforeOpen	Fires when the sort handle is added to the DOM but not rendered, and before the opening transition begins.	bubblescomposed
calciteBlockSortHandleClose	Fires when the sort handle is closed and animation is complete.	bubblescomposed
calciteBlockSortHandleOpen	Fires when the sort handle is open and animation is complete.	bubblescomposed
calciteBlockToggle	deprecatedin v3.0.0, removal target v6.0.0 - Use `openClose` events such as `calciteBlockOpen`, `calciteBlockClose`, `calciteBlockBeforeOpen`, and `calciteBlockBeforeClose` instead. Fires when the component's header is clicked.	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 first tabbable element.	`setFocus(options?: FocusOptions): Promise<void>`