List Index

List Index allows to access a particular section of the list view instantly without scrolling through each section.

List Index Layout

Single List Index layout is pretty simple:

<div class="page">
  <div class="navbar">...</div>
  <!-- List Index element, must be a direct child of page -->
  <div class="list-index"></div>
  <!-- Scrollable page content -->
  <div class="page-content">...</div>
</div>

List Index App Methods

Let’s look at related App methods to work with List Index:

app.listIndex.create(parameters)- create List Index instance

• parameters - object. Object with list index parameters

Method returns created List Index’s instance

app.listIndex.destroy(el)- destroy List Index instance

• el - HTMLElement or string (with CSS Selector) or object. List Index element or List Index instance to destroy.

app.listIndex.get(el)- get List Index instance by HTML element

• el - HTMLElement or string (with CSS Selector). List Index element.

Method returns List Index’s instance

List Index Parameters

Now let’s look at list of available parameters we need to create List Index:

var listIndex = app.listIndex.create({
  el: ‘.list-index’,
  on: {
    select: function () {
      console.log(‘Index selected’)
    },
  },
})

List Index Methods & Properties

So to create List Index we have to call:

var listIndex = app.listIndex.create({ /* parameters */ })

After that we have its initialized instance (like listIndex variable in example above) with useful methods and properties:

List Index Events

List Index will fire the following DOM events on list index element and events on app and list index instance:

DOM Events

App and List Index Instance Events

List Index instance emits events on both self instance and app instance. App instance events has same names prefixed with listIndex.

List Index Auto Initialization

If you don’t need to use List Index API and your List Index is inside of the page and presented in DOM on moment of page initialization then it can be auto initialized with just adding additional list-index-init class:

<!-- Add list-index-init class -->
<div class="list-index list-index-init"></div>

In this case if you need to access created List Index instance you can use the app.listIndex.get app method:

var listIndex = app.listIndex.get('.list-index');
var indexes = listIndex.indexes;
// do something with indexes

When using auto init you may need to pass additional parameters. you can set all available parameters via data- attributes on list index element:

<div class="page">
  ...
  <!-- parameters set via data- attributes -->
  <div class="list-index"
    data-list-el=".contacts-list"
    data-label="true"
    data-indexes="auto"
  ></div>
  <div class="page-content">
    <div class="list contacts-list">
      ...
    </div>
  </div>
</div>

CSS Variables

Below is the list of related CSS variables (CSS custom properties).

Note that commented variables are not specified by default and their values is what they fallback to in this case.

:root {
  --f7-list-index-width: 16px;
  --f7-list-index-font-size: 11px;
  --f7-list-index-font-weight: 600;
  /* --f7-list-index-text-color: var(--f7-theme-color); */
  --f7-list-index-item-height: 14px;
  --f7-list-index-label-text-color: #fff;
  /* --f7-list-index-label-bg-color: var(--f7-theme-color); */
  --f7-list-index-label-font-weight: 500;
}
.ios {
  --f7-list-index-label-size: 44px;
  --f7-list-index-label-font-size: 17px;
  --f7-list-index-skip-dot-size: 6px;
}
.md {
  --f7-list-index-label-size: 56px;
  --f7-list-index-label-font-size: 20px;
  --f7-list-index-skip-dot-size: 4px;
}
.aurora {
  --f7-list-index-font-size: 12px;
  --f7-list-index-label-size: 32px;
  --f7-list-index-label-font-size: 12px;
  --f7-list-index-label-font-weight: 600;
  --f7-list-index-skip-dot-size: 4px;
}

Examples

<div class="page">
  <div class="navbar">
    ...
  </div>
  <!-- List index element -->
  <div class="list-index"></div>
  <div class="page-content">
    <!-- Contacts list -->
    <div class="list simple-list contacts-list">
      <div class="list-group">
        <ul>
          <li class="list-group-title">A</li>
          <li>Aaron</li>
          <li>Adam</li>
          ...
        </ul>
      </div>
      <div class="list-group">
        <ul>
          <li class="list-group-title">B</li>
          <li>Benjamin</li>
          <li>Blake</li>
          <li>Bobby</li>
        </ul>
      </div>
      <div class="list-group">
        <ul>
          <li class="list-group-title">C</li>
          <li>Caleb</li>
          <li>Callum</li>
          ...
        </ul>
      </div>
      ...
    </div>
  </div>
</div>

var app = new Framework7();
var listIndex = app.listIndex.create({
  // ".list-index" element
  el: '.list-index',
  // List el where to look indexes and scroll for
  listEl: '.contacts-list',
  // Generate indexes automatically based on ".list-group-title" and ".item-divider"
  indexes: 'auto',
  // Scroll list on indexes click and touchmove
  scrollList: true,
  // Enable bubble label when swiping over indexes
  label: true,
});