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

Show code snippetCopy code snippet
Edit sample on Codepen
v1.0.0-beta.83
Toggle preview themeToggle preview direction

Accessibility

Keyboard navigation

KeyFunction
Arrow downMove 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 upMove 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
TabMove focus in and out of component
Tab and ShiftMove focus in and out of component

When using the component with drag-enabled, additional keyboard functionality is available.

KeyFunction
SpaceWhile focused on the drag handle, enter or exit the drag mode
Arrow downWhile in the drag mode, move the current item up in the list order
Arrow upWhile in the drag mode, move the current item down in the list order

API reference

calcite-value-list
v1.0.0-beta.83

Properties

PropertyAttributeDescriptionTypeValues
disableddisabled

When true, prevents user interaction. This state shows list items grayed out and with lower opacity.

booleanA boolean property should be present, or not
truefalse
dragEnableddrag-enabled

When true, list items are sortable via a draggable button.

booleanA boolean property should be present, or not
truefalse
filterEnabledfilter-enabled

When true, an input appears at the top of the list that can be used by end users to filter list items.

booleanA boolean property should be present, or not
truefalse
filterPlaceholderfilter-placeholder

Placeholder text for the filter's input field.

stringA custom string
undefined
groupgroup

The list's group identifier. To drag elements from one list into another, both lists must have the same group value.

optional
stringA custom string
undefined
loadingloading

When true, content is waiting to be loaded. This state shows a busy indicator.

booleanA boolean property should be present, or not
truefalse
multiplemultiple

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.

booleanA boolean property should be present, or not
truefalse
selectionFollowsFocusselection-follows-focus

When true and single-selection is enabled, the selection changes when navigating list items via the keyboard.

booleanA boolean property should be present, or not
truefalse

Events

NameDescriptionDetail
calciteListChange

Emits when any of the list item selections have changed.

bubblescomposedcancelable
Map<string, HTMLCalciteValueListItemElement>
calciteListOrderChange

Emits when the order of the list has changed.

bubblescomposedcancelable
any[]

Methods

NameDescriptionSignatureReturns
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

NameDescription
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.

calcite-value-list-item
v1.0.0-beta.83

Properties

PropertyAttributeDescriptionTypeValues
descriptiondescription

An optional description for the list item that displays below the label text.

optional
stringA custom string
undefined
disableddisabled

When true, the list item cannot be clicked and is visually muted.

booleanA boolean property should be present, or not
truefalse
iconicon

Determines the icon SVG symbol that will be shown. Options are circle, square, grip or null.

optional
typedChoose from a set of typed values
View documentation
labellabel

The main label for the list item. Appears next to the icon.

required
stringA custom string
undefined
metadata

Provides additional metadata to a list item. Primary use is for a filter on the parent list.

optional
typedChoose from a set of typed values
{ [x: string]: unknown; }
nonInteractivenon-interactive

When true, prevents the content of the list item from user interaction.

booleanA boolean property should be present, or not
truefalse
removableremovable

When true, adds an action to remove the list item.

booleanA boolean property should be present, or not
truefalse
selectedselected

When true, preselects the list item. Toggles when an item is checked/unchecked.

booleanA boolean property should be present, or not
truefalse
valuevalue

The list item's associated value.

required
typedChoose from a set of typed values
any

Events

NameDescriptionDetail
calciteListItemRemove

Emits when the remove button is pressed.

bubblescomposedcancelable
void

Methods

NameDescriptionSignatureReturns
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

NameDescription
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.

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