ViraStack Address: Türkiye Adresleri için React Hook'u

Türkiye'de bir adres formu yazdıysan bilirsin: il seçilince ilçeler, ilçe seçilince mahalleler gelmeli; il değişince alttakiler temizlenmeli, yoksa formda Sakarya'nın altında Kadıköy kalıyor. Posta kodunu kullanıcıya yazdırırsan yanlış girilir. Verisi de ayrı bir dert: 81 il, 973 ilçe ve 72 binden fazla mahalle.

ViraStack Address (@virastack/address) bunları tek bir React hook'unda çözüyor.

Ne Yapıyor?

• Zincirleme seçim: İl, ilçe ve mahalle sırayla geliyor; üst seviye değişince alttakiler temizleniyor.
• Posta kodu türetiliyor: Mahalle seçilince posta kodu kendiliğinden doluyor. Tersi de çalışıyor: posta kodunu yazınca il ve ilçe doluyor.
• Headless: Bileşen ya da stil yok; düz <select>, shadcn/ui ya da Ant Design ile çalışıyor.
• Hafif veri: PTT verisi paketin içinde. İl ve ilçe adları 5 kB; mahalleler yalnızca seçilen il için indiriliyor, tipik bir ziyarette toplam 10 kB civarı.
• Sunucuda doğrulama: Gönderilen adres sunucuda tekrar kontrol ediliyor, posta kodu orada türetiliyor.

Dene

İl, ilçe ve mahalle seç ya da posta kodu kutusuna 54100 yaz. Altında hook'un döndürdüğü value ve tek satırlık adres görünüyor.

Kurulum

pnpm add @virastack/address

Kullanım

import { useViraAddress } from "@virastack/address"
 
export function AddressFields() {
  const { getProvinceProps, getDistrictProps, getNeighbourhoodProps, value } = useViraAddress()
 
  return (
    <>
      <select {...getProvinceProps()} />
      <select {...getDistrictProps()} />
      <select {...getNeighbourhoodProps()} />
      <p>Posta kodu: {value.postalCode ?? "—"}</p>
    </>
  )
}

Sakarya, Adapazarı ve Alandüzü Mahallesi seçilince value şu oluyor:

{
  provinceCode: "54",
  province: "SAKARYA",
  district: "ADAPAZARI",
  neighbourhood: "ALANDÜZÜ MAH.",
  postalCode: "54100",
  postalCodes: ["54100"]
}

React Hook Form kullanıyorsan formu ver, seçimler forma kendiliğinden yazılsın: useViraAddress({ form }). Alanlar varsayılan olarak province, district, neighbourhood ve postalCode; farklıysa names ile verebilirsin.

Sunucuda doğrulama

İstemci istediği posta kodunu gönderebilir, o yüzden adresi sunucuda tekrar çöz:

import { resolveAddress } from "@virastack/address/server"
 
await resolveAddress({ province: "sakarya", district: "adapazarı", neighbourhood: "alandüzü mah." })
// { ok: true, value: { province: "SAKARYA", district: "ADAPAZARI", postalCode: "54100", … }, issues: [] }
 
await resolveAddress({ province: 54, district: "kadıköy", neighbourhood: "caferağa mah." })
// { ok: false, issues: [{ level: "district", reason: "unknown" }], … }

UI kütüphanesi örnekleri, posta kodundan arama, formatAddress ve veri seti ayrıntıları virastack.com/address dokümanında, kaynak kod github.com/virastack/form deposunda. Mask ve Password ile aynı formda kullanmak için ViraStack Mask yazısına bakabilirsin.