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:
//<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:
//<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' }
]
})
});
//<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
| 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
Configs
93Common
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
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.
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.
| Parameter | Type | Description |
|---|---|---|
record | Model | The record |
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.
| Parameter | Type | Description |
|---|---|---|
record | Model | The record |
Template function which is passed a group record and the uppercased group field name. The text returned will be rendered as the group header.
| Parameter | Type | Description |
|---|---|---|
record | Model | The record |
groupName | String | The current group name |
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.
true if the record is selectable
An array of Objects which are converted into records and used to create this List's store
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
| Parameter | Type | Description |
|---|---|---|
record | Model | The record |
Configure as true to allow multi select and add checkboxes to the items
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.
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
Template function to provide a tooltip (textual, will be automatically HTML-encoded) shown when hovering an item.
| Parameter | Type | Description |
|---|---|---|
record | Model | The record representing the item |
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.
falseornull- 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).
DOM
Float & align
Layout
Misc
Scrolling
Properties
77
Properties
77Class hierarchy
Other
Configure as true to allow selecting groups (all the group child records will be toggled). Only
applicable when the store is grouped.
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
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
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
CSS
DOM
Layout
Misc
Functions
65
Functions
65Other
Returns the DOM element representing the passed record (or record id)
The item element
Searches up from the specified element for a list item and returns the associated record.
| Parameter | Type | Description |
|---|---|---|
element | HTMLElement | Element somewhere within a list item element |
Record for the item
Toggles the collapsed state of a group header or tree parent node record
| Parameter | Type | Description |
|---|---|---|
record | Model | The group header or parent record |
collapse | Boolean | Force collapse (true) or expand (false) |
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).
| Parameter | Type | Description |
|---|---|---|
toDeselect | String | 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).
| Parameter | Type | Description |
|---|---|---|
toSelect | String | String[] | Number | Number[] | Object | Object[] | |
clearSelected | Boolean | Pass |
Selects all items in this list.
Configuration
Events
Misc
Widget hierarchy
Events
19
Events
19User 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 }) => {
});| Parameter | Type | Description |
|---|---|---|
source | List | The List instance |
item | HTMLElement | The clicked list element |
record | Model | Activated record |
index | Number | List item index |
event | Event | 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 }) => {
});| Parameter | Type | Description |
|---|---|---|
source | List | The List instance |
item | HTMLElement | The clicked list element |
record | Model | Activated record |
index | Number | List item index |
event | Event | Triggering event |
Fired when selection changes
// Adding a listener using the "on" method
list.on('selectionChange', ({ source, selected }) => {
});| Parameter | Type | Description |
|---|---|---|
source | List | The List instance |
selected | Model[] | An array of the currently selected records |
Group item expanded or collapsed
// Adding a listener using the "on" method
list.on('toggleGroup', ({ groupRecord, collapse }) => {
});| Parameter | Type | Description |
|---|---|---|
groupRecord | Model | Group record |
collapse | Boolean | Collapsed (true) or expanded (false) |
Tree parent node expanded or collapsed
// Adding a listener using the "on" method
list.on('toggleNode', ({ record, collapse }) => {
});| Parameter | Type | Description |
|---|---|---|
record | Model | The parent record which has been toggled |
collapse | Boolean | Collapsed (true) or expanded (false) |
Event handlers
19
Event handlers
19User 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 }) {
}
});| Parameter | Type | Description |
|---|---|---|
source | List | The List instance |
item | HTMLElement | The clicked list element |
record | Model | Activated record |
index | Number | List item index |
event | Event | 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 }) {
}
});| Parameter | Type | Description |
|---|---|---|
source | List | The List instance |
item | HTMLElement | The clicked list element |
record | Model | Activated record |
index | Number | List item index |
event | Event | Triggering event |
Called when selection changes
new List({
onSelectionChange({ source, selected }) {
}
});| Parameter | Type | Description |
|---|---|---|
source | List | The List instance |
selected | Model[] | An array of the currently selected records |
Group item expanded or collapsed
new List({
onToggleGroup({ groupRecord, collapse }) {
}
});| Parameter | Type | Description |
|---|---|---|
groupRecord | Model | Group record |
collapse | Boolean | Collapsed (true) or expanded (false) |
Tree parent node expanded or collapsed
new List({
onToggleNode({ record, collapse }) {
}
});| Parameter | Type | Description |
|---|---|---|
record | Model | The parent record which has been toggled |
collapse | Boolean | Collapsed (true) or expanded (false) |
Typedefs
6
Typedefs
6CSS variables
38
CSS variables
38| Name | Description |
|---|---|
--b-list-multi-select-gap | Gap between list items in a multi select list |
--b-list-item-gap | Gap within list items |
--b-list-item-padding | List item padding |
--b-list-multi-select-item-padding | List item padding in a multi select list |
--b-list-item-border-radius | List item border radius |
--b-list-item-group-padding | Padding for group child items |
--b-list-selected-icon-size | Selection icon size (checkmark) |
--b-list-selected-icon-content | Selection icon content (checkmark) |
--b-list-item-group-header-font-weight | Group header font-weight |
--b-list-background | List background |
--b-list-item-background | List item background |
--b-list-item-font-weight | List item font-weight |
--b-list-item-color | List item color |
--b-list-title-font-weight | List title (& select all) font-weight |
--b-list-floating-background | Background for floating lists |
| Focused | |
--b-list-item-focus-background | Background for focused items |
| Selected | |
--b-list-checkbox-checked-border-color | Border-color for checked list items |
--b-list-item-selected-background | Background for selected items |