List

Displays a list of items which the user can navigate using the keyboard and select using either pointer gestures or the keyboard. Appearance in the built-in themes:

List
//<code-header>
fiddle.title = 'List';
//</code-header>
const list = new List({
    appendTo : targetElement,
    selected : [1],
    items    : [{
        id   : 1,
        text : 'Eggs'
    }, {
        id   : 2,
        text : 'Beef'
    }, {
        id   : 3,
        text : 'Bread'
    }, {
        id   : 4,
        text : 'Cucumber'
    }, {
        id   : 5,
        text : 'Juice'
    }, {
        id   : 6,
        text : 'Tomatoes'
    }, {
        id   : 7,
        text : 'Bacon'
    }]
});

Multi-selection

Set the multiSelect flag to true to allow multiple items to be selected:

Multi-select list
//<code-header>
fiddle.title = 'Multi-select list';
CSSHelper.insertRule('#my-list, .b-list .b-list-title { display:grid; gap:1em; background:transparent;}', targetElement.getRootNode());
CSSHelper.insertRule(`#my-list .b-list-item:not(.b-list-title) {
    padding: 1.3em 1.2em;
    background: var(--b-neutral-100);
    border-radius: 1em;
    font-size:1.1em;
    border: 1px solid var(--b-neutral-94);
    box-shadow: 0px 2px 4px var(--b-neutral-99); }`, targetElement.getRootNode());
//</code-header>
new SlideToggle({
    appendTo : targetElement,
    label    : 'Multiselect',
    checked  : true,
    style    : 'margin-bottom:1em',
    onChange({ checked }) {
        list.multiSelect = checked;
    }
});

const list = new List({
    title       : 'Favourite foods',
    id          : 'my-list',
    width       : 200,
    appendTo    : targetElement,
    multiSelect : true,
    itemTpl     : item => `${item.text}`,
    items       : [{
        id   : 1,
        text : 'Eggs'
    }, {
        id   : 2,
        text : 'Beef'
    }, {
        id   : 3,
        text : 'Bread'
    }, {
        id   : 4,
        text : 'Cucumber'
    }, {
        id   : 5,
        text : 'Juice'
    }, {
        id   : 6,
        text : 'Tomatoes'
    }, {
        id   : 7,
        text : 'Bacon'
    }],
    onItem({ record }) {
        Toast.show('You clicked ' + record.text);
    },
    selected : [1, 2, 3]
});

Grouped list

To group the list contents, simply group your store using groupers. You can decide if clicking a header should toggle all group children (or if it should do nothing) with the allowGroupSelect flag.

const list = new List({
    width            : 400,
    displayField     : 'name',
    multiSelect      : true,
    allowGroupSelect : false,
    // Show icon based on group name
    groupHeaderTpl   : (record, groupName) => `
        <i class="icon-${groupName}"></i>${groupName}
    `,
    value : [1, 4],
    store : new Store({
        fields : [
            'type'
        ],
        groupers : [
            { field : 'type', ascending : true }
        ],
        data : [
            { id : 1, name : 'pizza', type : 'food' },
            { id : 2, name : 'bacon', type : 'food' },
            { id : 3, name : 'egg', type : 'food' },
            { id : 4, name : 'Gin tonic', type : 'drinks' },
            { id : 5, name : 'Wine', type : 'drinks' },
            { id : 6, name : 'Beer', type : 'drinks' }
        ]
    })
});

Grouped list
//<code-header>
fiddle.title = 'Grouped list';
//</code-header>
new SlideToggle({
    appendTo   : targetElement,
    label      : 'Multiselect',
    checked    : true,
    labelWidth : '13em',
    onChange({ checked }) {
        list.multiSelect = checked;
    }
});

new SlideToggle({
    appendTo   : targetElement,
    label      : 'Collapsible groups',
    checked    : true,
    style      : 'margin-bottom:1em',
    labelWidth : '13em',
    onChange({ checked }) {
        list.collapsibleGroups = checked;
    }
});

const list = new List({
    width             : 300,
    height            : 300,
    appendTo          : targetElement,
    multiSelect       : true,
    displayField      : 'name',
    valueField        : 'id',
    collapsibleGroups : true,
    allowGroupSelect  : false,
    selected          : [1, 2, 4],
    itemTpl           : item => `
        <div style="display:flex; align-items:center; padding:.5em;flex:1">
            <img src="data/Core/images/food/${encodeURIComponent(item.image)}"
                 style="width:2em; height:2em; border-radius:.5em; object-fit:cover; margin-inline-end:1em" />
            <div style="flex:1; line-height:1.3;">
                <div>${item.name}</div>
                <div style="font-size:.8em; color:#777;">${item.desc}</div>
            </div>
            <div style="color:#999; margin-inline-start:auto">
                $${item.price.toFixed(2)}
            </div>
        </div>
    `,

    // Show icon based on group name
    groupHeaderTpl : (record, groupName) => {
        let icon;
        switch (groupName) {
            case 'Drinks':
                icon = 'wine-bottle';
                break;
            case 'Food':
                icon = 'pizza-slice';
                break;
            case 'Snacks':
                icon = 'cookie-bite';
                break;
        }
        return `<i class="fa fa-${icon}" style="margin-inline-end:.7em"></i>${groupName}`;
    },
    store : {
        fields : [
            'type'
        ],
        groupers : [
            { field : 'type', ascending : true }
        ],
        data : [
            { id : 1, name : 'Pizza', type : 'food', desc : 'Fresh from the oven', price : 12.50, image : 'pizza.png' },
            { id : 2, name : 'Bacon', type : 'food', desc : 'Crispy and smoky', price : 5.20, image : 'bacon.png'  },
            { id : 3, name : 'Egg', type : 'food', desc : 'Free range-ish', price : 2.10, image : 'egg.png'  },
            { id : 4, name : 'Gin tonic', type : 'drinks', desc : 'Classic mix', price : 8.90, image : 'gintonic.png'  },
            { id : 5, name : 'Wine', type : 'drinks', desc : 'Red, white or sweet', price : 15.00, image : 'redwine.png'  },
            { id : 6, name : 'Pepsi', type : 'drinks', desc : 'Chilled can', price : 2.70, image : 'pepsi.png'  },
            { id : 7, name : 'Potato chips', type : 'snacks', desc : 'Salted crunch', price : 3.40, image : 'chips.png'  },
            { id : 8, name : 'Pretzels', type : 'snacks', desc : 'Twisted delight', price : 2.90, image : 'pretzels.png'  },
            { id : 9, name : 'Popcorn', type : 'snacks', desc : 'Movie night', price : 3.10, image : 'popcorn.png'  },
            { id : 10, name : 'Chocolate bar', type : 'snacks', desc : 'At least 5% cocoa', price : 2.50, image : 'chocolate.png'  },
            { id : 11, name : 'Trail mix', type : 'snacks', desc : 'Nut and raisin blend', price : 4.80, image : 'nuts.png'  }
        ]
    },
    onItem({ item }) {
        Toast.show('You clicked ' + item.innerText);
    }
});

Keyboard shortcuts

A List has the following default keyboard shortcuts:

Keys Action description
Ctrl+a Select all
ArrowRight Expands a group item
ArrowLeft Collapses a group item
Space Toggles selection of currently focused item
Enter Toggles selection of currently focused item

Configs

93

Common

listenersEvents

Other

Configure as true to activate items on mouseover. This is used by the Combo field when using a List as its dropdown.

Configure as true to allow selecting groups (all the group child records will be toggled). Only applicable when the store is grouped.

Configure as true to clear selection when clicking on empty space inside the List´s element.

True to add a collapse icon to toggle groups being collapsed or expanded

displayField: String= text

The model field to render into each list item

The text to show when the list is empty. If not set, the list will be empty.

getItemCls: function | String

Configure this as a function or the name of a function, which when passed a record in the list, returns a CSS class name string to apply to its list item.

ParameterTypeDescription
recordModel

The record

Returns: String
getItemStyle: function | String

Configure this as a function or the name of a function, which when passed a record in the list, returns a style string to apply to its list item.

ParameterTypeDescription
recordModel

The record

Returns: String
groupHeaderTpl: function

Template function which is passed a group record and the uppercased group field name. The text returned will be rendered as the group header.

ParameterTypeDescription
recordModel

The record

groupNameString

The current group name

Returns: String
isSelectable: function | String

A function, or the name of a function in the ownership hierarchy which is used to determine whether a record is selectable. By default, all records are selectable except group header records in a grouped store.

Returns: Boolean -

true if the record is selectable

An array of Objects which are converted into records and used to create this List's store

itemTpl: function | String

Template function (or name of a template function), which, when passed a record, returns the textual HTML for that item. Defaults to a function returning the value of the record´s displayField

ParameterTypeDescription
recordModel

The record

Returns: String

Configure as true to allow multi select and add checkboxes to the items

selectAllItem: Boolean | String= false

Set to true to add a "Select all" item to the list to select/unselect all items at once. Only applies when multiSelect mode is enabled.

selected: Object[] | Number[] | String[] | Collection | CollectionConfigAlso a property

A Collection, or Collection config object to use to contain this List's selected records.

Or, an array encapsulating the initial selection which this List is to have upon Store load. This may be an array of ids , or an array of objects with an id property:

new List({
    // initially select record IDs 1 and 5 when store loads
    selected : [1, 5]
});

A Store which provides the records which map to List items. Each record is passed through the itemTpl to produce the DOM structure of the List. May be generated from an array of items.

The store may also be configured as an array of records, or record data objects from which records may be constructed.

The title to show at the top of the list.

Select/deselect all if CMD/CTRL is pressed when clicking

tooltipTemplate: function

Template function to provide a tooltip (textual, will be automatically HTML-encoded) shown when hovering an item.

ParameterTypeDescription
recordModel

The record representing the item

Returns: String
virtualize: Boolean | Number= false

Controls virtualization of list items using the IntersectionObserver API to render items only when scrolled into view. This is only useful for lists with complex markup, for simple lists it likely adds overhead.

  • false or null - Virtualization disabled (default)
  • true - Always virtualize, regardless of item count
  • {Number} - Virtualize only when item count exceeds this threshold (e.g., 1000)

Set to false to explicitly disable virtualization. This is useful in environments where IntersectionObserver is not available (e.g., Salesforce Locker Service).

Note that the overhead from virtualization is most of the time not worth it. Only enable it if you have really large lists with complex item templates.

columnWidget
rtlRTL
spanWidget

Accessibility

ariaLabelWidget
keyMapKeyMap

CSS

clsWidget
colorWidget
htmlClsWidget
styleWidget
uiWidget

DOM

adoptWidget
appendToWidget
contentWidget
datasetWidget
htmlWidget
idWidget
tagWidget

Float & align

alignWidget
anchorWidget
centeredWidget
draggableWidget
floatingWidget
xWidget
yWidget

Layout

alignSelfWidget
dockWidget
flexWidget
heightWidget
hiddenWidget
marginWidget
maxHeightWidget
maxWidthWidget
minHeightWidget
minWidthWidget
textAlignWidget
weightWidget
widthWidget

Misc

dataFieldWidget
disabledWidget
localeClassLocalizable
localizableLocalizable
maskedWidget
ownerWidget
readOnlyWidget
refWidget
rippleWidget
tabWidget
tooltipWidget

Scrolling

Properties

77

Class hierarchy

isList: Boolean= truereadonly
Identifies an object as an instance of List class, or subclass thereof.
isList: Boolean= truereadonlystatic
Identifies an object as an instance of List class, or subclass thereof.
isDelayableDelayable
isEventsEvents
isKeyMapKeyMap
isLocalizableLocalizable
isWidgetWidget

Other

Configure as true to allow selecting groups (all the group child records will be toggled). Only applicable when the store is grouped.

allSelected: Booleanreadonly

Yields true if all the available items are selected.

Configure as true to clear selection when clicking on empty space inside the List´s element.

True to add a collapse icon to toggle groups being collapsed or expanded

count: Numberreadonly

The number of rendered items in the list, including group headers and the select all item if present.

The text to show when the list is empty. If not set, the list will be empty.

May be set as an array of Objects which are converted into records and used to create this List's store

multiSelect: Boolean= falseAlso a config

Configure as true to allow multi select and add checkboxes to the items

Gets/sets the collection of selected records.

When used as a setter, a record, or record id or array of same may be passed to set the selected records.

A Store which provides the records which map to List items. Each record is passed through the itemTpl to produce the DOM structure of the List. May be generated from an array of items.

The store may also be configured as an array of records, or record data objects from which records may be constructed.

The title to show at the top of the list.

Select/deselect all if CMD/CTRL is pressed when clicking

$namestaticWidget
columnWidget
rtlRTL
spanWidget
typestaticWidget

Accessibility

keyMapKeyMap

CSS

clsWidget

DOM

appendToWidget
contentWidget
datasetWidget
elementWidget
htmlWidget
idWidget
styleWidget

Float & align

xWidget
yWidget

Layout

alignSelfWidget
flexWidget
heightWidget
marginWidget
maxHeightWidget
maxWidthWidget
minHeightWidget
minWidthWidget
widthWidget

Lifecycle

configBase

Misc

cellInfoWidget
disabledWidget
localeHelperLocalizable
localeManagerLocalizable
readOnlyWidget
refWidget
tabWidget
tooltipWidget

Visibility

hiddenWidget
isVisibleWidget

Widget hierarchy

ownerWidget
parentWidget

Functions

65

Other

Returns the DOM element representing the passed record (or record id)

Returns: Element -

The item element

Searches up from the specified element for a list item and returns the associated record.

ParameterTypeDescription
elementHTMLElement

Element somewhere within a list item element

Returns: Model -

Record for the item

Toggles the collapsed state of a group header or tree parent node record

ParameterTypeDescription
recordModel

The group header or parent record

collapseBoolean

Force collapse (true) or expand (false)

composeWidget
createOnFrameDelayable
disableWidget
enableWidget
focusWidget
LstaticLocalizable
maskWidget
onEvents
recomposeWidget
relayAllEvents
triggerEvents
unEvents
unmaskWidget

Selection

Deselects the passed item(s).

An item to deselect may be the id of a record in this List's store, or it may be an object with an id property which is the id of a record in this List's store (For example one of the records).

ParameterTypeDescription
toDeselectString | String[] | Number | Number[] | Object | Object[]

Deselects all selected items

Selects the passed item(s).

An item to select may be the id of a record in this List's store, or it may be an object with an id property which is the id of a record in this List's store (For example one of the records).

ParameterTypeDescription
toSelectString | String[] | Number | Number[] | Object | Object[]
clearSelectedBoolean

Pass true to replace the existing selection.

Selects all items in this list.

Configuration

applyDefaultsstaticBase

Events

Float & align

alignToWidget
setXYWidget
showByWidget
toFrontWidget

Lifecycle

createstaticWidget
destroystaticBase
initClassstaticWidget

Misc

attachTooltipstaticWidget
fromElementstaticWidget
fromSelectorstaticWidget
getByIdstaticWidget
isOfTypeNamestaticBase
mixinstaticBase
optionalLstaticLocalizable

Visibility

hideWidget
showWidget

Widget hierarchy

closestWidget
containsWidget
ownsWidget
queryWidget
queryAllWidget
upWidget

Events

19

User going to activate an item in the list either by pointer or keyboard. The active record, list item index, and the triggering event are passed. It is preventable by returning false

// Adding a listener using the "on" method
list.on('beforeItem', ({ source, item, record, index, event }) => {

});
ParameterTypeDescription
sourceList

The List instance

itemHTMLElement

The clicked list element

recordModel

Activated record

indexNumber

List item index

eventEvent

Triggering event

User activated an item in the list either by pointer or keyboard. The active record, list item index, and the triggering event are passed.

// Adding a listener using the "on" method
list.on('item', ({ source, item, record, index, event }) => {

});
ParameterTypeDescription
sourceList

The List instance

itemHTMLElement

The clicked list element

recordModel

Activated record

indexNumber

List item index

eventEvent

Triggering event

Fired when selection changes

// Adding a listener using the "on" method
list.on('selectionChange', ({ source, selected }) => {

});
ParameterTypeDescription
sourceList

The List instance

selectedModel[]

An array of the currently selected records

Group item expanded or collapsed

// Adding a listener using the "on" method
list.on('toggleGroup', ({ groupRecord, collapse }) => {

});
ParameterTypeDescription
groupRecordModel

Group record

collapseBoolean

Collapsed (true) or expanded (false)

Tree parent node expanded or collapsed

// Adding a listener using the "on" method
list.on('toggleNode', ({ record, collapse }) => {

});
ParameterTypeDescription
recordModel

The parent record which has been toggled

collapseBoolean

Collapsed (true) or expanded (false)

catchAllEvents
destroyEvents
focusInWidget
focusOutWidget
hideWidget
paintWidget
readOnlyWidget
recomposeWidget
resizeWidget
showWidget

Event handlers

19

User going to activate an item in the list either by pointer or keyboard. The active record, list item index, and the triggering event are passed. It is preventable by returning false

new List({
    onBeforeItem({ source, item, record, index, event }) {

    }
});
ParameterTypeDescription
sourceList

The List instance

itemHTMLElement

The clicked list element

recordModel

Activated record

indexNumber

List item index

eventEvent

Triggering event

User activated an item in the list either by pointer or keyboard. The active record, list item index, and the triggering event are passed.

new List({
    onItem({ source, item, record, index, event }) {

    }
});
ParameterTypeDescription
sourceList

The List instance

itemHTMLElement

The clicked list element

recordModel

Activated record

indexNumber

List item index

eventEvent

Triggering event

Called when selection changes

new List({
    onSelectionChange({ source, selected }) {

    }
});
ParameterTypeDescription
sourceList

The List instance

selectedModel[]

An array of the currently selected records

Group item expanded or collapsed

new List({
    onToggleGroup({ groupRecord, collapse }) {

    }
});
ParameterTypeDescription
groupRecordModel

Group record

collapseBoolean

Collapsed (true) or expanded (false)

Tree parent node expanded or collapsed

new List({
    onToggleNode({ record, collapse }) {

    }
});
ParameterTypeDescription
recordModel

The parent record which has been toggled

collapseBoolean

Collapsed (true) or expanded (false)

onDestroyEvents
onFocusInWidget
onHideWidget
onPaintWidget
onResizeWidget
onShowWidget

Typedefs

6

CSS variables

38
NameDescription
--b-list-multi-select-gapGap between list items in a multi select list
--b-list-item-gapGap within list items
--b-list-item-paddingList item padding
--b-list-multi-select-item-paddingList item padding in a multi select list
--b-list-item-border-radiusList item border radius
--b-list-item-group-paddingPadding for group child items
--b-list-selected-icon-sizeSelection icon size (checkmark)
--b-list-selected-icon-contentSelection icon content (checkmark)
--b-list-item-group-header-font-weightGroup header font-weight
--b-list-backgroundList background
--b-list-item-backgroundList item background
--b-list-item-font-weightList item font-weight
--b-list-item-colorList item color
--b-list-title-font-weightList title (& select all) font-weight
--b-list-floating-backgroundBackground for floating lists
Focused
--b-list-item-focus-backgroundBackground for focused items
Selected
--b-list-checkbox-checked-border-colorBorder-color for checked list items
--b-list-item-selected-backgroundBackground for selected items

Inherited