Expandable list items in Onsen UI 2.10

Onsen UI 2.10 has just been released, and with it comes a much-requested feature: expandable list items! Also known as expansion panels or accordions, expandable list items are much like regular items in an Onsen UI list, except that they can be expanded to reveal hidden content. They’re really easy to add into your existing Onsen UI applications, and in this article I’ll be showing you how to do just that, as well as providing an example app that uses this new feature.

Basic usage

Expandable list items in Onsen UI are actually just an extension to regular list items. You can make a regular ons-list-item into an expandable list item by setting the expandable attribute:

<ons-list>
  <ons-list-item expandable>...</ons-list-item>
</ons-list>

The regular ons-list-item is composed of three optional parts: the left part, the center part and the right part. The contents of each of these are defined in their own divs respectively:

<ons-list-item>
  <div class="left">The left part</div>
  <div class="center">The center part</div>
  <div class="right">The right part</div>
</ons-list-item>

Onsen UI 2.10 adds a fourth part for expandable list items — div.expandable-content. Inside this div goes everything that should appear when the list item is expanded.

<ons-list-item expandable>
  <div class="left">The left part</div>
  <div class="center">The center part</div>
  <div class="right">The right part</div>
  <div class="expandable-content">
    This gets shown when I'm expanded
  </div>
</ons-list-item>

div.left, div.center and div.right are all optional, but div.expandable-content has to be defined if you set the expandable attribute. If it isn’t, the list item won’t expand at all.

Normally a user of your app would expand an expandable list item by tapping on it, but if you want to do it yourself there are also the showExpansion and hideExpansion methods.

<ons-list-item id="expandable-list-item" expandable>
  ...
  <div class="expandable-content">Expanded!</div>
</ons-list-item>
<script>
  document.querySelector('#expandable-list-item').showExpansion();
</script>

Using in practice

The finished contact list

Let’s make a contact list where each item is a contact. The top-level should display the contact’s name, and the expandable content should be further contact details. We’ll start with an ordinary, non-expandable list of items.

<ons-page>
  <ons-list id="contacts">
    <ons-list-item>Ken</ons-list-item>
    <ons-list-item>Joe</ons-list-item>
    <ons-list-item>Jun</ons-list-item>
    <ons-list-item>Jinpei</ons-list-item>
    <ons-list-item>Ryu</ons-list-item>
  </ons-list>
</ons-page>

You can try all the examples in this article in CodePen.

So far, so good. Now we want to add the contact details for each contact as expandable content. First we give each list item the expandable attribute, then add the contact details in div.expandable-content.

<ons-page>
  <ons-list id="contacts">
    <ons-list-item expandable>
      Ken
      <div class="expandable-content">ken@gtchmn.co.jp</div>
    </ons-list-item>
    <ons-list-item expandable>
      Joe
      <div class="expandable-content">joe@gtchmn.co.jp</div>
    </ons-list-item>
    <ons-list-item expandable>
      Jun
      <div class="expandable-content">jun@gtchmn.co.jp</div>
    </ons-list-item>
    <ons-list-item expandable>
      Jinpei
      <div class="expandable-content">jinpei@gtchmn.co.jp</div>
    </ons-list-item>
    <ons-list-item expandable>
      Ryu
      <div class="expandable-content">ryu@gtchmn.co.jp</div>
    </ons-list-item>
  </ons-list>
</ons-page>

It would be nice if we had a way of closing all the expanded contacts at once, so let’s add a toolbar button with that functionality.

<ons-page>  
  <ons-toolbar>
    <div class="right">
      <ons-toolbar-button onclick="hideAll()">
        Hide all
      </ons-toolbar-button>
    </div>
  </ons-toolbar>
  <ons-list id="contacts">
    ...
  </ons-list>
</ons-page>
const hideAll = () => {
  Array.from(document.querySelector('#contacts').children)
    .forEach(contact => {
      if (contact.expanded) {
        contact.hideExpansion();
      }
    });
};

Now we can freely expand whatever contacts we want, and then hide them all again by tapping ‘Hide all’.

Hopefully you have seen how expandable list items work in Onsen UI and have some ideas about how you can put them to use in your own projects. Expandable list items are just one of the new features in Onsen UI 2.10. For the full list of changes, see here. Stay tuned for more Onsen UI updates.