React에서 URL 기반 페이지네이션 구현 (feat. useSearchParams)

페이지네이션은 대부분의 리스트 페이지에서는 필수적인 기능입니다.

리스트로 보여줄 데이터 10개 미만이라면 그냥 모든 데이터를 보여줘도 상관없겠지만, 그게 1억개가 된다면 UI적으로는 물론이고 백엔드 서버에도 큰 부하를 줄 것입니다.

그래서 거의 모든 서비스에서도 리스트 페이지를 구현할때, 페이지네이션을 이용할 것입니다.

React 페이지네이션, 왜 URL과 함께 관리해야할까?

저는 vapevibe의 상품 목록에서 원래 useState를 이용하여 페이지네이션을 관리하려고 했습니다. 그 이유로는 번잡한 URL를 사용자에게 보여주고 싶지 않았기때문이죠.

근데 몇가지 문제가 있었습니다.

• 사용자가 '뒤로 가기'를 눌렀을 때, 항상 첫 페이지로 돌아감
• URL을 복사해도 현재 페이지 정보가 유지되지 않음
• 새로고침하면 페이지 상태가 초기화됨

이런 UX 문제를 해결하려면 URL 쿼리스트링으로 페이지 상태를 관리해야 한다는 결론을 내렸습니다. React에서는 react-router-dom의 useSearchParams를 통해 이를 간단하게 구현할 수 있습니다. 

---

React Router의 useSearchParam로 쿼리스트링 다루기

React Router v6부터 제공되는 useSearchParams 훅(Hook)은 브라우저 URL의 쿼리 파라미터를 읽고 수정하는 데 특화되어 있습니다.

import { useSearchParams } from 'react-router-dom';

const [searchParams, setSearchParams] = useSearchParams();
const page = searchParams.get('page');

get() 으로 파라미터를 읽고, setSearchParams({ page: '2' }) 처럼 값을 바꿔 URL을 갱신할 수 있습니다. 

 

---

페이지네이션 구현 흐름: URL > 상태 > API 호출

페이지네이션 로직은 다음과 같은 흐름으로 설계됩니다:

1. useSearchParams 로 현재 페이지 값(page)을 URL에서 가져오기
2. useEffect 로 page 가 바뀔 때마다 API 호출
3. 응답 받은 데이터를 리스트로 렌더링
4. MUI의 Pagination 컴포넌트로 UI 구성
5. onChange 시 setSearchParams({ page }) 호출하여 URL 갱신 

코드는 아래와 같습니다.

const [searchParams, setSearchParams] = useSearchParams();
const page = parseInt(searchParams.get("page") || "1", 10);

useEffect(() => {
  fetchData({ page });
}, [page]);

const handleChange = (event: React.ChangeEvent<unknown>, value: number) => {
  setSearchParams({ page: value.toString() });
};

---

실제 코드로 보는 페이지네이션 구현 예시 (with MUI Pagination)

import Pagination from '@mui/material/Pagination';

<Pagination
  count={totalPages}
  page={page}
  onChange={handleChange}
  color="primary"
/>

• count 는 전체 페이지 수
• page 는 현재 페이지 번호 (1부터 시작)
• onChange 에서는 setSearchParams 로 URL 업데이트

전체적으로 API 호출과 UI 상태가 page 라는 단일 URL 파라미터로 일관되게 관리되므로, 뒤로가기/앞으로가기, URL 공유, 초기 진입 시 상태 복원 모두 자연스럽게 처리됩니다.

---

이로 인해 내가 해결한 문제

1. 페이지가 새로고침되면 초기화됨

useSearchParams().get("page") 는 항상 URL 기준이므로, 새로고침해도 상태가 유지됨

2. 뒤로가기 눌렀을 때 페이지 상태가 바뀌지 않음

setSearchParams 은 브라우저 히스토리에 반영되므로 back/forward 모두 정상 작동

---

마무리: 페이지네이셔 UR로 관리하면 얻는 UX 개선 효과 및 느낌점

React에서 페이지네이션을 URL과 연결하면, 단순한 리스트 기능이 아니라 다음과 같은 개선 효과를 함께 얻을 수 있습니다:

• 사용자 친화적 히스토리 이동
• 검색/공유 가능한 URL
• 새로고침에도 안전한 상태 복원

프론트엔드 개발은 항상 디테일과 꼼꼼함을 필수로 하는 거 같습니다. 백엔드 개발도 비슷한 능력을 필요로 하지만, 세부적인 부분까지 들어간다면 UI, UX, 기기별 호환, 상태 관리, 컴포넌트 분리 및 관리 등등.. 

정신 바짝 차리고 만듭시다.