List organizes list items, grouped items, and their actions.
Overview
Lists can group List Items with List Groups, and leverage slots to include actionable or supplemental elements, such as Actions and Icons. Lists and List Items can support selection workflows using selection
and accommodate filtering with filter
.
Usage
- Format a series of line items
- Grouping line items
Sample
<calcite-list label="Park features">
<calcite-list-item label="Hiking trails" description="Designated routes for hikers to use." value="hiking-trails">
<calcite-action slot="actions-end" icon="layer" text="Trails layer"></calcite-action>
</calcite-list-item>
<calcite-list-item label="Waterfalls" description="Vertical drops from a river." value="waterfalls">
<calcite-action slot="actions-end" icon="layer" text="Waterfalls layer"></calcite-action>
</calcite-list-item>
<calcite-list-item label="Rivers" description="Large naturally flowing watercourses." value="rivers">
<calcite-action slot="actions-end" icon="layer" text="Rivers layer"></calcite-action>
</calcite-list-item>
</calcite-list>
Accessibility
Keyboard navigation
Key | Function |
---|---|
Arrow down | Navigates to the next calcite-list-item . |
Arrow up | Navigates to the previous calcite-list-item . |
Arrow right | Navigates to the next focusable slotted content in the calcite-list-item . If focused on a calcite-list-item with nested calcite-list-items , will expand the nested calcite-list-items . |
Arrow left | Navigates to the previous focusable slotted content in the calcite-list-item . If focused on a calcite-list-item with nested calcite-list-items , will collapse the nested calcite-list-items . |
Home | Navigates to the first calcite-list-item . |
End | Navigates to the last calcite-list-item . |
Tab | Navigates to the next calcite-list-item child calcite-action . If the currently focused calcite-action is the last item, the focus will leave the component. |
Tab and Shift | Navigates to the next calcite-list-item child calcite-action . If the currently focused calcite-action is the last item, the focus will leave the component. |
Space | When the component is drag and a calcite-list-item 's move handle is focused, enables moving the item's placement using the Arrow down and Arrow up keys. |
API reference
Properties
Property | Attribute | Description | Type | Default |
---|---|---|---|---|
canPull | When provided, the method will be called to determine whether the element can move from the list. | (detail: ListDragDetail) => boolean | ||
canPut | When provided, the method will be called to determine whether the element can be added from another list. | (detail: ListDragDetail) => boolean | ||
disabled | disabled | When true , interaction is prevented and the component is displayed with lower opacity. | boolean | false |
displayMode | display-mode | Specifies the nesting behavior of calcite-list-item s, where
"flat" displays calcite-list-item s in a uniform list, and
"nested" displays calcite-list-item s under their parent element.
The parent component's behavior should follow throughout its child elements. | "flat" | "nested" | "flat" |
dragEnabled | drag-enabled | When true , calcite-list-item s are sortable via a draggable button. | boolean | false |
filteredData | The currently filtered calcite-list-item data. | Array<{
label: string;
description: string;
metadata: Record<string, unknown>;
el: HTMLCalciteListItemElement;
heading?: Array<string>;
}> | ||
filteredItems | The currently filtered calcite-list-item s. | Array<HTMLCalciteListItemElement> | ||
filterEnabled | filter-enabled | When true , an input appears at the top of the component that can be used by end users to filter calcite-list-item s. | boolean | false |
filterLabel | filter-label | Specifies an accessible name for the filter input field. | string | |
filterPlaceholder | filter-placeholder | Placeholder text for the component's filter input field. | string | |
filterPredicate | Specifies a function to handle filtering. | (item: HTMLCalciteListItemElement) => boolean | ||
filterProps | Specifies the properties to match against when filtering. If not set, all properties will be matched (label, description, metadata, value, group heading). | Array<string> | ||
filterText | filter-text | Text for the component's filter input field. | string | |
group | group | The list's group identifier. To drag elements from one list into another, both lists must have the same group value. | string | |
interactionMode | interaction-mode | Specifies the interaction mode of the component.
"interactive" allows interaction styling and pointer changes on hover
"static" does not allow interaction styling and pointer changes on hover
The "static" value should only be used when selectionMode is "none" . | "interactive" | "static" | "interactive" |
label | label | Specifies an accessible name for the component.
When dragEnabled is true and multiple list sorting is enabled with group , specifies the component's name for dragging between lists. | string | |
loading | loading | When true , a busy indicator is displayed. | boolean | false |
messageOverrides | Use this property to override individual strings used by the component. | {
filterEnabled?: string;
total?: string;
} | ||
numberingSystem | numbering-system | Specifies the Unicode numeral system used by the component for localization. | "arab" | "arabext" | "latn" | |
scale | scale | Specifies the size of the component. | "l" | "m" | "s" | "m" |
selectedItems | The currently selected items. | Array<HTMLCalciteListItemElement> | ||
selectionAppearance | selection-appearance | Specifies the selection appearance - "icon" (displays a checkmark or dot) or "border" (displays a border). | "border" | "icon" | "icon" |
selectionMode | selection-mode | Specifies the selection mode of the component, where:
"multiple" allows any number of selections,
"single" allows only one selection,
"single-persist" allows one selection and prevents de-selection, and
"none" does not allow any selections. | "multiple" | "none" | "single" | "single-persist" | "none" |
Slots
Name | Description |
---|---|
default (unnamed) | A slot for adding calcite-list-item and calcite-list-item-group elements. |
filter-actions-start | A slot for adding actionable calcite-action elements before the filter component. |
filter-actions-end | A slot for adding actionable calcite-action elements after the filter component. |
filter-no-results | When filterEnabled is true , a slot for adding content to display when no results are found. |
Styles
Name | Description |
---|---|
--calcite-list-background-color | Specifies the component's background color. |
Events
Name | Description | Behavior |
---|---|---|
calciteListChange | Fires when the component's selected items have changed. | |
calciteListDragEnd | Fires when the component's dragging has ended. | |
calciteListDragStart | Fires when the component's dragging has started. | |
calciteListFilter | Fires when the component's filter has changed. | |
calciteListOrderChange | Fires when the component's item order changes. |
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 focusable element. | setFocus(): Promise<void> |