@clroot/react-kakao-postcode

카카오 우편번호 서비스를 위한 React 라이브러리입니다. react-daum-postcode에 영감을 받아, 카카오 우편번호 서비스의 도메인 및 네임스페이스 변경에 대응하여 headless hook 기반의 새로운 구조로 재설계하였습니다.

설치

bun add @clroot/react-kakao-postcode
# npm install @clroot/react-kakao-postcode
# pnpm add @clroot/react-kakao-postcode

React 16.8 이상이 필요합니다.

사용법

1. Headless Hook

useKakaoPostcode는 모든 로직을 담당하는 핵심 hook입니다. UI는 직접 구성합니다.

import { useKakaoPostcode } from '@clroot/react-kakao-postcode';

function AddressSearch() {
  const { status, error, embedRef, open } = useKakaoPostcode({
    onComplete: (address) => {
      // address.zonecode, address.roadAddress 등 사용
      console.log(address.zonecode, address.roadAddress);
    },
  });

  if (status === 'error') return <p>{error?.message}</p>;

  return (
    <div>
      {/* embed 모드: ref를 연결하면 해당 영역에 검색창이 표시됩니다 */}
      <div ref={embedRef} style={{ width: '100%', height: 400 }} />

      {/* popup 모드: open()을 호출하면 팝업으로 열립니다 */}
      <button onClick={() => open()}>팝업으로 열기</button>
    </div>
  );
}

Hook Options

이름	타입	기본값	설명
onComplete	(address: Address) => void	-	주소 선택 완료 시 호출
onClose	(state: CloseState) => void	-	서비스 닫힘 시 호출
onSearch	(data: SearchData) => void	-	검색 실행 시 호출
onResize	(size: Size) => void	-	화면 크기 변경 시 호출
onError	(error: Error) => void	-	스크립트 로드 실패 시 호출
defaultQuery	string	''	검색창 초기 검색어
autoClose	boolean	true	주소 선택 후 자동 닫힘
scriptUrl	string	카카오 CDN	커스텀 스크립트 URL
timeout	number	10000	스크립트 로드 타임아웃 (ms)
maxRetries	number	2	로드 실패 시 재시도 횟수
theme	Theme	-	검색창 테마 커스터마이징

Hook 반환값

이름	타입	설명
status	'idle' | 'loading' | 'ready' | 'error'	현재 상태
error	Error | null	에러 객체
embedRef	(el: HTMLElement | null) => void	embed 모드용 콜백 ref
open	(options?: OpenOptions) => void	popup 모드로 열기
close	() => void	수동 닫기

2. Embed 컴포넌트

검색창을 페이지에 바로 표시합니다.

import { Postcode } from '@clroot/react-kakao-postcode';

function AddressForm() {
  return (
    <Postcode
      onComplete={(address) => console.log(address)}
      style={{ height: 500 }}
    />
  );
}

Props

useKakaoPostcode의 모든 옵션에 더해 다음을 지원합니다.

이름	타입	기본값	설명
className	string	-	래퍼 요소 CSS 클래스
style	CSSProperties	{ width: '100%', height: 400 }	래퍼 요소 스타일

3. Popup 컴포넌트

children을 클릭하면 팝업으로 검색창이 열립니다.

import { PostcodePopup } from '@clroot/react-kakao-postcode';

function AddressButton() {
  return (
    <PostcodePopup onComplete={(address) => console.log(address)}>
      <button>주소 검색</button>
    </PostcodePopup>
  );
}

children에 함수를 전달하면 상태에 따라 UI를 분기할 수 있습니다.

<PostcodePopup onComplete={handleComplete}>
  {({ open, status }) => (
    <button onClick={open} disabled={status === 'loading'}>
      {status === 'loading' ? '불러오는 중...' : '주소 검색'}
    </button>
  )}
</PostcodePopup>

Props

useKakaoPostcode의 모든 옵션에 더해 다음을 지원합니다.

이름	타입	설명
openOptions	OpenOptions	팝업 위치·제목 등 설정
children	ReactNode | (api) => ReactNode	트리거 요소 또는 render function

OpenOptions:

이름	타입	설명
q	string	검색어
left	number | string	팝업 X 좌표
top	number | string	팝업 Y 좌표
autoClose	boolean	주소 선택 후 자동 닫힘
popupTitle	string	팝업 타이틀
popupKey	string	팝업 키 (동일 키 시 같은 창 재사용)

주소 데이터 구조

onComplete 콜백으로 전달되는 Address 객체의 주요 필드입니다.

필드	타입	설명
zonecode	string	우편번호
address	string	기본 주소
addressEnglish	string	기본 주소 (영문)
addressType	'R' | 'J'	R: 도로명, J: 지번
roadAddress	string	도로명 주소
jibunAddress	string	지번 주소
buildingName	string	건물명
apartment	'Y' | 'N'	공동주택 여부
sido	string	시/도
sigungu	string	시/군/구
bname	string	법정동/법정리
query	string	사용자 검색어

전체 필드는 카카오 우편번호 서비스 가이드를 참고하세요.

고급: 스크립트 로더 직접 사용

React 없이 스크립트 로딩만 필요한 경우 createPostcodeLoader를 사용할 수 있습니다.

import { createPostcodeLoader } from '@clroot/react-kakao-postcode';

const loader = createPostcodeLoader({
  timeout: 5000,
  maxRetries: 3,
});

const Postcode = await loader.load();
const instance = new Postcode({
  oncomplete: (address) => console.log(address),
});
instance.open();

react-daum-postcode에서 마이그레이션

react-daum-postcode	@clroot/react-kakao-postcode
<DaumPostcodeEmbed onComplete={fn} />	<Postcode onComplete={fn} />
const open = useDaumPostcodePopup()	const { open } = useKakaoPostcode({ onComplete: fn })
open({ onComplete: fn })	open() (onComplete는 hook에 전달)
에러 시 errorMessage prop	status === 'error'로 직접 처리
스크립트 URL만 커스터마이징	timeout, retry, 커스텀 로더까지 지원

참고

이 패키지는 카카오 우편번호 서비스와 독립적으로 제작되었습니다. React 환경에서 발생하는 이슈는 이 저장소의 이슈 트래커에 남겨주세요. 카카오 우편번호 서비스 자체의 문제는 공식 QnA를 참고해주세요.

License

MIT