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ón | Mejor opción | Por qué |
|---|---|---|
| Los usuarios saltan a items o páginas concretas | Paginación numerada | No hay forma de enlazar la “página 7” de un stream |
| Hay contenido bajo la lista (footer, filtros) | Botón cargar más | La lista empuja el footer para siempre |
| El usuario retoma donde lo dejó | Paginación + restaurar scroll | El back-nav aterriza a mitad de stream sin ancla |
| El contenido cambia rápido (items nuevos arriba) | Paginación por cursor | El offset ?page=N duplica o salta items |
| Audiencia que depende de lectores de pantalla | Botón cargar más | Insertar 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
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:
rootMarginagranda 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 deemnirem).- La bandera
loadingserializa 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. hasMoredesde la API marca la parada de forma fiable. Un arrayitemsvací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=Mse 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 yabort()del fetch en vuelo al desmontar, o harás append en un nodo desconectado y fugarás el observer.
Variantes
| Enfoque | Complejidad | Cuándo |
|---|---|---|
| IntersectionObserver | Baja | Default — ~97% de soporte |
| Evento scroll + debounce | Media | WebViews antiguos sin IO |
| Botón cargar más | Baja | Hay footer, importa deep-linking, a11y crítica |
| Basado en cursor | Media | Feeds con mucha escritura donde el offset deriva |
| Scroll virtual (react-window) | Alta | Miles 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
hasMorese agote, deja de observar el centinela (unobserve) para que no siga disparando. - Agrupa los appends con
DocumentFragment; NappendChildson N reflows. - Cancela fetchs en vuelo y desconecta el observer al desmontar.
- Renderiza con
textContent/createElement, nuncainnerHTMLcon 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
catchdejaloadingatascado y el scroll muere en silencio al primer request inestable. - Guardias solo-async. Leer
loadingdel 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. innerHTMLcon datos del API. Unpost.titlemalicioso y ya publicaste un XSS. UsatextContent.
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.
Recursos Relacionados
Funciones Debounce y Throttle en JavaScript
Controla la tasa de ejecución de funciones con debounce y throttle. Cubre leading y trailing edge, timers cancelables y casos de uso reales.
RecipeService Worker Offline Caching para PWA en JavaScript
Sirve tu aplicación web sin conexión con Service Workers y la Cache API: precaché, estrategias de caché en runtime y página de respaldo.
RecipeVirtualizar Listas Largas con react-window
Cómo renderizar listas grandes eficientemente en React usando react-window para virtualización del DOM, incluyendo filas de altura fija y variable y layouts de grid.
RecipePaginación por Cursor en PostgreSQL (Keyset vs OFFSET)
Implementa paginación eficiente por cursor para datasets grandes en PostgreSQL, evitando la degradación de rendimiento de OFFSET con paginación keyset indexada y ordenamiento estable
RecipeImplementar Lazy Loading para Imágenes, Componentes y Datos
Cómo diferir la carga de recursos no críticos hasta que se necesitan, mejorando el tiempo de carga inicial, reduciendo el ancho de banda y optimizando Core Web Vitals.
PatternPatrón Eager Loading: resuelve el problema N+1
Carga datos relacionados en una sola consulta en lugar de múltiples llamadas a la base de datos, evitando el problema N+1 y mejorando el rendimiento de lectura.