Value List
Calcite Value List provides a list of operational items in the interface.
Overview
In a configuration, the user may have selected a small number of items from a list of many items. Value List offers a view of the items that are relevant to the interface in that moment.
Value List enables sorting and removing. Its children can also have a selected state for when an operative item requires additional configuration. Additionally, Value List has a filtering prop that leverages Calcite Filter.
Populate Calcite Value List with Calcite Value List Item.
Usage
- Display operational items in a configuration
- Enable reordering of operational items
- Enable configuration of operational items
Sample
Accessibility
Keyboard navigation
Key | Function |
---|---|
Arrow down | Move focus and selection to previous item. If the current focus and selection is the first item, the focus and selection will cycle to the end |
Arrow up | Move focus and selection to next item. If the current focus and selection is the last item, the focus and selection will cycle to the beginning |
Tab | Move focus in and out of component |
Tab and Shift | Move focus in and out of component |
When using the component with drag-enabled
, additional keyboard functionality is available.
Key | Function |
---|---|
Space | While focused on the drag handle, enter or exit the drag mode |
Arrow down | While in the drag mode, move the current item up in the list order |
Arrow up | While in the drag mode, move the current item down in the list order |
API reference
Properties
Property | Attribute | Description | Type | Values |
---|---|---|---|---|
disabled | disabled | When true, prevents user interaction. This state shows list items grayed out and with lower opacity. | true false | |
dragEnabled | drag-enabled | When true, list items are sortable via a draggable button. | true false | |
filterEnabled | filter-enabled | When true, an input appears at the top of the list that can be used by end users to filter list items. | true false | |
filterPlaceholder | filter-placeholder | Placeholder text for the filter's input field. | undefined | |
group | group | The list's group identifier. To drag elements from one list into another, both lists must have the same group value. | undefined | |
loading | loading | When true, content is waiting to be loaded. This state shows a busy indicator. | true false | |
multiple | multiple | Similar to standard radio buttons and checkboxes. When true, a user can select multiple list items at a time. When false, only a single list item can be selected at a time, and selecting a new list item will deselect any other selected list items. | true false | |
selectionFollowsFocus | selection-follows-focus | When true and single-selection is enabled, the selection changes when navigating list items via the keyboard. | true false |
Events
Name | Description | Detail |
---|---|---|
calciteListChange | Emits when any of the list item selections have changed. | Map<string, HTMLCalciteValueListItemElement> |
calciteListOrderChange | Emits when the order of the list has changed. | any[] |
Methods
Name | Description | Signature | Returns |
---|---|---|---|
getSelectedItems | Returns the currently selected items | getSelectedItems() => Promise<Map<string, HTMLCalciteValueListItemElement>> | Promise<Map<string, HTMLCalciteValueListItemElement>> |
setFocus | Sets focus on the component. | setFocus(focusId?: ListFocusId) => Promise<void> | Promise<void> |
Slots
Name | Description |
---|---|
default (unnamed) | A slot for adding `calcite-value-list-item` elements. List items are displayed as a vertical list. |
menu-actions | A slot for adding a button and menu combination for performing actions, such as sorting. |
Properties
Property | Attribute | Description | Type | Values |
---|---|---|---|---|
description | description | An optional description for the list item that displays below the label text. | undefined | |
disabled | disabled | When true, the list item cannot be clicked and is visually muted. | true false | |
icon | icon | Determines the icon SVG symbol that will be shown. Options are circle, square, grip or null. | ||
label | label | The main label for the list item. Appears next to the icon. | undefined | |
metadata | Provides additional metadata to a list item. Primary use is for a filter on the parent list. | { [x: string]: unknown; } | ||
nonInteractive | non-interactive | When true, prevents the content of the list item from user interaction. | true false | |
removable | removable | When true, adds an action to remove the list item. | true false | |
selected | selected | When true, preselects the list item. Toggles when an item is checked/unchecked. | true false | |
value | value | The list item's associated value. | any |
Events
Name | Description | Detail |
---|---|---|
calciteListItemRemove | Emits when the remove button is pressed. | void |
Methods
Name | Description | Signature | Returns |
---|---|---|---|
setFocus | Set focus on the component. | setFocus() => Promise<void> | Promise<void> |
toggleSelected | Toggle the selection state. By default this won't trigger an event. The first argument allows the value to be coerced, rather than swapping values. | toggleSelected(coerce?: boolean) => Promise<void> | Promise<void> |
Slots
Name | Description |
---|---|
actions-end | A slot for adding actions or content to the end side of the item. |
actions-start | A slot for adding actions or content to the start side of the item. |