Getting Started with ListBox Component
IntegralUI ListBox is a native Web Component that displays a list of items with customizable content. You can load data on demand during run-time from local or remote data sources, create different item templates using custom HTML elements, reorder the list using advanced drag and drop functionality etc. In following sections, you can find details about different features available in the ListBox component, with sample code in JavaScript, Angular, React and Vue.
List of Included Features
Detailed information is available here: Features in ListBox component.
How to Use IntegralUI ListBox
At first, you need to install the IntegralUI Web library on your side. Detailed information is available here: How to Use IntegralUI Web Components. It provides information on how to setup and use components for each framework: Angular, React or Vanilla JavaScript. In general, you need to open your application and add a reference to a component you want to use.
To use the IntegralUI ListBox component, you need to do the following:
- Place the ListBox using the iui-listbox tag
- Connect the ListBox to your data source
- (optional) Define the template that will be used to create the items
- (optional) Add custom HTML elements as item content
Properties, Events and Methods
A detailed list for each property, event and method is available here: ListBox API.
Data
You can populate the ListBox component with data from various sources. In general, you need to create an array of JavaScript Objects that will contain all data that you want to show in a list. Then apply this array to the items property.
Data Binding
If your data uses different field names than the ones used by the ListBox, you may need to bind your data to the ListBox, using dataFields property. Although, having custom fields in your data is fully supported, this may be required if there is overlapping with predefined ones already used by the ListBox component. The most important fields that may require data binding are:
- id - a unique identifier used to distinguish the item in the list
- group - determines the group to which item belongs
- selected - specifies whether item is selected or not
- text - represents the item label
There are many other predefined fields available, a complete list of fields in use is available in ListBox API under item object
When using templates this may not be required, because within the template you can have any custom fields set in your code.
How to Add/Remove Items
You can create the list initially in code by adding new items one by one or you can load it from a local or remote data source. In the same way, you can remove items one by one or clearing the whole list at once.
Load Data from JSON
In general, when you have custom data fields you can use item templates to create the list in the ListBox component. As a data source you can use a JSON file where items can have custom data fields.
Export to JSON
IntegralUI ListBox component comes with built-in functionality that allows you to export the list in full or partially to JSON. You can export the list completely or just a small portion of it, for example only selected items.
Grouping
When you have a long list of items, it may become hard to find a specific item. One way to solve this is to use create list groups. The ListBox component supports grouping that allows you to create groups on demand and divide items in multiple categories.
Drag and Drop
The ListBox component comes with built-in support for drag and drop operations. You can drag and drop items from one position to another within the same or to different components like: ListBox, ListView, TreeViewT or other custom HTML elements or components. During this process, several drag and drop events are fired that you can handle in your code and further enhance the drag drop functionality.
There are two ways to drag and drop items:
- Static - a drop marker appears with information about target item and an icon that shows drop position: Up or Down
- Dynamic - a window with a list of dragged items appears and while dragging all other items will move making space where item(s) can drop
Drag Drop between ListBox and other Components
You can drag and drop one or multiple items within the ListBox component, or move/copy items from ListBox to other components like ListView.
Copy Item with Drag and Drop
Drag and Drop allows you to move items during run time from one position to another in the same or between different components. In some cases, during this process instead of moving the item(s), you may need to create an item copy and place it at target location.
Drag Drop Multiple Items
When drag and drop is enabled in ListBox component, you can move items one by one within the same or to other components. With multi selection enabled you can also drag and drop multiple items at the same.
Filtering
When you have large list with thousands of items, it may be hard to find specific item that you are looking for. For this purpose, it is better if you could filter the list so that only those items that match the filter criteria are displayed.
IntegralUI ListBox component includes an option to filter the list using multiple filters with different conditions using AND/OR logic. There are many String, Boolean and Numeric operators to choose from; in addition you can also create your own custom filter operations.
Filter List by Value
By default, when filtering is active you can filter the list by item’s label using string operations. However, you can also filter list by value, which can be of any type, including objects set in custom fields as part of item object.
How to Add Multiple Filters
In ListBox you have an option to apply multiple filters with different conditions. You can search more than one field and filter the list data. You can combine multiple filters using AND / OR logic and create custom filtering formula.
Custom Filter
In most cases of filtering, only item’s text or value field is used to match the current filtering value, which only uses one condition set with one filtering operation. However, if you want to create multi field data filters, you will need to create custom filter by specifying your own callback function.
Search and Highlight Items
In many cases, when using filtering in ListBox component, the list is filtered by specified conditions, showing only items that match the filter criteria. However, there is a way to show a full list and only highlight items that match the search value.
Layout
By default, ListBox component has an internal template shared among all items that displays the item icon and label. This works in most cases, where you need to display a simple list. However, you can create your own custom item template that allows you to add any custom HTML elements and arrange them in different layouts. In addition, you can set conditions and use multiple different templates for each item separately or share them between items.
Scrolling
In ListBox only vertical scrolling is available. When the list is longer than the view size, a scrollbar will appear on the right side. You can change the scroll bar appearance to:
- Static - scroll bar is always visible when there are more items than currently present in the view
- Dynamic - scroll bar will appear only when mouse hovers over ListBox space
There are multiple ways to add new data to the ListBox, dynamically during run-time. You can add items one by one from code, oad data using load more buttonl or using infinite scrolling to load data on demand. In addition, you can scroll to selected item and show it in the current view of ListBox component.
Selection
There are four different options to select one or more items in ListBox component:
- None - selection is disabled
- One - only one item is selectable, default option
- MultiSimple - you can select multiple items using just mouse clicks or touch
- MultiExtended - you can select multiple items using mouse and CTRL or SHIFT keys
How to Select Multiple Items
There are two multi-select options in ListBox: simple and extended. In both ways, you can select multiple items using mouse clicks or touch in combination with keyboard keys. In addition, you can also select items from code.
Move Selected Items in Dual List Box
When you have multiple items selected in ListBox component, you can move them to a different position within the same list or to another list, in different ways. One example is to move selected items using two buttons: move right and move left.
Sorting
IntegralUI ListBox component comes with built-in support for sorting that allows you to sort items in ascending or descending order based on item's text or value field. Sorting is available for string, boolean and numeric values, but you can also create custom sorting methods that will sort items based on different fields or objects, like Dates or custom JavaScript Objects.
Styling
You can modify the existing CSS classes for ListBox component that govern its appearance or create your own. In general, you can change every component part in this way. In addition, you can also use dynamic styles that you can apply to each item separately during run-time from code. This allows you to set up conditions when and how item(s) will appear in the ListBox.
Items with Alternate Background Colors
One example is to create alternate background colors for even and odd items in ListBox component, using dynamic styles.
Highlight Items
IntegralUI ListBox component is fully customizable; you can modify its appearance either through CSS or using dynamic styles. In order to highlight items, you can just change the CSS class that governs the appearance of items by using selectors. However, the better way is to apply a different style for specific item based on some condition set in code.
Utility
Add CheckBox to Items
By default, ListBox items don't have an option to show a checkbox. However, you can create a custom item template, where you can add checkbox and place it on left, right side or in other position within the item space. For check boxes, you can use the IntegralUI CheckBox component or standard input or span element and set it to appear before the item label.
Add Context Menu to ListBox
Having a context menu is useful in cases when you want to extend the ListBox functionality with additional custom actions. For example, if you want to add or remove items, you can create a context menu with options that can provide that kind of functionality.
Add Tooltip to Items
By default, items in ListBox component don't have a tooltip. However, you can create a tooltip for each item that will appear whenever mouse hovers over the item space.
Conclusion
IntegralUI ListBox is a web component that displays a list of items with customizable content. You can reorder the list dynamically using advanced drag and drop operations. You can create custom item templates where you can add any standard or custom HTML elements or other Web Components, like icons, checkboxes, editors etc. In addition, the component is fully customizable; you can override default CSS classes with your own, use CSS custom properties or dynamic styles or choosing a different theme.
ListBox component is part of IntegralUI Web that you can use in Angular, React, Vue and any other JavaScript frameworks.