올바른 이해와 사용 방법

자바스크립트를 이용하면 현재 페이지를 연 브라우저 방문 기록(Session History)을 읽고 이동하며 제어할 수 있습니다.
이때 window.history 객체를 사용합니다.

다음의 목차로 설명합니다.

브라우저는 사용자가 현재 창이나 탭에서 방문한 페이지를 방문 기록(Session History)으로 관리합니다. 사용자가 새로운 페이지로 이동하거나 브라우저의 "뒤로 가기" 또는 "앞으로 가기" 기능을 사용할 수 있는 것도 이 방문 기록을 기반으로 동작합니다.

자바스크립트에서는 window.history 객체를 사용하여 현재 창이나 탭의 방문 기록을 읽거나, 특정 방문 기록으로 이동하고, 새로운 방문 기록을 추가하거나 현재 방문 기록을 교체하는 등의 작업을 수행할 수 있습니다. 하지만, 사용자의 프라이버시와 보안 등을 고려해 방문 기록에 저장된 URL 목록이나 다른 페이지의 내용을 직접 가져오는 기능은 지원하지 않습니다.

현재 창이나 탭에서 브라우저 방문 기록의 개수는 window.history.length 속성을 사용해 가져올 수 있습니다.

window.history.length 속성은 현재 브라우저 창이나 탭의 방문 기록 총 개수를 정수로 반환하는 읽기 전용 속성입니다. 예를 들어, 새로 열린 브라우저 창이나 탭의 초기 방문 기록 개수는 1입니다.

window 객체는 생략할 수 있으며, 보통 history.length를 사용합니다.

구문 
history.length;
// 또는 window.history.length;

예제

변수에 값 할당하기 
const totalPages = history.length;
// 또는 const totalPages = window.history.length;

console.log(totalPages); // 방문 기록 개수를 정수로 출력
조건문에서 비교하기 
if (history.length === 1) {
    console.log("현재 창(또는 탭)에서 방문한 첫 번째 페이지입니다.");
}

현재 창이나 탭의 브라우저 방문 기록에서 특정 위치로 이동하려면 window.history.go() 메서드를 사용합니다.
이때, 매개변수에는 현재 페이지에서 상대적으로 이동하려고 하는 방문 기록의 위치를 정수로 지정합니다.

  • 음수로 지정하면 이전 방문 기록으로 이동합니다.
    (예를 들어, window.history.go(-2)는 현재 페이지를 기준으로 이전의 두 페이지 뒤로 이동합니다.)
  • 0을 지정(window.history.go(0))하면 현재 페이지로 이동하게 됩니다. 즉, 현재 페이지를 새로고침합니다.
  • 양수로 지정하면 다음 방문 기록으로 이동합니다.
    (예를 들어, window.history.go(2)는 현재 페이지를 기준으로 다음의 두 페이지 앞으로 이동합니다.)

window 객체는 생략할 수 있으며, 보통 history.go()를 사용합니다.

구문 
history.go(n);
// 또는 window.history.back(n);

만약, 매개 변수에 아무것도 지정하지 않으면, 0을 지정한것과 동일하게 작동합니다.

만약, 매개 변수에 음수를 지정했을 때 브라우저의 방문 기록(Session History)에 이전 페이지 기록이 없다면 아무런 반응이 일어나지 않습니다.

만약, 매개 변수에 양수를 지정했을 때 브라우저의 방문 기록(Session History)에 다음 페이지 기록이 없다면 아무런 반응이 일어나지 않습니다.

예제

버튼 클릭 시 이전 페이지로 이동하기 onclick 속성으로 버튼을 클릭했을 때, 이전 페이지로 이동하기 
<button type="button" onclick="history.go(-1)">이전 페이지로 이동하기</button>
<!-- 또는 -->
<button type="button" onclick="window.history.go(-1)">이전 페이지로 이동하기</button>
버튼 클릭 시 이전 페이지로 이동하기 addEventListener() 메서드로 버튼을 클릭했을 때, 이전 페이지로 이동하기 
<button type="button" id="back-btn">이전 페이지로 이동하기</button>

<script>
    const backBtn = document.getElementById("back-btn");
    
    backBtn.addEventListener("click", () => {
        history.go(-1);
        // 또는 window.history.go(-1);
    });
</script>

현재 창이나 탭의 브라우저 방문 기록에 저장된 상태(State) 데이터를 가져오려면 window.history.state 속성을 사용합니다.
이 속성은 현재 방문 기록에 연결된 상태(State) 데이터를 반환하며, 상태 데이터가 없다면 null을 반환합니다.

방문 기록에 저장된 상태(State) 데이터

window.history.state 속성을 사용하면 현재 창이나 탭의 브라우저 방문 기록에 저장된 상태(State) 데이터를 가져올 수 있습니다.

이 데이터는 브라우저가 자동으로 생성하는 것이 아닙니다. 개발자가 직접 설정하여 저장한 정보입니다.

개발자는 사용자가 현재 방문 중인 페이지의 UI 상태나 애플리케이션 상태(예: 선택된 탭, 스크롤 위치 등)에 따라 관련 정보를 현재 방문 기록의 상태(State) 데이터로 저장할 수 있습니다. 이 저장된 정보가 해당 방문 페이지의 기록에 저장된 상태(State) 데이터입니다.

현재 방문 중인 페이지의 상태 데이터는 window.history.pushState() 또는 window.history.replaceState() 메서드로 저장하며, window.history.state 속성으로 가져올 수 있습니다.

구문

window 객체는 생략할 수 있으며, 보통 history.state를 사용합니다.

JavaScript 
history.state;
// 또는 window.history.state;

예제

현재 방문 중인 페이지의 상태 데이터 가져오기 
const state = history.state;
// 또는 const state = window.history.state;

console.log(state);
현재 방문 중인 페이지의 상태 데이터가 있는지 확인하기 
if (history.state !== null) {
    console.log("상태 데이터가 존재합니다.");
} else {
    console.log("상태 데이터가 없습니다.");
}

일반적으로 브라우저는 새로운 페이지로 이동할 때 자동으로 방문 기록(Session History)을 추가합니다.

하지만 window.history.pushState() 메서드를 사용하면 새로운 페이지를 서버에 요청하지 않고 현재 브라우저의 창이나 탭의 방문 기록(Session History)에 새로운 방문 기록을 직접 추가할 수 있습니다. 이 메서드는 현재 페이지를 새로 불러오지 않고 새로운 방문 기록을 추가하면서, 필요에 따라 상태(State) 데이터와 URL도 함께 변경할 수 있습니다.

이 기능은 페이지를 새로고침하지 않고 화면의 일부만 변경하는 SPA(Single Page Application)에서 자주 사용됩니다.

구문

window 객체는 생략할 수 있으며, 보통 history.pushState()를 사용합니다.

JavaScript 
history.pushState(state, unused)
history.pushState(state, unused, url)

// 또는
window.history.pushState(state, unused)
window.history.pushState(state, unused, url)

매개변수

window.history.pushState() 메서드의 매개변수 설명
state
  • 새롭게 추가할 방문 기록에 저장할 상태(State) 데이터입니다.
  • 객체(Plain objects, 일반 객체)뿐만 아니라 문자열, 숫자, 배열 등 구조화 가능한(Structured Clone) 자바스크립트 데이터라면 무엇이든 저장할 수 있습니다.
unused 이 매개변수는 역사적인 이유로 존재하며 현재는 사용되지 않습니다. 일반적으로 관례상 빈 문자열("")을 지정합니다.
url
  • 새로운 방문 기록에 표시할 URL을 문자열로 지정합니다.
  • 새 URL은 절대 경로일 필요는 없으며, 상대 경로인 경우 현재 URL을 기준으로 해석됩니다.
  • 현재 페이지와 동일한 출처(Same-origin)여야 하며, 다른 도메인으로 설정 시 예외(SecurityError)가 발생합니다.
  • 이 매개변수를 지정하지 않으면 문서의 현재 URL이 사용됩니다.
  • 브라우저는 pushState() 호출 후 이 URL의 페이지를 새로 로드하지 않으며, 주소창의 URL만 변경됩니다.

예제

JavaScript 
/* 초기 URL 예: https://www.example.com/ */

// 1. 상태 { page: 1 } 저장 + URL 변경
history.pushState({ page: 1 }, "", "/page-1");

console.log("현재 state:", history.state); // 출력: {page: 1}
// 현재 URL: https://www.example.com/page-1

// 2. 상태 { page: 2 } 저장 + URL 변경
history.pushState({ page: 2 }, "", "/page-2");

console.log("현재 state:", history.state); // 출력: {page: 2}
// 현재 URL: https://www.example.com/page-2

/* 3. 브라우저의 '뒤로 가기' 버튼을 누르면
      주소창은 다시 /page-1로 변하고,
      history.state는 { page: 1 }로 복원됩니다.
*/

window.history.pushState() 메서드는 브라우저의 현재 창 또는 탭의 방문 기록(Session History)에 새로운 기록을 추가하는 반면, window.history.replaceState() 메서드는 현재 활성화된 방문 기록의 상태(State)와 URL을 새로운 값으로 교체(변경)합니다.

window.history.replaceState() 메서드도 window.history.pushState() 메서드처럼 현재 페이지를 새로 불러오지 않습니다.

하지만 window.history.replaceState() 메서드는 window.history.pushState() 메서드처럼 방문 기록(Session History)에 새로운 기록을 추가하지 않기 때문에 사용자가 '뒤로 가기' 버튼을 눌렀을 때, window.history.replaceState() 메서드로 교체(변경)하기 바로 이전의 기록 항목이 아닌 그 이전 기록 항목으로 이동하게 됩니다.

이 기능은 페이지를 새로고침하지 않고 화면의 일부만 변경하는 SPA(Single Page Application)에서 방문 기록은 남지 않으면서 현재 활성화된 방문 기록을 교체할 때(예: 검색 필터 적용, 탭 전환 등) 자주 사용됩니다.

구문

window 객체는 생략할 수 있으며, 보통 history.replaceState()를 사용합니다.

JavaScript 
history.replaceState(state, unused)
history.replaceState(state, unused, url)

// 또는
window.history.replaceState(state, unused)
window.history.replaceState(state, unused, url)

매개변수

window.history.replaceState() 메서드의 매개변수 설명
state
  • 교체(변경)할 방문 기록에 저장할 상태(State) 데이터입니다.
  • 객체(Plain objects, 일반 객체)뿐만 아니라 문자열, 숫자, 배열 등 구조화 가능한(Structured Clone) 자바스크립트 데이터라면 무엇이든 저장할 수 있습니다.
unused 이 매개변수는 역사적인 이유로 존재하며 현재는 사용되지 않습니다. 일반적으로 관례상 빈 문자열("")을 지정합니다.
url
  • 교체(변경)할 방문 기록에 표시할 URL을 문자열로 지정합니다.
  • 새 URL은 절대 경로일 필요는 없으며, 상대 경로인 경우 현재 URL을 기준으로 해석됩니다.
  • 현재 페이지와 동일한 출처(Same-origin)여야 하며, 다른 도메인으로 설정 시 예외(SecurityError)가 발생합니다.
  • 브라우저는 replaceState() 호출 후 이 URL의 페이지를 새로 로드하지 않으며, 주소창의 URL만 변경됩니다.

예제

JavaScript 
/* 현재 URL 예: https://www.example.com/ */

// 1. 상태 { page: 1 }을 가진 새로운 기록을 추가
history.pushState({ page: 1 }, "", "/page-1");

// 2. 현재 방문 기록 항목의 상태를 { page: 2 }로 교체 (새로운 기록이 추가되지 않음)
history.replaceState({ page: 2 }, "", "/page-2");

console.log("현재 상태:", history.state); // 출력: { page: 2 }
// 주소창 결과: https://www.example.com/page-2

/* 3. '뒤로 가기' 버튼을 누르면
      /page-1로 가지 않고, 
      최초 페이지인 https://www.example.com/ 로 바로 이동합니다.
*/

브라우저의 방문 기록(Session History)이 변경되어 이전 페이지 또는 다음 페이지로 이동할 때, 즉 현재 표시되고 있는 방문 기록 항목(현재 활성화된 항목)이 다른 항목으로 전환된 후 발생하는 이벤트가 popstate 이벤트입니다.

브라우저의 방문 기록(Session History)에 새로운 방문 기록을 추가할 때에는 popstate 이벤트가 발생하지 않습니다. 즉, 기존에 있던 방문 기록 항목(entry) 사이를 오갈 때 발생합니다.

popstate 이벤트는 다음과 같은 상황에서 발생합니다.

  • window 객체에서 발생하는 이벤트입니다.
  • 사용자가 브라우저의 "뒤로 가기" 버튼을 눌렀을 때
  • 사용자가 브라우저의 "앞으로 가기" 버튼을 눌렀을 때
  • window.history.go() 메서드를 사용해 실제 특정 방문 기록으로 이동했을 때
    (단, window.history.go(0)으로 현재 페이지로 이동하거나, 지정한 특정 방문 기록이 브라우저의 현재 방문 기록에 없을 경우는 제외)
  • window.history.back() 메서드를 사용해 이전 페이지로 이동했을 때
    (단, 브라우저의 현재 방문 기록에 이전 페이지 기록이 없는 경우는 제외)
  • window.history.forward() 메서드를 사용해 다음 페이지로 이동했을 때
    (단, 브라우저의 현재 방문 기록에 다음 페이지 기록이 없는 경우는 제외)

주의: 이럴 때는 발생하지 않습니다!

  • 브라우저의 방문 기록(Session History)에 새로운 방문 기록을 추가할 때
    (예: <a> 요소를 통한 이동, <form> 제출 등 HTML로 이동하는 경우, JavaScript를 사용한 새로운 페이지로 이동, 서버 사이드 언어를 사용한 HTTP Header 리다이렉트 등)
  • 사용자가 브라우저의 "새로고침" 버튼을 눌렀을 때
  • window.history.pushState() 메서드를 사용해 표시되는 URL이 바뀔 때
  • window.history.replaceState() 메서드를 사용해 표시되는 URL이 바뀔 때
  • 그 밖에 JavaScript를 사용해 현재 페이지를 새로고침했을 때

구문

JavaScript 
window.addEventListener("popstate", (event) => { })

window.onpopstate = (event) => { }

예제

사용자가 브라우저의 '뒤로 가기' 버튼을 눌러 이전에 방문했던 페이지로 돌아왔다고 가정합니다.

이 페이지에는 여러 탭으로 콘텐츠를 구분하여 보여주고 있으며, 사용자가 마지막으로 선택한 탭은 이미 window.history.pushState() 메서드를 사용해 저장해 두었습니다. 사용자가 이 페이지로 다시 돌아왔을 때는 여러 탭 중 이전에 선택했던 탭을 다시 보여주는 것이 UX(User Experience, 사용자 경험) 측면에서 더 좋을 수 있습니다.

아래 예제는 popstate 이벤트를 활용해 사용자가 이 페이지로 다시 돌아왔을 때 저장된 탭 정보를 읽어 이전에 선택했던 탭을 복원하는 예제입니다.

JavaScript 
// 탭 전환 함수
function selectTab(tabName, shouldPushState = true) {
    // 실제 화면 갱신 로직 (예제에서는 콘솔 출력으로 대체)
    console.log(`현재 탭: ${tabName}`);

    // 새로운 방문 기록 추가
    if (shouldPushState) {
        history.pushState({ tab: tabName }, "", `?tab=${tabName}`);
    }
}

// 브라우저의 방문 기록이 변경되면 이전 탭 복원
window.addEventListener("popstate", () => {
    let tabToRestore = null;

    // 히스토리에 저장된 상태값이 있는지 확인 후 탭 설정
    if (history.state) {
        tabToRestore = history.state.tab;
    } else {
        tabToRestore = "home";
    }

    console.log(`복원된 탭: ${tabToRestore}`);

    // 방문 기록을 추가하지 않고 화면만 복원
    selectTab(tabToRestore, false);
});

명세서

자바스크립트 URL 방문 기록(Session History) 다루기의 명세서 사양
명세서 사양
window.history HTML
#the-history-interface
popstate HTML
#event-popstate
onpopstate HTML
#handler-window-onpopstate

브라우저 호환성

자바스크립트 URL 방문 기록(Session History) 다루기의 브라우저 호환성
인터페이스
데스크탑 Chrome
Chrome
데스크탑 Edge
Edge
데스크탑 Firefox
Firefox
Safari
Safari
window.history 1 12 1 1
window.history.length 1 12 1 1
window.history.go() 1 12 1 1
window.history.state 19 12 4 6
window.history.pushState() 5 12 4 5
window.history.replaceState() 5 12 4 5
popstate 이벤트 5 12 4 5

참고문헌

같이 보기