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
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.
collapsible to save space when the content contained is non-critical.heading and description properties to provide context to a user.collapsible when critical information or crucial controls are present.Accessibility
Keyboard navigation
| 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-sections. 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-sections. 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 | 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 | expanded property instead.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 | icon-start property instead. | 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-actions 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 | --calcite-block-heading-text-color instead - When the component is expanded, specifies the heading text color. |
| --calcite-block-padding | --calcite-block-content-space instead - Specifies the padding of the component's default slot. |
| --calcite-block-text-color | |
| --calcite-block-description-text-color | Specifies the component's description text color. |
| --calcite-block-icon-color | Specifies the component's collapsible icon, iconStart and iconEnd color. |
| --calcite-block-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. | |
| calciteBlockBeforeOpen | Fires when the component is added to the DOM but not rendered, and before the opening transition begins. | |
| calciteBlockClose | Fires when the component is closed and animation is complete. | |
| calciteBlockCollapse | Fires when the component's content area is collapsed. | |
| calciteBlockExpand | Fires when the component's content area is expanded. | |
| calciteBlockOpen | Fires when the component is open and animation is complete. | |
| calciteBlockSortHandleBeforeClose | Fires when the sort handle is requested to be closed and before the closing transition begins. | |
| calciteBlockSortHandleBeforeOpen | Fires when the sort handle is added to the DOM but not rendered, and before the opening transition begins. | |
| calciteBlockSortHandleClose | Fires when the sort handle is closed and animation is complete. | |
| calciteBlockSortHandleOpen | Fires when the sort handle is open and animation is complete. | |
| calciteBlockToggle | openClose events such as calciteBlockOpen, calciteBlockClose, calciteBlockBeforeOpen, and calciteBlockBeforeClose instead. |
Methods
| Name | Description | Signature |
|---|---|---|
| componentOnReady | Create a promise that resolves once component is fully loaded. | componentOnReady(): Promise<this> |
| setFocus | Sets focus on the component's first tabbable element. | setFocus(options?: FocusOptions): Promise<void> |