Block | Calcite Design System

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.

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.

A collapsible 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 collapsible 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.

A collapsible 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 collapsible 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	When `true`, the component is collapsible.	`boolean`	`false`
description	description	Specifies a description for the component. Displays below the heading.	`string`
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`
expanded	expanded	When `true`, expands the component and its contents.	`boolean`	`false`
heading	heading	Specifies the component's heading text.	`string`
headingLevel	heading-level	Specifies the heading level number of the component's `heading` for proper document structure, without affecting visual styling.	`HeadingLevel`
iconEnd	icon-end	Specifies an icon to display at the end of the component.	`IconName`
iconFlipRtl	icon-flip-rtl	Displays the `iconStart` and/or `iconEnd` as flipped when the element direction is right-to-left (`"rtl"`).	`FlipContext`
iconStart	icon-start	Specifies an icon to display at the start of the component.	`IconName`
label	label	Specifies an accessible label for the component.	`string`
loading	loading	When `true`, a busy indicator is displayed.	`boolean`	`false`
menuFlipPlacements		Specifies the component's fallback `menuPlacement` when it's initial or specified `menuPlacement` has insufficient space available.	`FlipPlacement[]`
menuPlacement	menu-placement	Determines where the action menu will be positioned.	`LogicalPlacement`	`"bottom-end"`
messageOverrides		Overrides individual strings used by the component.	`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, where: `"absolute"` works for most cases - positioning the component inside of overflowing parent containers, which affects the container's layout, and `"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`
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.

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-header-background-color	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-collapsible-icon-color`, `--calcite-block-icon-start-color` and `--calcite-block-icon-end-color` instead. Specifies the component's `collapsible` icon, `iconStart` and `iconEnd` color.
--calcite-block-icon-color-hover	deprecated in v5.1.0, removal target v7.0.0 - Use `--calcite-block-collapsible-icon-color-hover` instead. Specifies the component's `collapsible` 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-collapsible-icon-color	Specifies the component's `collapsible` icon color.
--calcite-block-collapsible-icon-color-hover	Specifies the component's `collapsible` icon color when hovered.

Events

Name	Description	Behavior
calciteBlockBeforeClose	Fires when the component is requested to be closed and before the closing transition begins.	bubblescomposed
calciteBlockBeforeOpen	Fires when the component is added to the DOM but not rendered, and before the opening transition begins.	bubblescomposed
calciteBlockClose	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	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>`