🔍 React에서 URLSearchParams 사용하기

React 를 사용한 웹 애플리케이션에서는
URL 쿼리 스트링을 통해 페이지 상태를 유지하거나 데이터를 전달하는 일이 잦다.

이럴 때 URLSearchParams를 활용하면 URL 쿼리를 쉽게 파싱하고 조작할 수 있다.

---

🌐 URLSearchParams란?

URLSearchParams는 URL 쿼리 문자열을 다루기 위한 내장 객체이다.

예를 들어, 다음과 같은 URL이 있다고 하자:

https://example.com/search?keyword=react&page=2

여기서 ?keyword=react&page=2는 쿼리 스트링이고,

URLSearchParams를 이용하면 해당 값을 쉽게 읽고 조작할 수 있다.

---

🔎 쿼리 읽기

React 컴포넌트 내부에서 쿼리 문자열을 읽는 일반적인 방법은 다음과 같다:

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

function SearchPage() {
  const { search } = useLocation();
  const query = new URLSearchParams(search);

  const keyword = query.get('keyword'); // 'react'
  const page = query.get('page');       // '2'

  return (
    <div>
      <h1>검색어: {keyword}</h1>
      <p>페이지: {page}</p>
    </div>
  );
}

• useLocation()은 현재 URL의 정보를 가져오고
• search는 ? 포함한 쿼리 문자열
• query.get('key')를 통해 값을 추출할 수 있다.

---

🔄 쿼리 변경하기

React 에서는 URLSearchParams를 조작하고 navigate를 통해 URL을 변경할 수 있다.

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

function FilterButton() {
  const navigate = useNavigate();

  const handleClick = () => {
    const params = new URLSearchParams();
    params.set('keyword', 'react');
    params.set('page', '1');

    navigate(`/search?${params.toString()}`);
  };

  return <button onClick={handleClick}>React 검색하기</button>;
}

• params.set()으로 쿼리 값 추가/변경
• params.toString()으로 직렬화
• navigate()로 URL 갱신

---

🧪 여러 값 처리하기

URL에 배열 같은 데이터를 넣고 싶다면 같은 키를 여러 번 설정하면 된다.

const params = new URLSearchParams();
params.append('filter', 'frontend');
params.append('filter', 'backend');

console.log(params.toString());
// filter=frontend&filter=backend

const filters = params.getAll('filter');
// ['frontend', 'backend']

---

⚠️ 주의할 점

• URLSearchParams는 문자열만 다룬다. 숫자, boolean, 배열은 직접 형변환이 필요함
• 값이 없으면 null을 반환한다 → ||나 optional chaining (?.)으로 처리

---

🔨 TIL

• URLSearchParams는 React에서 쿼리 스트링을 읽고 쓰는 데 매우 유용하다.
• useLocation()과 함께 사용하면 현재 URL의 쿼리를 쉽게 추출할 수 있다.
• URL을 동적으로 업데이트하려면 useNavigate()와 함께 조작하면 된다.
• 여러 값을 같은 키로 관리할 때는 append()와 getAll()을 활용하자.
• 쿼리 기반 필터링, 페이지네이션, 검색 기능 구현 시 필수 도구다!