ons-list-item

実例

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 some elements for creating lists:

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

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 and titles

To group items together you can use the <ons-list-header> element to create a header with text content. The whole list can be preceded by a <ons-list-title> element.

<ons-list-title>People I know</ons-list-title>
<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-header>My enemies</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>

The child elements can also be label or even ons-if.

Apart from this, some extra classes are provided to style different parts of the list items:

  • list-item__title: Title inside the central part. Modifies font and position.
  • list-item__subtitle: Subtitle inside the central part. Modifies font and position.
  • list-item__icon: List item icon. Modifies size and alignment.
  • list-item__thumbnail: List item thumbnail. Modifies size, borders and alignment.
<ons-list-item>
  <div class="left">
    <img class="list-item__thumbnail" src="https://placekitten.com/g/40/40">
  </div>
  <div class="center">
    <span class="list-item__title">Cutest kitty</span>
    <span class="list-item__subtitle">On the Internet</span>
  </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.

In order to prevent tappable effect when tapping on specific child elements like custom buttons, prevent-tap attribute can be added to any of the children. ons-* elements like ons-button or ons-checkbox are ignored by default.

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.

For example, 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>

Compilation

ons-list-item adds extra classes to avoid CSS collisions. The final results is as follows:

<ons-list-item class="list-item">
  <div class="top list-item__top">
    <div class="left list-item__left">Left content</div>
    <div class="center list-item__center">Center content</div>
    <div class="right list-item__right">Right content</div>
  </div>
  <div class="expandable-content list-item__expandable-content">Expandable content</div>
</ons-list-item>

If none of those sections is provided, ons-list-item will wrap all its content inside div.list-item__center.

関連情報

名前 型 / デフォルト値 概要
modifier String 各要素の表現を指定します。 Optional.
lock-on-drag Boolean この属性があると、ユーザーがこの要素を横方向にドラッグしている時に、縦方向のスクロールが起きないようになります。 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 この属性があると、"touchmove", "touchcancel", "touchend", "touchleave", "mouseup", and "mouseout" イベント時に背景色がクリアされないようになります。 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.
名前 概要
lockOnDrag この属性があると、ユーザーがこの要素を横方向にドラッグしている時に、縦方向のスクロールが起きないようになります。
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 この属性があると、"touchmove", "touchcancel", "touchend", "touchleave", "mouseup", and "mouseout" イベント時に背景色がクリアされないようになります。
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 概要
tappable タップやクリックした時に効果が表示されるようになります。
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. (翻訳中)
シグネチャ 概要
showExpansion() Show the expandable content if the element is expandable. (翻訳中)
hideExpansion() Hide the expandable content if the element expandable. (翻訳中)
clearTapBackgroundColor() タップやクリックした時に効果が表示されるようになります。このメソッドは keep-tap-background-colortrue のときに使用します。
showExpansion()

Show the expandable content if the element is expandable. (翻訳中)

hideExpansion()

Hide the expandable content if the element expandable. (翻訳中)

clearTapBackgroundColor()

タップやクリックした時に効果が表示されるようになります。このメソッドは keep-tap-background-colortrue のときに使用します。

名前 概要
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. (翻訳中)

パラメーター
名前 概要

お困りですか?

Onsen UIに関する質問は、Stack Overflowにてonsen-uiタグを付与してください。Onsen UIチームはあなたの問題解決をお手伝いします。

バグ報告や機能要望については、GitHub Issuesに記載をお願いいたします。

あわせて、下記の情報も参考にしてください。