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
<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>
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-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 | A description for the component, which 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 Block Group is dragEnabled , the component is not draggable. | boolean | false |
dragHandle | drag-handle | true , the component displays a draggable button. | boolean | false |
heading | heading | The component header text. | string | |
headingLevel | heading-level | Specifies the heading level of the component's heading for proper document structure, without affecting visual styling. | 1 | 2 | 3 | 4 | 5 | 6 | |
iconEnd | icon-end | Specifies an icon to display at the end of the component. | string | |
iconFlipRtl | icon-flip-rtl | Displays the iconStart and/or iconEnd as flipped when the element direction is right-to-left ("rtl" ). | "both" | "end" | "start" | |
iconStart | icon-start | Specifies an icon to display at the start of the component. | string | |
label | label | Specifies an accessible name for the component. | string | |
loading | loading | When true , a busy indicator is displayed. | boolean | false |
menuFlipPlacements | Specifies 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"> | ||
menuPlacement | menu-placement | Determines 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" |
messageOverrides | Use this property to override individual strings used by the component. | {
collapse?: string;
expand?: string;
loading?: string;
options?: string;
} | ||
open | open | When true , expands the component and its contents. | boolean | false |
overlayPositioning | overlay-positioning | Determines 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" |
sortHandleOpen | sort-handle-open | When true , displays and positions the sort handle. | boolean | false |
status | status | icon-start instead. | "idle" | "invalid" | "valid" |
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. |
icon | calcite-icon . Use icon-start instead. |
content-start | A slot for adding non-actionable elements before content of the component. |
control | actions-end instead. |
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-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-heading-text-color | Specifies the component's heading text color. |
--calcite-block-heading-text-color-press | When the component is open , specifies the heading text color. |
--calcite-block-padding | default slot. |
--calcite-block-text-color | Specifies the component's text color. |
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. | |
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<void> |
setFocus | Sets focus on the component's first tabbable element. | setFocus(): Promise<void> |