ZipCodeKR

한국 우편번호 검색 컨트롤 — 읽기전용 입력 필드 + 검색 버튼 구성

개요

Cals ZipCodeKR은 한국 우편번호 검색을 위한 전용 컨트롤입니다. 우편번호 입력 필드는 항상 읽기전용이며, 검색 아이콘 버튼을 클릭하여 주소를 조회합니다. 검색 결과는 콜백을 통해 상위 컴포넌트에 전달됩니다.

주요 특징

• ✅ 읽기전용 입력: 우편번호 값은 검색 결과로만 설정
• ✅ 검색 버튼: 아이콘 버튼으로 주소 검색 팝업 트리거
• ✅ FormItem 래핑: label, required, orientation 등 폼 기능 지원
• ✅ 스타일 오버라이드: backgroundColor, color, border 등 커스터마이징
• ✅ 가시성/비활성: visible, disabled prop
• ✅ 크기: xs ~ xl 5단계 크기 지원

기본 사용

const [zipcode, setZipcode] = useState("")
 
<ZipCodeKR
  value={zipcode}
  placeholder="우편번호를 검색하세요"
  onSearchClick={() => openKakaoPostcode()}
/>

레이블 + 필수 표시

<ZipCodeKR label="우편번호" required placeholder="검색하세요" />

수평 레이아웃

<ZipCodeKR label="우편번호" orientation="horizontal" />

비활성 상태

disabled 시 검색 버튼이 비활성화됩니다. 입력 필드는 항상 읽기전용입니다.

<ZipCodeKR value="06141" disabled />

오류 상태

<ZipCodeKR label="우편번호" required error="우편번호를 입력하세요" />

스타일 오버라이드

<ZipCodeKR
  backgroundColor="#f0fdf4"
  borderColor="#16a34a"
  color="#15803d"
/>

Kakao 주소 검색 연동 예시

import { ZipCodeKR } from "@vortex/ui-cals"
 
function AddressForm() {
  const [zipcode, setZipcode] = useState("")
  const [address, setAddress] = useState("")
 
  const handleSearch = () => {
    new window.kakao.Postcode({
      oncomplete(data) {
        setZipcode(data.zonecode)
        setAddress(data.roadAddress)
      },
    }).open()
  }
 
  return (
    <div className="space-y-2">
      <ZipCodeKR
        label="우편번호"
        value={zipcode}
        onSearchClick={handleSearch}
      />
      <input value={address} readOnly placeholder="도로명 주소" />
    </div>
  )
}

API Reference

Props

Ref

ZipCodeResult

접근성

권장 사항

• ✅ group role 컨테이너로 렌더링됩니다.
• ✅ 검색 버튼에 aria-label이 자동 설정됩니다.
• ✅ disabled 시 검색 버튼에 disabled 속성이 적용됩니다.
• ✅ error 시 input에 aria-invalid 속성이 설정됩니다.

관련 컴포넌트

• Cals LookUp: 범용 조회 컨트롤 (모달 기반)
• Cals Text: 텍스트 입력 컴포넌트