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. | truefalse | |
| dragEnabled | drag-enabled | When true, list items are sortable via a draggable button. | truefalse | |
| 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. | truefalse | |
| 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. | truefalse | |
| 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. | truefalse | |
| selectionFollowsFocus | selection-follows-focus | When true and single-selection is enabled, the selection changes when navigating list items via the keyboard. | truefalse |
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. | truefalse | |
| 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. | truefalse | |
| removable | removable | When true, adds an action to remove the list item. | truefalse | |
| selected | selected | When true, preselects the list item. Toggles when an item is checked/unchecked. | truefalse | |
| 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. |