pushState y replaceState
Actualice la URL del navegador sin recargar toda la página
pushState y replaceState es una lección gratuita de HTML Academy en CoddyKit. Esta es la lección 1 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de HTML Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de HTML Academy incluye 4 lecciones en total.
La History API
La History API permite que una página cambie la URL mostrada en la barra de direcciones sin activar una navegación completa. Combinada con la renderización del lado del cliente, permite crear Single-Page Applications con una experiencia similar a la nativa sin renunciar a URLs que se pueden guardar en marcadores.
pushState
history.pushState(state, "", url) añade una nueva entrada al historial del navegador. La URL de la barra de direcciones se actualiza inmediatamente y no se realiza ninguna solicitud de red. El usuario puede volver a la entrada anterior mediante el botón Atrás del navegador.
history.pushState({ view: "settings" }, "", "/settings");El argumento state
El primer argumento es un conjunto arbitrario de datos serializables asociado a la entrada. Puede volver a leerlo mediante history.state o en eventos popstate. Úselo para pasar el estado de la interfaz (qué pestaña estaba abierta o la posición de desplazamiento), de modo que al volver pueda restaurarse exactamente la vista anterior.
El argumento title
El segundo argumento es el título de la entrada. En la práctica, todos los navegadores modernos lo ignoran: establezca document.title = "..." directamente para cambiar el título. Por convención, pase una cadena vacía; no tiene ningún efecto.
El argumento url
El tercer argumento es la nueva URL. Las URL relativas se resuelven con respecto a la página actual; la nueva URL debe ser del mismo origen (si es de otro origen, se produce un error SecurityError). Los navegadores no solicitan la URL: pushState solo actualiza la barra de direcciones y el historial.
replaceState
history.replaceState(state, "", url) reemplaza la entrada actual del historial en lugar de añadir una nueva. Úselo cuando quiera actualizar la URL sin crear un nuevo paso de navegación hacia atrás (por ejemplo, al actualizar la cadena de consulta de un filtro).
// Update query string in place
const url = new URL(location);
url.searchParams.set("filter", "open");
history.replaceState(null, "", url);Casos de uso de pushState
Cambios de ruta en una SPA (hacer clic en un enlace de navegación sin una recarga completa), apertura de un modal (para que el botón de retroceso lo cierre) y transiciones entre pasos de un asistente. Cada estado significativo debe ser una nueva entrada del historial, para que el botón de retroceso se comporte como esperan los usuarios.
Casos de uso de replaceState
Actualizaciones de filtros, ordenación o paginación que no deben llenar el historial, redirecciones después de completar parcialmente un formulario y actualización de parámetros de seguimiento sin crear entradas navegables. Cuando el usuario pulsa el botón de retroceso, se salta estos estados «intermedios».
Actualice la vista después de pushState
pushState solo cambia la URL; su código debe actualizar el DOM por separado. El patrón consiste en renderizar el contenido nuevo y después llamar a pushState. Juntas, ambas acciones producen la experiencia de una SPA.
function navigate(path) {
renderPage(path);
history.pushState(null, "", path);
window.scrollTo(0, 0);
}Actualizaciones del título y los metadatos
Actualice document.title y las etiquetas meta og:title después de la navegación, para que el uso compartido en redes sociales y los títulos de las pestañas del navegador reflejen la vista actual. Si lo olvida, se conserva el título original en los usos compartidos posteriores: es un error sutil, pero común, en las SPA.
pushState inicial al cargar la página
Llamar a pushState antes de que el usuario haya navegado sobrescribe la entrada inicial. Para asociar un estado a la primera entrada de la página, use replaceState: añade el estado sin alterar la profundidad del historial.
Restricción de seguridad
Las URL de pushState deben ser del mismo origen. Intentar usar pushState con https://evil.com produce un error SecurityError. Esto evita que las páginas suplanten la barra de direcciones para hacer creer a los usuarios que están en otro sitio.
Comprobación de conocimientos
¿Qué hace history.replaceState que no hace history.pushState?
Resumen
pushState añade una nueva entrada al historial sin recargar la página: es la base del enrutamiento de las SPA. replaceState actualiza la entrada actual en su lugar para realizar cambios cosméticos en la URL. Ambos requieren URL del mismo origen e ignoran el argumento title. Actualice siempre el DOM por separado y recuerde actualizar document.title y las etiquetas meta después de la navegación.
Preguntas frecuentes
¿La lección «pushState y replaceState» es gratis?
Sí — el texto completo de «pushState y replaceState» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de HTML Academy, actualiza a CoddyKit PRO. El curso de HTML Academy incluye 4 lecciones en total.
¿Qué aprenderé en «pushState y replaceState»?
Actualice la URL del navegador sin recargar toda la página Practicas HTML Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.
¿Necesito experiencia previa para empezar HTML Academy?
No se requiere experiencia previa. HTML Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 1 de 4.
¿Cuánto tiempo toma la lección «pushState y replaceState»?
La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.
¿Puedo escribir y ejecutar código en esta lección de HTML Academy?
Sí. Cada lección de HTML Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.
Todas las lecciones de este curso
- pushState y replaceState
- El evento popstate
- Enrutamiento basado en hash frente a basado en rutas
- La Navigation API en navegadores modernos