List

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 selectionMode and accommodate filtering with filterEnabled.

Usage

  • Format a series of line items
  • Grouping line items

Sample

9 samples
1
2
3
4
5
6
7
8
9
10
11
<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>
v3.0.0

Accessibility

Keyboard navigation

KeyFunction
Arrow downNavigates to the next calcite-list-item.
Arrow upNavigates to the previous calcite-list-item.
Arrow rightNavigates 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 leftNavigates 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.
HomeNavigates to the first calcite-list-item.
EndNavigates to the last calcite-list-item.
TabNavigates 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 ShiftNavigates 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.
SpaceWhen the component is dragEnabled 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

PropertyAttributeDescriptionTypeDefault
canPullWhen provided, the method will be called to determine whether the element can move from the list.(detail: ListDragDetail) => boolean
canPutWhen provided, the method will be called to determine whether the element can be added from another list.(detail: ListDragDetail) => boolean
disableddisabledWhen true, interaction is prevented and the component is displayed with lower opacity.booleanfalse
displayModedisplay-modeSpecifies the nesting behavior of calcite-list-items, where "flat" displays calcite-list-items in a uniform list, and "nested" displays calcite-list-items under their parent element. The parent component's behavior should follow throughout its child elements."flat" | "nested""flat"
dragEnableddrag-enabledWhen true, calcite-list-items are sortable via a draggable button.booleanfalse
filteredDataread-onlyThe currently filtered calcite-list-item data.Array<{ label: string; description: string; metadata: Record<string, unknown>; el: HTMLCalciteListItemElement; heading?: Array<string>; }>
filteredItemsread-onlyThe currently filtered calcite-list-items.Array<HTMLCalciteListItemElement>
filterEnabledfilter-enabledWhen true, an input appears at the top of the component that can be used by end users to filter calcite-list-items.booleanfalse
filterLabelfilter-labelSpecifies an accessible name for the filter input field.string
filterPlaceholderfilter-placeholderPlaceholder text for the component's filter input field.string
filterPredicateSpecifies a function to handle filtering.(item: HTMLCalciteListItemElement) => boolean
filterPropsSpecifies the properties to match against when filtering. If not set, all properties will be matched (label, description, metadata, value, group heading).Array<string>
filterTextfilter-textText for the component's filter input field.string
groupgroupThe list's group identifier. To drag elements from one list into another, both lists must have the same group value.string
interactionModeinteraction-modeSpecifies 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"
labelrequiredlabelSpecifies 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
loadingloadingWhen true, a busy indicator is displayed.booleanfalse
messageOverridesUse this property to override individual strings used by the component.{ filterEnabled?: string; total?: string; }
numberingSystemnumbering-systemSpecifies the Unicode numeral system used by the component for localization."arab" | "arabext" | "latn"
scalescaleSpecifies the size of the component."l" | "m" | "s""m"
selectedItemsread-onlyThe currently selected items.Array<HTMLCalciteListItemElement>
selectionAppearanceselection-appearanceSpecifies the selection appearance - "icon" (displays a checkmark or dot) or "border" (displays a border)."border" | "icon""icon"
selectionModeselection-modeSpecifies 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

NameDescription
default (unnamed)A slot for adding calcite-list-item and calcite-list-item-group elements.
filter-actions-startA slot for adding actionable calcite-action elements before the filter component.
filter-actions-endA slot for adding actionable calcite-action elements after the filter component.
filter-no-resultsWhen filterEnabled is true, a slot for adding content to display when no results are found.

Styles

NameDescription
--calcite-list-background-colorSpecifies the component's background color.

Events

NameDescriptionBehavior
calciteListChangeFires when the component's selected items have changed.bubblescomposed
calciteListDragEndFires when the component's dragging has ended.bubblescomposed
calciteListDragStartFires when the component's dragging has started.bubblescomposed
calciteListFilterFires when the component's filter has changed.bubblescomposed
calciteListOrderChangeFires when the component's item order changes.bubblescomposed

Methods

NameDescriptionSignature
componentOnReadyCreate a promise that resolves once component is fully loaded.componentOnReady(): Promise<void>
setFocusSets focus on the component's first focusable element.setFocus(): Promise<void>

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.

You can no longer sign into this site. Go to your ArcGIS portal or the ArcGIS Location Platform dashboard to perform management tasks.

Your ArcGIS portal

Create, manage, and access API keys and OAuth 2.0 developer credentials, hosted layers, and data services.

Your ArcGIS Location Platform dashboard

Manage billing, monitor service usage, and access additional resources.

Learn more about these changes in the What's new in Esri Developers June 2024 blog post.

Close