useViraAddress()

Hook API'si: seçenekler, dönüş değeri, value nesnesi ve kendi veri kaynağınız.

Temel kullanım

Hook üç liste ve üç setter döndürür. Her liste { value, label } biçimindedir: value veri setindeki ham adı (FATİH), label başlık biçimini (Fatih) taşır. İl listesinde value plaka kodudur ("34").

const {
  provinces, districts, neighbourhoods,
  setProvince, setDistrict, setNeighbourhood,
  value, loading,
} = useViraAddress()
 
return (
  <>
    <select
      value={value.provinceCode ?? ""}
      onChange={(e) => setProvince(e.target.value)}
    >
      <option value="">İl seçiniz</option>
      {provinces.map((p) => (
        <option key={p.value} value={p.value}>{p.label}</option>
      ))}
    </select>
 
    <select
      value={value.district ?? ""}
      onChange={(e) => setDistrict(e.target.value)}
      disabled={!districts.length}
    >
      <option value="">İlçe seçiniz</option>
      {districts.map((d) => (
        <option key={d.value} value={d.value}>{d.label}</option>
      ))}
    </select>
 
    <select
      value={value.neighbourhood ?? ""}
      onChange={(e) => setNeighbourhood(e.target.value)}
      disabled={!neighbourhoods.length}
    >
      <option value="">
        {loading.neighbourhoods ? "Yükleniyor…" : "Mahalle seçiniz"}
      </option>
      {neighbourhoods.map((n) => (
        <option key={n.value} value={n.value}>{n.label}</option>
      ))}
    </select>
  </>
)

Elle bağlamak istemiyorsanız aynı şeyi prop getter'lar tek satırda yapar. setProvince plaka kodunu sayı veya metin olarak alır.

value

Formun ihtiyaç duyduğu her şey tek nesnededir:

{
  provinceCode: "34",       // plaka kodu, string olarak
  province: "İSTANBUL",
  district: "FATİH",
  neighbourhood: "AKSARAY MAH.",
  postalCode: "34096",      // mahallenin ilk posta kodu ya da yazılan kod
  postalCodes: ["34096"],   // hepsi; birkaç yüz mahallede birden fazla
}

Seçilmemiş seviyeler null, postalCodes boş dizidir. Adlar veri setindeki gibi büyük harflidir; ekranda göstermek için listelerdeki label alanını ya da formatName kullanın.

Seçenekler

Seçenek	Varsayılan	Ne yapar
`source`	paketteki veri seti	Listelerin geldiği yer. Test fixture'ı ya da kendi API'niz için değiştirin.
`defaultValue`	—	`{ provinceCode, district, neighbourhood }` ile başlangıç. `form` verildiyse ve bu boşsa formdaki adresten okunur.
`formatLabel`	`formatName`	Ham adı etikete çevirir; ikinci parametre seviyedir. `(name) => name` büyük harfi korur.
`onChange`	—	Her değişiklikte `value` ile çağrılır; ilk render'da çağrılmaz.
`form`	—	Senkron tutulacak form, örneğin React Hook Form'un `useForm()` sonucu.
`names`	`province`, `district`, `neighbourhood`, `postalCode`	Formdaki ve prop getter'ların döndürdüğü input'lardaki alan adları. `provinceCode` yalnızca adı verilirse yazılır.
`shouldValidate`	`true`	Adres değiştikçe form alanlarını yeniden doğrular.

form, names ve shouldValidate React Hook Form sayfasında ayrıntılı anlatılır.

Dönüş değeri

Alan	Açıklama
`value`	Seçili adres; yukarıdaki nesne.
`provinces, districts, neighbourhoods`	Select'e hazır `{ value, label }` listeleri. Mahalle seçenekleri ayrıca `postalCode` ve `postalCodes` taşır.
`setProvince(code), setDistrict(name), setNeighbourhood(name)`	Seçim yapar; `null` veya `""` seviyeyi temizler. Üst seviye alttakileri temizler.
`setPostalCode(code)`	Posta kodundan adresi doldurur; `"exact" \| "partial" \| "unknown"` ile çözülür. Bkz. posta kodundan adres.
`postalCodeStatus`	Son posta kodunun ne bulduğu; etkin bir arama yoksa `null`.
`reset()`	Her seviyeyi temizler.
`loading.neighbourhoods`	Seçili ilin mahalleleri yüklenirken `true`.
`error`	Son yükleme hatası. Başka bir il seçilince temizlenir; başarısız il sonra tekrar seçilirse yükleme yeniden denenir.
`getProvinceProps(), getDistrictProps(), getNeighbourhoodProps()`	Düz bir `<select>`'e yayılan prop'lar; `disabled` zincirden hesaplanır. Diğer bileşenler için `as` ile biçim seçilir.
`getPostalCodeProps()`	Türetilen posta kodu için gizli bir input.
`getPostalCodeInputProps()`	Kullanıcının posta kodu yazabildiği input; seçimden türetilen kodu da gösterir.

Kendi veri kaynağınız

Varsayılan kaynak paketteki veri setidir. Testlerde küçük bir fixture kullanmak ya da listeleri kendi API'nizden okumak için source verin:

import { useViraAddress, type AddressSource } from "@virastack/address"
 
const aksaray = {
  name: "AKSARAY MAH.",
  postalCode: "34096",
  postalCodes: ["34096"],
}
 
const source: AddressSource = {
  provinces: [
    { code: 34, name: "İSTANBUL", districts: ["FATİH", "KADIKÖY"] },
  ],
  neighbourhoods: async (code) => new Map([["FATİH", [aksaray]]]),
}
 
const address = useViraAddress({ source })

Hook mahalleleri yalnızca il değiştiğinde okur; her render'da yeni bir source nesnesi vermek yüklemeyi tekrarlatmaz. Yalnızca mahallelerin nereden geldiğini değiştirmek istiyorsanız setLoader daha kısadır; bkz. veri seti.