ons-list-item

Component that represents each item in a list. The list item is composed of four parts that are represented with the left, center, right and expandable-content classes. These classes can be used to ensure that the content of the list items is properly aligned.

  <ons-list-item>
    <div class="left">Left</div>
    <div class="center">Center</div>
    <div class="right">Right</div>
    <div class="expandable-content">Expandable content</div>
  </ons-list-item>

There are also a number of classes (prefixed with list-item__*) that help when putting things like icons and thumbnails into the list items.

Tutorial

Lists

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:

  • <ons-list>
  • <ons-list-item>
  • <ons-list-header>

Markup

The <ons-list> is used as the parent and for every item one <ons-list-item> element is used:

<ons-list>
  <ons-list-item>Item A</ons-list-item>
  <ons-list-item>Item B</ons-list-item>
  <ons-list-item>Item C</ons-list-item>
</ons-list>

This will render as a list with three items.

Headers

To group items together you can use the <ons-list-header> element to create a header with text content.

<ons-list>
  <ons-list-header>My friends</ons-list-header>
  <ons-list-item>Alice</ons-list-item>
  <ons-list-item>Bob</ons-list-item>
  <ons-list-item>Eve</ons-list-item>
</ons-list>

You can use as many headers as you want in the same list.

List item structure

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 four sections.

This can be used to add icons, thumbnails or even form elements to your list items:

<ons-list-item>
  <div class="left">
    <ons-icon icon="md-face" class="list-item__icon"></ons-icon>
  </div>
  <div class="center">
    Icon and switch
  </div>
  <div class="right">
    <ons-switch></ons-switch>
  </div>
  <div class="expandable-content">
    Expandable content
  </div>
</ons-list-item>

Expandable list items

You can create list items that expand to reveal extra content when tapped by setting the expandable attribute. The content that is shown when the list item is expanded is defined in div.expandable-content.

<ons-list-item expandable>
  Tap to expand
  <div class="expandable-content">This is shown when expanded</div>
</ons-list-item>

If div.right is not defined, a dropdown arrow is automatically added to the right side of the expandable list item.

The list item can also be expanded and contracted with the showExpansion and hideExpansion methods.

The tappable attribute

The 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.

<ons-list-item tappable>Tap me!</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.

Modifiers

There are 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.

Inset lists

To create an inset list you can use the inset modifier on the <ons-list> element:

<ons-list modifier="inset">
  ...
</ons-list>

Changing the divider

The longdivider and 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:

<ons-list>
  <ons-list-item modifier="nodivider">Item A</ons-list-item>
  <ons-list-item modifier="nodivider">Item B</ons-list-item>
</ons-list>

See also

Name Type Description
modifier String The appearance of the list item. Optional.
lock-on-drag Boolean Prevent vertical scrolling when the user drags horizontally. Optional.
tappable Boolean Makes the element react to taps. prevent-tap attribute can be added to child elements like buttons or inputs to prevent this effect. ons-* elements are ignored by default. 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.
keep-tap-background-color Boolean Prevent from clearing the background color on "touchmove", "touchcancel", "touchend", "touchleave", "mouseup", and "mouseout". For this to work, the attribute “tappable” needs to be set. Optional.
expandable Boolean Makes the element able to be expanded to reveal extra content. For this to work, the expandable content must be defined in div.expandable-content. Optional.
expanded Boolean For expandable list items, specifies whether the expandable content is expanded or not. Optional.
animation String
default
The animation used when showing and hiding the expandable content. Can be either "default" or "none". Optional.
Name Description
lockOnDrag Prevent vertical scrolling when the user drags horizontally.
tappable Makes the element react to taps. prevent-tap attribute can be added to child elements like buttons or inputs to prevent this effect. ons-* elements are ignored by default.
tapBackgroundColor 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.
keepTapBackgroundColor Prevent from clearing the background color on "touchmove", "touchcancel", "touchend", "touchleave", "mouseup", and "mouseout". For this to work, the attribute “tappable” needs to be set.
expandable Makes the element able to be expanded to reveal extra content. For this to work, the expandable content must be defined in div.expandable-content.
expanded For expandable list items, specifies whether the expandable content is expanded or not.
animation The animation used when showing and hiding the expandable content. Can be either "default" or "none".
Name Description
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.
Signature Description
showExpansion() Show the expandable content if the element is expandable.
hideExpansion() Hide the expandable content if the element expandable.
clearTapBackgroundColor() Clear backgroundColor changed on tap or click. This method is helpful when keep-tap-background-color is true.
showExpansion()

Show the expandable content if the element is expandable.

hideExpansion()

Hide the expandable content if the element expandable.

clearTapBackgroundColor()

Clear backgroundColor changed on tap or click. This method is helpful when keep-tap-background-color is true.

Some Onsen UI components have overlapping event names. For example, ons-carousel and ons-navigator both emit postchange events. Stop overlapping events from propagating to avoid conflicts: document.querySelector('ons-carousel').on('postchange', e => e.stopPropagation()).

Name Description
expand For expandable list items, fires when the list item is expanded or contracted.
expand

For expandable list items, fires when the list item is expanded or contracted.

Parameters
Name Type Description

Need Help?

If you have any questions, use our Community Forum or talk to us on Discord chat. The Onsen UI team and your peers in the community will work together to help solve your issues.

For bug reports and feature requests use our GitHub Issues page.