AddressInput

Code

import { AddressInput, type Address } from "@fadymondy/nasaq/web";import { useState } from "react";export function Delivery() {  const [address, setAddress] = useState<Address>({ street: "" });  return <AddressInput value={address} onValueChange={setAddress} />;}

Forms · beta

Live examples and controls: AddressInput in the lab.

InstallCopy Anchor Link

npx shadcn@latest add https://docs.nasaqui.com/r/address-input.json

One form for a postal address. Country, city and area are comboboxes that cascade: city stays disabled until a country is chosen, area until a city is chosen, and choosing a new parent clears the children. Each list is searchable by its English or Arabic name. Below them are street, building, floor, apartment, landmark and postal code fields, and a PhoneInput whose value is E.164. The value is a plain snake_case object (Address) that can be posted to an API as it is.

Places are loaded through a LocationsDataSource. The default is the CircleXO hub public locations API; pass your own object to use another API or a static list. There is no map: lat and lng are part of the type and pass through untouched, but the component never sets them.

When to useCopy Anchor Link

• Checkout, delivery, billing and profile forms in the Gulf and Arab world, where a place has an English and an Arabic name.
• Any form that must store country, city and area as ids from one reference list.

When not to useCopy Anchor Link

• A single country field: use CountrySelect.
• Free-text addresses with no reference data: use Input and Textarea.
• Picking a point on a map: Nasaq has no map component.

ImportCopy Anchor Link

import { AddressInput, createHubLocationsDataSource, type Address } from "@fadymondy/nasaq/web";
// inside this monorepo: "@nasaq/web"

Quick startCopy Anchor Link

import { AddressInput, type Address } from "@fadymondy/nasaq/web";
import { useState } from "react";

export function Delivery() {
  const [address, setAddress] = useState<Address>({ street: "" });
  return <AddressInput value={address} onValueChange={setAddress} />;
}

AnatomyCopy Anchor Link

AddressInput                    div                      data-slot="address-input"
├─ country                      Field + Combobox         data-slot="address-input-country"
├─ city                         Field + Combobox         data-slot="address-input-city"
├─ area                         Field + Combobox         data-slot="address-input-area"
├─ street                       Field + Input            data-slot="address-input-street"
├─ building, floor, apartment   Field + Input            data-slot="address-input-building" / -floor / -apartment
├─ postal code                  Field + Input (ltr)      data-slot="address-input-postal-code"
├─ landmark                     Field + Input            data-slot="address-input-landmark"
└─ phone                        Field + PhoneInput       data-slot="address-input-phone"   (showPhone)

APICopy Anchor Link

AddressInputCopy Anchor Link

AddressCopy Anchor Link

interface Address {
  country_id?: number;
  city_id?: number;
  area_id?: number;
  street: string;
  building?: string;
  floor?: string;
  apartment?: string;
  landmark?: string;
  postal_code?: string;
  lat?: number;   // passed through, never set by the component
  lng?: number;
  phone?: string; // E.164
}

LocationsDataSourceCopy Anchor Link

LocationCountry is { id, iso2, iso3?, name_en, name_ar, phone_code?, emoji?, region?, lat?, lng?, currency_code? }, LocationCity is { id, country_id, name_en, name_ar, lat?, lng?, timezone? }, LocationArea is { id, city_id, name_en, name_ar }. name_en or name_ar may be an empty string; the UI shows the other one.

createHubLocationsDataSource({ baseUrl?, fetch? })Copy Anchor Link

Returns a LocationsDataSource for the CircleXO hub REST API (public, no auth): GET {base}/api/locations/countries, /cities?country_id=, /areas?city_id=, /search?q=&type=&country_id=&city_id=&limit=, each returning { "items": [...] }. Responses are cached in memory per source object; a failed request is not cached.

HelpersCopy Anchor Link

ExamplesCopy Anchor Link

Own data sourceCopy Anchor Link

import { AddressInput, type LocationsDataSource } from "@fadymondy/nasaq/web";

const source: LocationsDataSource = {
  countries: async () => [{ id: 1, iso2: "SA", name_en: "Saudi Arabia", name_ar: "السعودية" }],
  cities: async () => [{ id: 10, country_id: 1, name_en: "Riyadh", name_ar: "الرياض" }],
  areas: async () => [{ id: 100, city_id: 10, name_en: "Olaya", name_ar: "العليا" }],
};

export const Static = () => <AddressInput dataSource={source} />;

Another hub, no phoneCopy Anchor Link

import { AddressInput, createHubLocationsDataSource } from "@fadymondy/nasaq/web";

const staging = createHubLocationsDataSource({ baseUrl: "https://staging.example.com" });

export const Shipping = () => <AddressInput dataSource={staging} showPhone={false} />;

ArabicCopy Anchor Link

import { AddressInput, NasaqProvider } from "@fadymondy/nasaq/web";

export const AddressAr = () => (
  <NasaqProvider locale="ar" target="scope">
    <AddressInput />
  </NasaqProvider>
);

AccessibilityCopy Anchor Link

Every field has a visible FieldLabel. The comboboxes are Base UI comboboxes; the phone field's own country list is named "Country" by PhoneInput. A disabled city or area is a real disabled input, so it leaves the tab order. The empty message of a list reads "Loading...", "Could not load the list." or "No results." as appropriate.

Caller must localise any labels override. Built-in strings come in English and Arabic.

RTL & i18nCopy Anchor Link

• The grid follows dir: in Arabic the first column is at the right.
• Names follow the active language and fall back to the other one when empty (Egyptian cities are Arabic only). Search matches both, folding Arabic letter variants.
• The postal code and phone fields are left to right in every direction.

Styling & tokensCopy Anchor Link

• Fields use the same tokens as Input and Combobox: border-input, bg-card, rounded-control, focus nq-focus, invalid nq-danger.
• Slots: address-input and the address-input-* slots in Anatomy. data-invalid is set on the root when invalid.
• Extend with className; the root is grid sm:grid-cols-2, so className="sm:grid-cols-1" makes a single column. Never override colours with raw hex.

Do / Don'tCopy Anchor Link

• Do create the data source once and reuse it so lists are cached.
• Do validate street (required) and the ids on the server.
• Don't expect a map pin; set lat and lng yourself if you have them.
• Don't point dataSource at an endpoint that returns thousands of areas per city; filtering is client-side.

RelatedCopy Anchor Link

• PhoneInput · CountrySelect · Combobox · Field · CountryFlag

LabCopy Anchor Link

https://nasaq-ui.fadymondy.com/?path=/docs/components-forms-address-input--docs