Giriş

Adres formu göründüğünden zordur: il değişince ilçe ve mahalle temizlenmeli, posta kodu kullanıcıya yazdırılmamalı, 72 bin mahalle tek seferde indirilmemeli ve gönderilen adres sunucuda yeniden kontrol edilmelidir. useViraAddress() bunları tek hook ile çözer. Select'leriniz ve stiliniz sizde kalır.

Başlarken

$ pnpm add @virastack/address

{
  "provinceCode": null,
  "province": null,
  "district": null,
  "neighbourhood": null,
  "postalCode": null,
  "postalCodes": []
}

"use client"
 
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>
    </>
  )
}

İl seçilince ilçeler gelir, ilçe seçilince o ilin mahalleleri yüklenir, mahalle seçilince posta kodu value.postalCode alanına düşer. Bir üst seviyeyi değiştirmek altındakileri temizler. Posta kodu yazmak ters yönde çalışır ve select'leri doldurur.

Yukarıdaki demo aynı hook'u shadcn/ui Select ile kullanır; diğer bileşenler için UI kütüphaneleri sayfasına bakın.

Neden ViraStack Address?

• Zincirleme seçim: İl, ilçe, mahalle. Üst seviye değişince alttakiler hem hook'ta hem formda temizlenir.
• İki yönlü posta kodu: Mahalle seçilince kodu gelir, kod yazılınca select'ler dolar: kodun tek mahallesi varsa üçü de, yoksa il ve ilçe. Bkz. posta kodundan adres.
• Tek satır adres: formatAddress seçimi "Alandüzü Mah. Adapazarı/Sakarya" biçimine getirir; istenirse posta koduyla.
• Güncel veri: Veri her ay otomatik bir sistemle PTT'ye karşı kontrol edilir. Bir değişiklik bulunursa yeni bir patch sürümü yayınlanır; API değişmez.
• İsteğe bağlı yükleme: İl ve ilçe adları paketle gelir; bir ilin mahalleleri yalnızca o il seçilince yüklenir. Tipik bir ziyaret yaklaşık 10 kB indirir.
• Headless: Hiçbir şey çizmez. Native select, shadcn/ui, Ant Design veya kendi bileşeninizle çalışır.
• Türkçe farkındalık: Sıralama, harf dönüşümü ve arama İ ile ı'yı doğru işler.
• Sunucuda doğrulama: Client'ın gönderdiği posta koduna güvenilmez; resolveAddress adresi veri setine karşı yeniden kontrol eder, posta kodunu sunucuda türetir ve uymayan bir kodu reddeder.

Karşılaştırma

Karşılaştırılan iki paket veri paketidir: select'leri, zincirlemeyi ve doğrulamayı siz yazarsınız. Fark hook, posta kodu, isteğe bağlı yükleme ve sunucu tarafındadır.

var · kısmi ya da elle · yok. 29 Ekim 2026’da npm paketleri (turkey-neighbourhoods 4.0.3, turkey-location-data 1.1.1) ve @virastack/address yerel derlemesi üzerinden kontrol edildi.

Boyut nasıl ölçüldü: Aynı form (zincirleme il, ilçe ve mahalle select'leri) üç paketle ayrı ayrı yazıldı ve esbuild ile production modunda, minify, tree-shaking ve code splitting açık derlendi. Tablodaki boyut, sayfa ilk açıldığında inen JS'in aynı formun veri paketi olmadan derlenmiş halinden farkının gzip boyutudur; React iki tarafta da olduğu için boyuta dahil edilmez. Address'te bir ilin mahalleleri o il seçilince ayrıca iner: ortanca 4,8 KB, en büyüğü 29,6 KB. turkey-location-data veriyi Node'un fs modülüyle okuduğu için tarayıcı için derlenemez. Sunucu doğrulamasındaki kısmi işaret, adresin dışa aktarılan listelerle elle kontrol edilebildiği anlamına gelir.

Giriş noktaları

Yalnızca kök girişte "use client" vardır. /server ve /data React import etmez; Server Component, Server Action, route handler ve Node betiklerinde çalışır.

Gereksinimler

• Hook için React 18.2+ (React 19 desteklenir). /server ve /data React olmadan çalışır.
• Node.js 20+
• Çalışma zamanı bağımlılığı yok; veri paketin içinde gelir.
• React Hook Form isteğe bağlıdır. Hook ondan hiçbir şey import etmez; formu form seçeneğiyle alır.

Kapsam

• useViraAddress(), React Hook Form ve UI kütüphaneleri
• Sunucu doğrulaması ve veri seti
• Türkçe yardımcılar ve tipler

Kapsam dışı: sokak, bina ve kapı numarası (veri setinde yoktur, serbest metin olarak alın), yurt dışı adresler, harita ve konumdan adres bulma, hazır select bileşeni.