react-daum-postcode

Daum 우편번호 검색 서비스를 React 환경에서 간편하게 이용할 수 있습니다.

Install

npm install react-daum-postcode
# or
yarn add react-daum-postcode

# if react not installed, install react also.
npm install react
# or
yarn add react

Embed

DaumPostcodeEmbed 컴포넌트를 사용하여, 우편번호 검색 서비스를 임베드 방식으로 사용할 수 있습니다.

import React from 'react';
import DaumPostcodeEmbed from 'react-daum-postcode';

const Postcode = () => {
  const handleComplete = (data) => {
    let fullAddress = data.address;
    let extraAddress = '';

    if (data.addressType === 'R') {
      if (data.bname !== '') {
        extraAddress += data.bname;
      }
      if (data.buildingName !== '') {
        extraAddress += extraAddress !== '' ? `, ${data.buildingName}` : data.buildingName;
      }
      fullAddress += extraAddress !== '' ? ` (${extraAddress})` : '';
    }

    console.log(fullAddress); // e.g. '서울 성동구 왕십리로2길 20 (성수동1가)'
  };

  return <DaumPostcodeEmbed onComplete={handleComplete} {...props} />;
};

DaumPostcodeEmbed 컴포넌트에 다음 우편번호 서비스의 생성자 및 임베드 설정값 등을 props로 전달할 수 있습니다. 전달하지 않은 설정값은 다음 우편번호 서비스의 기본 설정을 따라갑니다.

name	type	default	description
scriptUrl	string	CURRENT_URL	Daum 우편번호 서비스의 스크립트 주소입니다.
onComplete	function	undefined	우편번호 검색이 끝났을 때 사용자가 선택한 정보를 받아올 콜백함수입니다. 주소 데이터의 구성은 Daum 가이드를 참고해주세요.
onSearch	function	undefined	주소를 검색할 경우 실행되는 콜백함수입니다. 검색 결과 정보의 구성은 Daum 가이드를 참고해주세요.
onClose	function	undefined	검색 결과를 선택하여, 서비스가 닫힐 때 실행되는 콜백함수입니다.
onResize	function	undefined	검색 결과로 인해, 우편번호 서비스의 화면 크기가 변경될 때 호출되는 콜백함수입니다. 변경된 화면 정보의 구성은 Daum 가이드를 참고해주세요.
className	string	undefined	우편번호 검색창을 감싸는 최상위 엘리먼트에 적용할 클래스 이름입니다.
style	object	{ width:"100%", height:400 }	우편번호 검색창을 감싸는 최상위 엘리먼트에 적용할 스타일입니다.
defaultQuery	string	undefined	우편번호 검색창에 기본으로 입력할 검색어입니다.
autoClose	boolean	true	우편번호 검색 완료시 자동 닫힘 여부입니다. 주소를 선택하면, 최상위 엘리먼트를 돔에서 제거합니다.
errorMessage	ReactNode	<p>현재 Daum 우편번호 서비스를 이용할 수 없습니다. 잠시 후 다시 시도해주세요.</p>	우편번호 서비스 스크립트 로드에 실패했을 때 나타낼 에러 메세지 입니다.

기타 Daum 우편번호 생성자 속성들을 동일한 이름으로 props를 전달할 수 있습니다. 속성값에 대해서는 Daum 우편번호 서비스 가이드를 참고해주세요.

Popup

useDaumPostcodePopup hook 을 사용하여, 반환받은 함수를 통해 우편번호 검색 서비스를 팝업 방식으로 이용할 수 있습니다.

import React from 'react';
import { useDaumPostcodePopup } from 'react-daum-postcode';

const Postcode = () => {
  const open = useDaumPostcodePopup(scriptUrl);

  const handleComplete = (data) => {
    let fullAddress = data.address;
    let extraAddress = '';

    if (data.addressType === 'R') {
      if (data.bname !== '') {
        extraAddress += data.bname;
      }
      if (data.buildingName !== '') {
        extraAddress += extraAddress !== '' ? `, ${data.buildingName}` : data.buildingName;
      }
      fullAddress += extraAddress !== '' ? ` (${extraAddress})` : '';
    }

    console.log(fullAddress); // e.g. '서울 성동구 왕십리로2길 20 (성수동1가)'
  };

  const handleClick = () => {
    open({ onComplete: handleComplete });
  };

  return (
    <button type='button' onClick={handleClick}>
      Open
    </button>
  );
};

useDaumPostcodePopup 실행 시 우편번호 서비스의 스크립트 주소를 전달할 수 있습니다. 반환한 함수를 실행할 때 다음 우편번호 서비스의 생성자 및 팝업 설정값을 전달할 수 있습니다. 전달하지 않은 설정값은 다음 우편번호 서비스의 기본 설정을 따라갑니다.

name	type	default	description
scriptUrl	string	CURRENT_URL	Daum 우편번호 서비스의 스크립트 주소입니다.
onComplete	function	undefined	우편번호 검색이 끝났을 때 사용자가 선택한 정보를 받아올 콜백함수입니다. 주소 데이터의 구성은 Daum 가이드를 참고해주세요.
onSearch	function	undefined	주소를 검색할 경우 실행되는 콜백함수입니다. 검색 결과 정보의 구성은 Daum 가이드를 참고해주세요.
onClose	function	undefined	검색 결과를 선택하여, 서비스가 닫힐 때 실행되는 콜백함수입니다.
onResize	function	undefined	검색 결과로 인해, 우편번호 서비스의 화면 크기가 변경될 때 호출되는 콜백함수입니다. 변경된 화면 정보의 구성은 Daum 가이드를 참고해주세요.
width	string|number	undefined	우편번호 검색창의 가로 너비입니다.
height	string|number	undefined	우편번호 검색창의 세로 높이입니다.
defaultQuery	string	undefined	우편번호 검색창에 기본으로 입력할 검색어입니다.
top	string|number	undefined	팝업의 Y 위치를 나타내는 값입니다.
left	string|number	undefined	팝업의 X 위치를 나타내는 값입니다.
popupTitle	string	undefined	팝업창의 상태표시줄에 나오는 Title 값을 지정할 수 있습니다. 전달하지 않을 경우, 다음 우편번호의 기본 설정 문구가 출력됩니다.
popupKey	string	undefined	팝업창의 key 입니다. 전달하지 않을 경우 매번 새창이 열리게 됩니다.
autoClose	boolean	true	우편번호 검색 완료시 자동 닫힘 여부입니다. 주소를 선택하면 팝업창이 닫힙니다.

기타 Daum 우편번호 생성자 속성들을 동일한 이름으로 props를 전달할 수 있습니다. 속성값에 대해서는 Daum 우편번호 서비스 가이드를 참고해주세요.

안내

react-daum-postcode는 Daum 우편번호 서비스와 독립적으로 제작된 패키지입니다. React환경에서 발생하는 react-daum-postcode의 버그는 패키지 레포지터리의 이슈트래커에 말씀해주세요. 만약 Daum 우편번호 서비스 자체의 문제라고 생각하신다면, 다음 우편번호 서비스의 FAQ와 이슈트래커를 참조해주세요.