Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 37 ยท Components and Theming

Ionic Lists, Items and Sliding Actions

Build lists with ion-list and ion-item, add avatars, labels, dividers, swipe actions and drag-to-reorder, and render long lists from data efficiently.

Lists are the backbone of mobile apps: inboxes, settings, contacts, products. Ionic's list components give you rows with the correct touch behaviour, dividers, swipe actions and reordering. This lesson builds from a static list to a data-driven one, then adds sliding actions and reordering, and explains what to do with very long lists.

The basics

HTML
<ion-list>
  <ion-item>
    <ion-label>Pizza</ion-label>
  </ion-item>
  <ion-item button detail="true">
    <ion-label>Settings</ion-label>
  </ion-item>
  <ion-item href="/about">
    <ion-label>About</ion-label>
  </ion-item>
</ion-list>

ion-item is a row. It becomes tappable with button or href, shows a right chevron with detail, and has a ripple on Android. Inside it you normally put an ion-label. Three list styles exist through the lines and inset properties:

  • lines="full", "inset" or "none" control dividers between rows.
  • inset on ion-list gives rounded, margin-surrounded sections (the iOS grouped look).
  • ion-list-header adds a section heading.

Slots inside an item

HTML
<ion-item>
  <ion-avatar slot="start">
    <img alt="Ada" src="/assets/ada.png" />
  </ion-avatar>
  <ion-label>
    <h2>Ada Lovelace</h2>
    <h3>Analytical Engine</h3>
    <p>Sent a new note about Bernoulli numbers.</p>
  </ion-label>
  <ion-note slot="end">9:41</ion-note>
</ion-item>

h2, h3 and p inside a label are styled automatically as title, subtitle and body. ion-note shows secondary text such as a time stamp. Thumbnails use ion-thumbnail, and checkboxes and toggles can sit at either end.

Rendering lists from data

You never write rows by hand for real data. Each flavour loops over an array:

HTML
<!-- Angular -->
<ion-list>
  <ion-item *ngFor="let c of contacts; trackBy: trackById">
    <ion-label>{{ c.name }}</ion-label>
  </ion-item>
</ion-list>
JSX
{/* React */}
<IonList>
  {contacts.map((c) => (
    <IonItem key={c.id}><IonLabel>{c.name}</IonLabel></IonItem>
  ))}
</IonList>
HTML
<!-- Vue -->
<ion-list>
  <ion-item v-for="c in contacts" :key="c.id"><ion-label>{{ c.name }}</ion-label></ion-item>
</ion-list>

The key or trackBy must be a stable unique id, not the array index. A stable key lets the framework reuse DOM rows when data changes instead of rebuilding them, which matters for animations and scroll position.

Stand-in: grouping data into sections

A common list task is grouping rows under headers, like contacts by first letter. The logic is plain JavaScript you will reuse in any framework. This block runs.

JS Group a list into alphabetical sections

Press Run (or Ctrl + Enter) to see the console output here.

No output.

In Ionic each group becomes an ion-item-group with an ion-item-divider header, which is sticky while its group scrolls.

Sliding items

Swiping an item left or right reveals actions:

HTML
<ion-list>
  <ion-item-sliding #slider>
    <ion-item>
      <ion-label>Buy milk</ion-label>
    </ion-item>
    <ion-item-options side="end">
      <ion-item-option color="warning">Snooze</ion-item-option>
      <ion-item-option color="danger" expandable (click)="remove()">Delete</ion-item-option>
    </ion-item-options>
    <ion-item-options side="start">
      <ion-item-option color="success">Done</ion-item-option>
    </ion-item-options>
  </ion-item-sliding>
</ion-list>

expandable lets a long swipe trigger the option. Close the item programmatically with slider.close() after the action. Swipe actions are hidden gestures, so always offer the same actions another way too (a detail page, a context button) for accessibility and for desktop users.

Reordering

HTML
<ion-list>
  <ion-reorder-group [disabled]="false" (ionItemReorder)="onReorder($event)">
    <ion-item *ngFor="let t of tasks">
      <ion-label>{{ t }}</ion-label>
      <ion-reorder slot="end"></ion-reorder>
    </ion-item>
  </ion-reorder-group>
</ion-list>

The event reports from and to indexes. You must update your data and then call event.detail.complete() (or pass the updated array to it) so the visual order matches. Here is the data side as a runnable stand-in:

JS Stand-in: apply a reorder event to an array

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Long lists

A few hundred simple rows are fine. For thousands, rendering every row slows the app and uses memory. Options:

  • Pagination or infinite scroll: load pages as the user scrolls (see infinite scroll).
  • Virtual scrolling: render only visible rows. Angular has the CDK virtual scroll, React and Vue have libraries such as react-window and vue-virtual-scroller. Ionic removed its own ion-virtual-scroll because these tools do it better.
  • Keep rows light: avoid heavy images and deep trees in each item.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What should the key (or trackBy) of a list row be?

    Stable ids let the framework reuse and animate rows correctly when data changes.
  2. 2. Which component reveals swipe actions?

    ion-item-sliding wraps an item and ion-item-options holds the revealed buttons.
  3. 3. What must you do after an ionItemReorder event?

    Ionic only reports from and to; your code reorders the data and completes the event.
  4. 4. Why offer swipe actions in another way too?

    Accessibility and desktop users need visible alternatives.

Summary

  • ion-list holds ion-item rows; button, href and detail make rows tappable.
  • Use slots for avatars, notes and trailing controls.
  • Always key rows by a stable id.
  • Sliding options and reorder groups add gestures; keep alternatives visible.
  • For very long lists use pagination, infinite scroll or virtual scrolling.

Next: Modals, Alerts, Toasts and Popovers