StackPractices
intermediate Por Mathias Paulenko

Paginación con Scroll Infinito en JavaScript

Implementa carga de datos por scroll en JavaScript con IntersectionObserver: detección por centinela, fetch, estados de carga y error, y limpieza correcta.

Visión General

El scroll infinito añade la siguiente página de resultados cuando el usuario se acerca al final de la lista, así que nadie tiene que hacer clic en “siguiente”. Esta receta lo construye sobre IntersectionObserver: un elemento centinela queda al final de la lista, y cuando entra al viewport (más un margen de rootMargin) el código pide la página siguiente y la agrega. Verás una versión básica funcional, una clase de producción con estados de carga y error más un cierre limpio, un fallback con evento scroll para navegadores antiguos, y un hook de React con los detalles sutiles bien resueltos.

Cuándo usarlo

El scroll infinito encaja en feeds donde el contenido se consume de forma lineal y el orden es estable:

  • Feeds tipo red social, galerías de imágenes, streams de actividad, hilos de comentarios
  • Layouts centrados en móvil donde el scroll ya es el gesto principal
  • Resultados de búsqueda donde los clics en “página siguiente” muestran abandono medible

No encaja en todas partes. Prefiere paginación de verdad (o un botón “cargar más”) cuando:

SituaciónMejor opciónPor qué
Los usuarios saltan a items o páginas concretasPaginación numeradaNo hay forma de enlazar la “página 7” de un stream
Hay contenido bajo la lista (footer, filtros)Botón cargar másLa lista empuja el footer para siempre
El usuario retoma donde lo dejóPaginación + restaurar scrollEl back-nav aterriza a mitad de stream sin ancla
El contenido cambia rápido (items nuevos arriba)Paginación por cursorEl offset ?page=N duplica o salta items
Audiencia que depende de lectores de pantallaBotón cargar másInsertar contenido solo desorienta

Un botón “cargar más” es el punto medio honesto: mismo impulso de UX, pero el usuario controla la inserción y la gestión de foco queda simple. Además funciona mejor con usuarios de solo teclado: el foco nunca es desplazado por contenido que aparece debajo a mitad de scroll.

Solución

1. Scroll infinito básico con IntersectionObserver

const sentinel = document.getElementById("sentinel");
const container = document.getElementById("list");
let page = 1;
let loading = false;
let hasMore = true;

async function loadPage(pageNum) {
    const res = await fetch(`/api/items?page=${pageNum}`);
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    return res.json();
}

function renderItems(items) {
    for (const item of items) {
        const div = document.createElement("div");
        div.className = "list-item";
        div.textContent = item.title;
        container.appendChild(div);
    }
}

const observer = new IntersectionObserver(async (entries) => {
    if (!entries[0].isIntersecting || loading || !hasMore) return;

    loading = true;
    page++;
    try {
        const data = await loadPage(page);
        renderItems(data.items);
        hasMore = data.hasMore;
        if (!hasMore) observer.unobserve(sentinel);
    } catch (err) {
        page--; // el fetch fallido no consume la página
        console.error("Load failed:", err);
    }
    loading = false;
});

observer.observe(sentinel);

El try/catch importa: sin él, un fetch fallido deja loading atascado en true y el scroll deja de funcionar en silencio; es la forma más común en que este código se rompe en producción.

2. Clase completa con carga, error y cierre

class InfiniteScroll {
    constructor(options) {
        this.container = options.container;
        this.sentinel = options.sentinel;
        this.fetchUrl = options.fetchUrl;
        this.renderItem = options.renderItem;
        this.pageSize = options.pageSize ?? 10;
        this.threshold = options.threshold ?? 200;

        this.page = 1;
        this.loading = false;
        this.hasMore = true;
        this.observer = null;
        this.controller = null; // fetch en vuelo
    }

    init() {
        this.loadInitial();
        this.setupObserver();
    }

    async loadInitial() {
        this.showLoading();
        try {
            const data = await this.fetchPage(1);
            this.renderItems(data.items);
            this.hasMore = data.hasMore;
        } catch (err) {
            this.showError("Failed to load initial data");
        }
        this.hideLoading();
    }

    setupObserver() {
        this.observer = new IntersectionObserver(
            (entries) => this.handleIntersection(entries),
            { rootMargin: `${this.threshold}px` }
        );
        this.observer.observe(this.sentinel);
    }

    async handleIntersection(entries) {
        if (!entries[0].isIntersecting || this.loading || !this.hasMore) return;

        this.loading = true;
        this.showLoading();
        this.controller = new AbortController();

        try {
            this.page++;
            const data = await this.fetchPage(this.page);
            this.renderItems(data.items);
            this.hasMore = data.hasMore;

            if (!this.hasMore) {
                this.observer.unobserve(this.sentinel);
                this.showEndMessage();
            }
        } catch (err) {
            if (err.name === "AbortError") return; // destroy() nos canceló
            this.page--;
            this.showError("Failed to load more items. Try scrolling again.");
        } finally {
            this.controller = null;
            this.loading = false;
            this.hideLoading();
        }
    }

    async fetchPage(pageNum) {
        const url = `${this.fetchUrl}?page=${pageNum}&limit=${this.pageSize}`;
        const res = await fetch(url, { signal: this.controller.signal });

        if (!res.ok) throw new Error(`HTTP ${res.status}`);
        return res.json();
    }

    renderItems(items) {
        const fragment = document.createDocumentFragment();
        for (const item of items) {
            fragment.appendChild(this.renderItem(item));
        }
        this.container.appendChild(fragment); // un reflow, no N
    }

    showLoading() {
        let loader = document.getElementById("scroll-loader");
        if (!loader) {
            loader = document.createElement("div");
            loader.id = "scroll-loader";
            loader.className = "scroll-loader";
            loader.setAttribute("role", "status");
            loader.textContent = "Loading more items…";
            this.container.parentElement.appendChild(loader);
        }
        loader.style.display = "block";
    }

    hideLoading() {
        const loader = document.getElementById("scroll-loader");
        if (loader) loader.style.display = "none";
    }

    showError(message) {
        let error = document.getElementById("scroll-error");
        if (!error) {
            error = document.createElement("div");
            error.id = "scroll-error";
            error.className = "scroll-error";
            error.setAttribute("role", "alert");
            this.container.parentElement.appendChild(error);
        }
        error.textContent = message;
        error.style.display = "block";
        setTimeout(() => { error.style.display = "none"; }, 3000);
    }

    showEndMessage() {
        const end = document.createElement("div");
        end.className = "scroll-end";
        end.textContent = "You're all caught up.";
        this.container.parentElement.appendChild(end);
    }

    destroy() {
        if (this.controller) this.controller.abort();
        if (this.observer) {
            this.observer.disconnect();
            this.observer = null;
        }
    }
}

// Uso
const list = document.getElementById("list");
const scroll = new InfiniteScroll({
    container: list,
    sentinel: document.getElementById("sentinel"),
    fetchUrl: "/api/posts",
    renderItem: (post) => {
        const div = document.createElement("div");
        div.className = "post-card";
        const h3 = document.createElement("h3");
        h3.textContent = post.title; // textContent, no innerHTML — sin XSS
        const p = document.createElement("p");
        p.textContent = post.excerpt;
        div.append(h3, p);
        return div;
    },
    pageSize: 20,
    threshold: 300
});

scroll.init();

// Cierre al cambiar de ruta en SPA o al salir de la página
window.addEventListener("beforeunload", () => scroll.destroy());

Tres mejoras sobre la versión ingenua que vale la pena robar: AbortController cancela un fetch en vuelo cuando la página se desmonta (nada de appends fantasma), DocumentFragment convierte N inserciones en un solo reflow, y role="status"/role="alert" hacen visibles el loader y el error para lectores de pantalla.

3. Fallback con evento scroll y debounce

Para entornos sin IntersectionObserver (WebViews muy viejos, algunos navegadores embebidos):

function debounce(fn, delay) {
    let timer;
    return (...args) => {
        clearTimeout(timer);
        timer = setTimeout(() => fn(...args), delay);
    };
}

let page = 1;
let loading = false;
let hasMore = true;

const handleScroll = debounce(async () => {
    const scrollBottom = window.scrollY + window.innerHeight;
    const docHeight = document.documentElement.scrollHeight;

    if (scrollBottom < docHeight - 300 || loading || !hasMore) return;

    loading = true;
    page++;
    try {
        const res = await fetch(`/api/items?page=${page}`);
        const data = await res.json();
        renderItems(data.items);
        hasMore = data.hasMore;
    } catch (err) {
        page--;
        console.error("Load failed:", err);
    }
    loading = false;
}, 150);

window.addEventListener("scroll", handleScroll, { passive: true });

Comprueba soporte con "IntersectionObserver" in window y cambia de estrategia según toque. En la práctica el soporte de navegadores ya ronda el 97% global, así que esto queda como ruta de excepción.

4. Hook de React con guardia síncrona

import { useEffect, useRef, useState, useCallback } from "react";

function useInfiniteScroll(fetchUrl) {
    const [items, setItems] = useState([]);
    const [page, setPage] = useState(1);
    const [loading, setLoading] = useState(false);
    const [hasMore, setHasMore] = useState(true);
    const sentinelRef = useRef(null);
    // Ref, no state, para la guardia: dos eventos de intersection en el
    // mismo tick leen el `loading` del state como false antes del re-render
    const loadingRef = useRef(false);

    const loadMore = useCallback(async () => {
        if (loadingRef.current) return;
        loadingRef.current = true;
        setLoading(true);

        try {
            const res = await fetch(`${fetchUrl}?page=${page}`);
            const data = await res.json();
            setItems(prev => [...prev, ...data.items]);
            setHasMore(data.hasMore);
            setPage(prev => prev + 1);
        } catch (err) {
            console.error("Failed to load:", err);
        } finally {
            loadingRef.current = false;
            setLoading(false);
        }
    }, [fetchUrl, page]);

    useEffect(() => {
        const sentinel = sentinelRef.current;
        if (!sentinel || !hasMore) return;

        const observer = new IntersectionObserver(
            (entries) => {
                if (entries[0].isIntersecting) loadMore();
            },
            { rootMargin: "300px" }
        );

        observer.observe(sentinel);
        return () => observer.disconnect();
    }, [loadMore, hasMore]);

    return { items, loading, hasMore, sentinelRef };
}

function ItemList() {
    const { items, loading, hasMore, sentinelRef } = useInfiniteScroll("/api/items");

    return (
        <div>
            {items.map(item => (
                <div key={item.id} className="item-card">
                    {item.title}
                </div>
            ))}
            {loading && <p role="status">Loading…</p>}
            {hasMore && <div ref={sentinelRef} style={{ height: "1px" }} />}
            {!hasMore && <p>You're all caught up.</p>}
        </div>
    );
}

Cómo funciona

Mermaid flowchart LR diagram

IntersectionObserver vigila un objetivo (el centinela que dejas al final de la lista) y dispara cuando empieza o deja de intersectar el viewport, todo fuera del hilo principal, así que no traba el scroll como lo hace un listener de scroll. Los detalles que importan cuando esto va a producción:

  • rootMargin agranda la zona de disparo: "300px" salta cuando el centinela está aún 300px bajo el pliegue, y el contenido suele estar cargado antes de que el usuario llegue al hueco. Solo acepta px y %, con sintaxis de margin CSS (nada de em ni rem).
  • La bandera loading serializa todo el flujo. Los eventos de intersection disparan ante cambios de estado, no continuamente, pero un scroll rápido puede encolar varios antes de que resuelva el primer fetch. La guardia va síncrona; por eso la versión React usa un ref.
  • hasMore desde la API marca la parada de forma fiable. Un array items vacío también sirve de respaldo, pero una bandera explícita no deja ambigüedad cuando una página vuelve legítimamente vacía.
  • Offset vs cursor: ?page=N&limit=M se rompe cuando se insertan o borran items a mitad de scroll (el usuario ve duplicados o huecos). Si el dataset se escribe mucho, pide a la API paginación por cursor (?after=<último-id>); la clase cambia una línea: arma la URL con el id del último item renderizado en lugar de un contador de página. Ver paginación por cursor para el lado del servidor.
  • El cierre no es negociable en SPAs: disconnect() del observer y abort() del fetch en vuelo al desmontar, o harás append en un nodo desconectado y fugarás el observer.

Variantes

EnfoqueComplejidadCuándo
IntersectionObserverBajaDefault — ~97% de soporte
Evento scroll + debounceMediaWebViews antiguos sin IO
Botón cargar másBajaHay footer, importa deep-linking, a11y crítica
Basado en cursorMediaFeeds con mucha escritura donde el offset deriva
Scroll virtual (react-window)AltaMiles de items renderizados

Buenas prácticas

  • Precarga con rootMargin (200-400px) para que el contenido llegue antes de que se vea el hueco.
  • Guarda los fetchs de forma síncrona: una bandera leída y escrita en el mismo tick, no estado de React.
  • Cuando hasMore se agote, deja de observar el centinela (unobserve) para que no siga disparando.
  • Agrupa los appends con DocumentFragment; N appendChild son N reflows.
  • Cancela fetchs en vuelo y desconecta el observer al desmontar.
  • Renderiza con textContent/createElement, nunca innerHTML con datos del API.
  • Anuncia los cambios de estado: role="status" en el loader, role="alert" en errores.

Errores comunes

  • Sin ruta de error. Un fetch rechazado sin catch deja loading atascado y el scroll muere en silencio al primer request inestable.
  • Guardias solo-async. Leer loading del state de React deja que dos eventos del mismo tick disparen ambos fetch; usa un ref o una variable plana.
  • rootMargin: 0. Con margen cero el centinela tiene que ser totalmente visible antes de que cargue nada: el usuario ve un hueco duro mientras viaja el request.
  • Paginación por offset en un dataset que se mueve. La página 2 se desplaza cuando se insertan items; ahí toca cursor.
  • Fugar el observer. Sin disconnect() al desmontar hay fetchs fantasma y DOM retenido en SPAs.
  • innerHTML con datos del API. Un post.title malicioso y ya publicaste un XSS. Usa textContent.

Lecturas relacionadas

Preguntas frecuentes

¿Por qué IntersectionObserver es mejor que eventos de scroll?

IntersectionObserver corre fuera del hilo principal y solo dispara ante cambios de intersección, así que no compite con el camino del scroll. Un listener de scroll corre en cada frame, necesita throttling manual y encima consulta geometría (scrollY, scrollHeight) en el hilo principal.

¿Cómo evito que miles de items inflen el DOM?

Scroll virtual (react-window, vue-virtual-scroller o similar) renderiza solo el tramo visible más un buffer, manteniendo el DOM en ~50 nodos sin importar el tamaño de la lista. Ver listas virtuales con react-window.

¿Cómo debería verse la respuesta del API?
{
    "items": [...],
    "page": 2,
    "hasMore": true,
    "total": 500
}

Al observer le basta hasMore para saber cuándo parar; total queda como dato opcional por si quieres mostrar un indicador tipo "mostrando X de Y".

¿Y si el usuario pasa volando por el centinela varias veces?

La bandera loading serializa los fetchs, así que corre como máximo un request a la vez. El observer además solo dispara ante cambios de intersección, así que no vuelve a saltar mientras el centinela siga visible, solo al entrar o salir.

¿El scroll infinito perjudica al SEO?

Puede. Googlebot no hace scroll, así que todo lo que solo se renderiza al intersectar nunca se rastrea: de la página 2 en adelante es como si no existiera para buscadores. Para feeds tipo app con navegación por intención está bien, pero para contenido indexable (archivos de blog, listados de productos, docs) mantén URLs paginadas reales o renderiza al menos las primeras páginas en el servidor y deja que el scroll infinito enriquezca desde ahí.

¿El navegador restaura la posición de scroll al volver atrás?

Casi sí: el navegador restaura a la altura del documento que recuerda, pero las páginas cargadas por scroll infinito no se vuelven a pedir, así que la lista queda otra vez solo con la página 1 y el usuario aterriza arriba de una página más corta. Si el back-nav importa, guarda las páginas cargadas en sessionStorage y repítelas al montar (cachea items, page, hasMore y el offset de scroll), o pasa a paginación de verdad donde las propias URLs llevan el estado.