Native list

a select element with "multiple" attribute

Value:

Bind to simple arrays

Pass a simple array (number[], string[] or boolean[]) as source. By default the toString() method of the item is used to display the item.
In most cases you want to use a formatter to display a specific text for the item.

[source]="numberArray" Value: 1
[source]="stringArray" Value: "Three"
[source]="[true, false]" Value:
Note: The Array passed as "source" is converted to a LocalDataSource internally.

Bind to boolean values

Set [source]="[true, false]" to display boolean values.
Using formatters you can display different text for true/false values. The formatters are defined in the locale files. Locale formatter names starts with "@".

[source]="[true, false]" Value:
[source]="[true, false]"; formatBy="*OnOffBoolean" Value:
[source]="[true, false]"; formatBy="*CorrectIncorrectBoolean" Value:
[source]="[true, false]"; formatBy="*EnableDisableBoolean" Value:

Bind to Enums

Pass an Enum as source and use a formatter to display the enum titles.

[source]="Sexuality" Value:
[source]="Sexuality"; formatBy="*SexualityEnum" Value:
Note: The enum object passed as "source" is converted to a LocalDataSource internally.

Bind to objects

Pass an array of objects as source.
By default the toString() method of the object is used to display the item. In most cases you want to use a formatter to display a specific field of the object.

[source]="objectsSource1" (without formatter) Value:

Format Items:

Format source items by a specific field, a locale formatter or by a custom function.

You have 3 ways to format items:
  • Using object fields: formatBy="fieldName "
  • Using a locale formatter: formatBy="*formatterName "
  • Using a formatBy function: [formatBy]="functionName"
[source]="objectsSource1"; formatBy="name" Value:
[source]="objectsSource1"; formatBy="*personFormatter1" Value:
[source]="objectsSource1"; [formatBy]="formatterFunction" Value:

Compare items:

Compare source items with the selected value(s) by a specific field or by a custom function.
This is useful when the source items are objects and the selected value(s) are not the same object instances.

[source]="objectsSource1"; compareBy="id"; formatBy="name" Value: { "id": 2 }
[source]="objectsSource1"; [compareBy]="compareFunction"; formatBy="name" Value: { "id": 3 }

Custom value writer:

Write back the selected value(s) by a specific field or by a custom function.
This is useful when you want to bind the component to a specific property of an object instead of the whole object.

[source]="objectsSource1"; writeBy="id"; compareBy="id"; formatBy="name"

Value: { "id": 2 }

[source]="objectsSource1"; [writeBy]="customValueWriter1"; compareBy="id"; formatBy="name"

Value: { "id": 3 }
Bind to a DB ForeignKey: [writeBy]="id"; formatBy="name" Value: 2
Note: Using a value writer is useful when binding to database foreign keys.

Single selection

By default, the list allows single selection.

Without selection indicator

Value:

With selection indicator

Value:

Multi selection

By setting multiple="true" you can select multiple items.
Setting [showSelectionIndicator]="true" will display a checkbox in front of each item.

multiple="true" Value: []
multiple="true"; [showSelectionIndicator]="true" Value: [One]

Custom item template

Use an ng-template to define a custom item template. The let-option variable is an object with the following properties:

  • ref: a reference to the ListItemComponent
  • value: the item value
[source]="objectsSource1"; writeBy="id" Value:

Filter

Filter the items by a custom filter function.
The filter function receives the item and must return true if the item should be displayed.

[source]="stringArray"; [filterBy]="list17FilterFunction" Value:

Manipulating Data

Bind to a simple array and manipulate the data by adding/removing items or replacing the data source.

Source: number[] Value: []

Bind to RemoteDataSource

A RemoteDataSource is a data source that retrieves data from a remote server.

Source: RemoteDataSource Value: 2

Accessibility

Ensure that the list is accessible to all users, including those using assistive technologies.

Focus:
By setting the focusMode property, you can control how the list is navigated using the keyboard. focusMode property can be set to "none", "roving" or "activeDescendant".
  • focus="none": The list will not manage focus for its items.
  • focusMode="activeDescendant": The list will manage focus for its items using the aria-activedescendant attribute. This is default.
  • focusMode="roving": The list will manage focus for its items using a roving tabindex.
focusMode="none" Value:
focusMode="activeDescendant" Value:
focusMode="roving" Value:

Disabled state

Disable the list by setting the disabled property to true.

Source: number[]
  • Value:
  • Touched: false
  • Dirty: false

Events

Handle (valueChange) event to react on value changes. Select an item and See the browser console log.

Source: number[]

Unstyled list

Remove all styles from the list by adding "ng1-list-unstyled" class. List component allways adds "active" and "selected" CSS classes to the list items when appropriate. You can apply custom styles to the list items by targeting these classes.

Source: number[]

Value:

On this page: