Infinite list

When to use

Reach for an infinite list whenever a list is too long to load or render all at once, and scrolling for more fits the content better than numbered pages, such as a feed, a search results panel, a chat history, or a media grid.

It's deliberately unopinionated about what an item actually is: each direct child counts as one, whatever it's built from. If you instead need discrete, numbered pages someone navigates explicitly, with a URL that reflects which page they're on, see Alternatives below for a better fit.

Install & usage

Pick a framework in the toolbar above and these snippets adapt.

npm install @eunomia/elements

import "@eunomia/elements/infinite-list.js";
import "@eunomia/elements/loader.js";

<eun-infinite-list label="Team members">
  <div>Ada Lovelace</div>
  <div>Alan Turing</div>
  <div>Grace Hopper</div>
</eun-infinite-list>

npm install @eunomia/elements

<script type="module">
  import "@eunomia/elements/infinite-list.js";
  import "@eunomia/elements/loader.js";
</script>

<eun-infinite-list id="team" label="Team members" has-more>
  <div>Ada Lovelace</div>
  <div>Alan Turing</div>
  <div>Grace Hopper</div>
</eun-infinite-list>

<script type="module">
  const list = document.getElementById("team");
  list.addEventListener("eunloadmore", async (event) => {
    const page = await fetchTeamPage(event.page, event.pageSize); // your own API call
    for (const member of page.items) {
      const row = document.createElement("div");
      row.textContent = member.name;
      list.append(row);
    }
    list.loading = false;
    if (!page.hasMore) {
      list.hasMore = false;
    }
  });
</script>

npm install @eunomia/elements

import "@eunomia/elements/infinite-list.js";
import "@eunomia/elements/loader.js";
import { useCallback, useRef, useState } from "react";

function TeamList() {
  const [members, setMembers] = useState(initialPage); // however you seed page 1
  const [hasMore, setHasMore] = useState(true);
  const listRef = useRef(null);

  const onLoadMore = useCallback(async (event) => {
    const page = await fetchTeamPage(event.page, event.pageSize);
    setMembers((current) => [...current, ...page.items]);
    setHasMore(page.hasMore);
    listRef.current.loading = false;
  }, []);

  return (
    <eun-infinite-list
      ref={listRef}
      label="Team members"
      has-more={hasMore}
      oneunloadmore={onLoadMore}
    >
      {members.map((member) => (
        // A stable key matters here for the same reason it always does in
        // React — without it, re-renders may recreate DOM nodes instead of
        // reusing them, which is exactly what eun-infinite-list's own
        // virtualization otherwise avoids doing on your behalf.
        <div key={member.id}>{member.name}</div>
      ))}
    </eun-infinite-list>
  );
}

npm install @eunomia/elements

"use client";
import "@eunomia/elements/infinite-list.js";
import "@eunomia/elements/loader.js";
import { useCallback, useState } from "react";

export function TeamList({ initialMembers }) {
  const [members, setMembers] = useState(initialMembers);
  const [hasMore, setHasMore] = useState(true);

  const onLoadMore = useCallback(async (event) => {
    const page = await fetchTeamPage(event.page, event.pageSize); // Server Action or Route Handler
    setMembers((current) => [...current, ...page.items]);
    setHasMore(page.hasMore);
    event.target.loading = false;
  }, []);

  return (
    <eun-infinite-list
      label="Team members"
      has-more={hasMore}
      oneunloadmore={onLoadMore}
    >
      {members.map((member) => (
        <div key={member.id}>{member.name}</div>
      ))}
    </eun-infinite-list>
  );
}

npm install @eunomia/elements

<script setup>
  import "@eunomia/elements/infinite-list.js";
  import "@eunomia/elements/loader.js";
  import { ref } from "vue";

  const members = ref(initialMembers);
  const hasMore = ref(true);
  const list = ref(null);

  async function onLoadMore(event) {
    const page = await fetchTeamPage(event.page, event.pageSize);
    members.value.push(...page.items);
    hasMore.value = page.hasMore;
    list.value.loading = false;
  }
</script>

<template>
  <eun-infinite-list
    ref="list"
    label="Team members"
    :has-more="hasMore"
    @eunloadmore="onLoadMore"
  >
    <div v-for="member in members" :key="member.id"></div>
  </eun-infinite-list>
</template>

npm install @eunomia/elements

import { CUSTOM_ELEMENTS_SCHEMA, Component } from "@angular/core";
import "@eunomia/elements/infinite-list.js";
import "@eunomia/elements/loader.js";

@Component({
  selector: "app-team-list",
  template: `
    <eun-infinite-list
      label="Team members"
      [attr.has-more]="hasMore"
      (eunloadmore)="onLoadMore($event)"
    >
      <div *ngFor="let member of members; trackBy: trackById">
        
      </div>
    </eun-infinite-list>
  `,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class TeamListComponent {
  members = this.initialMembers;
  hasMore = true;

  async onLoadMore(
    event: CustomEvent & {
      page: number;
      pageSize: number;
      target: HTMLElement & { loading: boolean };
    },
  ) {
    const page = await this.fetchTeamPage(event.page, event.pageSize);
    this.members = [...this.members, ...page.items];
    this.hasMore = page.hasMore;
    event.target.loading = false;
  }

  trackById(_: number, member: { id: string }) {
    return member.id;
  }
}

Static vs. API-paginated

Both patterns slot items the exact same way: the only difference is how many you hand over upfront, and what you do in response to eunloadmore.

has-more is a plain HTML boolean attribute, so it can only be present (true) or absent (false), never set to the literal string "false" to mean false, the same as disabled or checked anywhere else in HTML. That's why false is the default here rather than true: it's the only one of the two that a static page can express with zero JavaScript at all.

Sorting & filtering

Whenever sort or filter criteria change, apply them to your whole dataset: every item, whether it's currently mounted, virtualized-out, or not yet fetched at all, then replace the list's content with the new result, starting from page one again. Never re-sort/re-filter only what's currently slotted, since that's an arbitrary subset (whatever's been scrolled through and fetched so far), and silently dropping virtualized-out or not-yet-loaded items from the result would be wrong regardless of how the list happens to be displaying itself at that moment.

You don't need to call anything to signal this: replacing the list's children (list.replaceChildren(...newSortedItems), or your framework's own re-render) is detected automatically: a full replacement scrolls back to the top and renumbers items from 1, while appending strictly more items past what was already there (the infinite-scroll growth case) preserves scroll position instead. Set hasMore to whatever's correct for the new result set either way (e.g. back to true if the new filtered query has its own further pages).

Performance, per framework

The core techniques (scroll-triggered fetch, DOM virtualization once the list is long) are framework-agnostic (see the Accessibility tab for exactly how virtualization works). A few extra, framework-specific habits matter too, and are easy to get backwards:

const fragment = document.createDocumentFragment();
for (const member of page.items) {
  const row = document.createElement("div");
  row.textContent = member.name;
  fragment.append(row);
}
list.append(fragment);

Alternatives

Guidance

Live testing

Properties

Static, virtualized

100 pre-rendered "wide" cards, all slotted upfront: no has-more needed, false is already the default. virtualizeThreshold is lowered to 20 here purely so the effect is visible within a small demo, since the default (100) is fine for real use and is only lowered here to keep the demo itself small.

The counter above the list is not part of the component: it's this demo's own MutationObserver, wired below, counting how many of the 100 cards are actually real DOM elements right now. Scroll and watch it move: it never grows much past the ~60 needed to cover the visible area plus buffer, no matter how far you scroll into the 100.

<eun-infinite-list label="Team members" style="--infinite-list-height: 320px;">
  <!-- all 100 cards, rendered upfront -->
</eun-infinite-list>

API-paginated

Only the first page is slotted, and the bare has-more attribute opts into fetching more (false, the default, would never trigger eunloadmore at all). Scrolling to the bottom shows the loader and fires eunloadmore, and this demo answers it with a simulated ~700ms "request" that appends 10 more items, five times, then sets hasMore to false. page-size="10" keeps every page (the pre-seeded one included) the same size, so event.pageSize matches what was actually seeded.

<eun-infinite-list
  id="results"
  label="Search results"
  has-more
></eun-infinite-list>

const list = document.getElementById("results");

list.addEventListener("eunloadmore", async (event) => {
  const response = await fetch(
    `/api/results?page=${event.page}&pageSize=${event.pageSize}`,
  );
  const { items, hasMore } = await response.json();
  list.append(...items.map(renderResult)); // your own item rendering
  list.loading = false;
  list.hasMore = hasMore;
});

Empty and end states

The empty slot shows while there are zero items and loading is false, while the end slot shows once hasMore is false and at least one item has been shown. Both are empty by default: render nothing until you provide content.

<eun-infinite-list label="Search results">
  <div slot="empty">No results yet.</div>
  <div slot="end">You've reached the end.</div>
  <!-- items -->
</eun-infinite-list>

Custom appearance

Every visual knob is a CSS custom property set directly on the element (no ::part/shadow-piercing selector needed), and the full list is in the API tab. This example tightens the three spacing-related ones for a dense list, and compares it against the default spacing (--infinite-list-gap: 16px, no padding of its own) used everywhere else on this page:

• --infinite-list-height: a shorter fixed height than the 320px used in the other examples, so this one scrolls internally sooner
• --infinite-list-gap: 4px instead of the 16px default, so items pack tightly instead of reading as separated cards
• --infinite-list-padding: 8px of breathing room around the scrollable area itself, inside the rounded corners below

The rows below have their own border only so the tighter gap is visible in this screenshot-sized demo, though that border is regular content styling, not something this component controls.

<eun-infinite-list
  label="Compact list"
  style="--infinite-list-height: 200px; --infinite-list-gap: 4px; --infinite-list-padding: 8px;"
>
  <div>Row 1</div>
  <div>Row 2</div>
  <!-- ... -->
</eun-infinite-list>

Reordering items

eun-infinite-list has no reordering of its own, but its items are plain slotted children: direct children of the same element, exactly what createDragReorder (the framework-agnostic drag-and-drop utility) needs. Grab a row by its handle (the grip icon) and drag it up or down, or focus the handle and press Space, then the arrow keys, then Space again.

<eun-infinite-list label="Reading list">
  <div class="row">
    <button class="drag-handle" aria-label="Reorder Atomic Habits">
      <eun-icon name="drag_indicator"></eun-icon>
    </button>
    <span>Atomic Habits</span>
  </div>
  <!-- ...more rows... -->
</eun-infinite-list>

import { createDragReorder } from "@eunomia/elements";

const list = document.querySelector("eun-infinite-list");
list.virtualize = false;

createDragReorder(list, {
  items: () => Array.from(list.children),
  handle: ".drag-handle",
  onReorder: ({ order }) => {
    readingList = order.map((row) => row.dataset.id);
  },
});

The Feed pattern

An infinite, auto-loading list has no native HTML equivalent, so the wrapper carries role="feed", the ARIA pattern purpose-built for exactly this: indefinitely-long content that loads more of itself as the user reaches its end. Each item automatically gets role="article" (unless it already sets its own role, its choice is always respected), plus aria-posinset/aria-setsize reflecting its position and the total count, or -1 for the total while hasMore is true (the real total genuinely isn't known yet).

aria-busy="true" is set on the feed itself while loading is set, and a visually-hidden, polite live region announces how many new items were just added right after they're appended, independently of loading, so it still fires even if a consumer forgets to flip it back to false promptly.

Keyboard interactions

Each article is reachable individually via a roving tabindex: only one (initially the first) is a Tab stop at any time, and reaching it and pressing Tab again moves on to whatever's next in the page, or into the article's own interactive content, exactly like Tab behaves anywhere else.

The arrow keys are the primary, discoverable way to move between items, while Page Down/Page Up do the exact same thing and are kept working alongside them since they're the literal keys the APG Feed pattern specifies. Plain Home/End (jump to the first/last known item) aren't part of that pattern itself, but match the behavior most people already expect from Home/End in any other list-like widget, while Ctrl+Home/ Ctrl+End remain the way to leave the list entirely.

Ctrl+Home/Ctrl+End exist specifically so a keyboard user never has to press Page Down hundreds of times to get past a very long feed: they jump straight out of it in either direction.

Virtualization and assistive technology

Once virtualize kicks in (past virtualizeThreshold items), pages far from the current scroll position are genuinely removed from the DOM, not merely hidden: the same nodes are cached and reattached as-is (state, listeners and all) once scrolled back near, rather than recreated. This keeps the live accessibility tree small on a very long feed, which is generally a good thing, but it does mean an in-page "Find" (Ctrl+F) or a screen reader's own text search can't reach content that's currently virtualized-out, since it isn't in the DOM at all at that moment.

If some content genuinely needs to stay reachable that way regardless of scroll position, raise bufferPages (keeps more mounted around the visible area) or set virtualize to false entirely for that list, trading the DOM-size benefit back for full reachability.

virtualize assumes a single-column, block/flex-column layout for items: a virtualized-out page collapses down to a single sized spacer, which preserves total scroll height correctly for a simple vertical stack but not for a CSS grid/multi-column arrangement, where collapsing several items into one spacer would also collapse the grid's own row/column count. Set virtualize to false for a grid-based layout.

Reference links

WAI-ARIA APG: Feed Pattern
WAI-ARIA 1.2: feed role
WAI-ARIA 1.2: article role