Component that represents each item in a list. The list item is composed of three parts that are represented with the
right classes. These classes can be used to ensure that the content of the list items is properly aligned.
<v-ons-list-item> <div class="left">Left</div> <div class="center">Center</div> <div class="right">Right</div> </v-ons-list-item>
There is also a number of classes (prefixed with
list-item__*) that help when putting things like icons and thumbnails into the list items.
Creating lists in Onsen UI is very simple and they are one of the most important UI components in mobile apps.
Onsen UI provides three elements for creating lists:
<v-ons-list> is used as the parent and for every item one
<v-ons-list-item> element is used:
<v-ons-list> <v-ons-list-item>Item A</v-ons-list-item> <v-ons-list-item>Item B</v-ons-list-item> <v-ons-list-item>Item C</v-ons-list-item> </v-ons-list>
This will render as a list with three items.
To group items together you can use the
<v-ons-list-header> element to create a header with text content.
<v-ons-list> <v-ons-list-header>My friends</v-ons-list-header> <v-ons-list-item>Alice</v-ons-list-item> <v-ons-list-item>Bob</v-ons-list-item> <v-ons-list-item>Eve</v-ons-list-item> </v-ons-list>
You can use as many headers as you want in the same list.
In the previous examples the list items only contained simple text content. Onsen UI list items provide a secondary syntax where the list item is divided into three sections.
This can be used to add icons, thumbnails or even form elements to your list items:
<v-ons-list-item> <div class="left"> <v-ons-icon icon="md-face" class="list-item__icon"></v-ons-icon> </div> <div class="center"> Icon and switch </div> <div class="right"> <v-ons-switch></v-ons-switch> </div> </v-ons-list-item>
Notice that the inner structure does not need to be made with
div elements. It can be any element such as a
tappable attribute is used to give the user an indication when they tap a list item. In iOS the background color will change when tapped and on Android it will display the Material Design ripple effect.
<v-ons-list-item tappable>Tap me!</v-ons-list-item>
This is very useful in apps that perform some action or navigate to a new page when a list item is tapped.
There is a bunch of modifiers that can be used to customize the look of the lists and list items.
In Onsen UI modifiers are applied by adding the
modifier attribute to an element. More than one can be added by separating them with spaces.
To create an inset list you can use the
inset modifier on the
<v-ons-list modifier="inset"> ... </v-ons-list>
nodivider modifiers can be used to change the length or remove the divider (horizontal line) between list items completely. The default style for list items is a divider that doesn’t completely cover the whole screen. Instead it has some padding on the left to make it look more similar to native lists.
By adding the
nodivider modifier the divider can be removed:
<v-ons-list> <v-ons-list-item modifier="nodivider">Item A</v-ons-list-item> <v-ons-list-item modifier="nodivider">Item B</v-ons-list-item> </v-ons-list>
|Name||Type Default Value||Description|
|lock-on-drag||String||Prevent vertical scrolling when the user drags horizontally. Optional.|
|modifier||String||The appearance of the list item. Optional.|
|tap-background-color||Color||Changes the background color when tapped. For this to work, the attribute “tappable” needs to be set. The default color is “#d9d9d9”. It will display as a ripple effect on Android. Optional.|
Makes the component react to taps.
|tappable||Make the list item change appearance when it’s tapped. On iOS it is better to use the “tappable” and “tap-background-color” attribute for better behavior when scrolling.|
|chevron||Display a chevron at the right end of the list item and make it change appearance when tapped.|
|longdivider||Displays a long horizontal divider between items.|
|nodivider||Removes the divider between list items.|
|material||Display a Material Design list item.|
For bug reports and feature requests use our GitHub Issues page.