Feature Request: Lightweight PhoneInput with Country Code Selector

[TheLostByGass]

Hi 👋
First contribution to the Chakra ecosystem, so apologies if I'm framing anything wrong. I was redirected here from a discussion on the Chakra UI repo (chakra-ui/chakra-ui#10704), where the suggestion was that this belongs in zag-js if it ships with logic.

Why

There's currently no framework-agnostic state machine for the phone number with country selector pattern — a very common shape in sign-up flows, account settings, and contact forms. Today, consumers either:

• Reach for @zag-js/combobox and rebuild the country/dial-code/value-composition logic on top, or
• Ship a number-input, which is the wrong primitive — phone numbers are identifiers, not numeric quantities.

A documented zag-js answer (machine or recipe) would close this gap.

Scope I'd propose for v1

Intentionally narrow:

• Country selection (with keyboard nav + type-to-search, parity with combobox)
• Dial-code display derived from selected country
• type="tel" input for the national number
• Derived value: { country, dialCode, nationalNumber, internationalValue }
• Hidden input for native form submission
• Field integration (disabled / invalid / required from parent field)

Explicitly out of scope for v1:

• Auto-formatting / masking
• Country-specific validation
• libphonenumber integration
• Parsing guarantees beyond dialCode + nationalNumber

The main design question

Looking at @zag-js/combobox, it already covers most of what's needed: trigger, listbox, items, keyboard navigation, type-to search, focus management, ARIA wiring. The differences from combobox are essentially:

1. A second input (type="tel") bound to the same root, exposing a nationalNumber part of the value.
2. A derived internationalValue from dialCode + nationalNumber.
3. A canonical "country" item shape (iso, name, dialCode, optional flag).

So my actual question: does this want to be a dedicated @zag-js/phone-input machine, or a recipe/example that composes combobox + a controlled tel input + a derived-value hook? I'm happy to take either direction — I just want to align on the right boundary before writing it.

Proposed shape (if a dedicated machine)

root, label, control, trigger, positioner, content,
list, item, itemText, itemIndicator,
input, hiddenInput, indicatorGroup, clearTrigger

Machine context (sketch):

interface PhoneInputProps {
  id?: string
  ids?: Partial<Record<Part, string>>
  // collection of countries (consumer-provided)
  collection: Collection<CountryItem>
  // controlled
  country?: string            // iso
  nationalNumber?: string
  open?: boolean
  // uncontrolled defaults
  defaultCountry?: string
  defaultNationalNumber?: string
  defaultOpen?: boolean
  // form
  name?: string
  form?: string
  required?: boolean
  disabled?: boolean
  invalid?: boolean
  readOnly?: boolean
  // callbacks
  onValueChange?: (details: ValueChangeDetails) => void
  onOpenChange?: (details: OpenChangeDetails) => void
  onCountryChange?: (details: CountryChangeDetails) => void
}

interface ValueChangeDetails {
  country: string
  dialCode: string
  nationalNumber: string
  internationalValue: string   // dialCode + nationalNumber
}

interface CountryItem {
  iso: string
  name: string
  dialCode: string
  // anything else (flag, alt names) is consumer-defined
}

Consumer-side example (framework-agnostic, Ark UI binding for illustration):

<PhoneInput.Root
  collection={countries}
  defaultCountry="US"
  onValueChange={(d) => console.log(d)}
>
  <PhoneInput.Label>Phone number</PhoneInput.Label>
  <PhoneInput.Control>
    <PhoneInput.Trigger>
      <PhoneInput.ValueText />        {/* e.g. "+1" */}
      <PhoneInput.Indicator />
    </PhoneInput.Trigger>
    <PhoneInput.Input />              {/* type="tel" */}
    <PhoneInput.HiddenInput />        {/* submits internationalValue */}
  </PhoneInput.Control>

  <PhoneInput.Positioner>
    <PhoneInput.Content>
      <PhoneInput.List>
        {countries.items.map((c) => (
          <PhoneInput.Item key={c.iso} item={c}>
            <PhoneInput.ItemText>{c.name} ({c.dialCode})</PhoneInput.ItemText>
            <PhoneInput.ItemIndicator />
          </PhoneInput.Item>
        ))}
      </PhoneInput.List>
    </PhoneInput.Content>
  </PhoneInput.Positioner>
</PhoneInput.Root>

Interaction & accessibility expectations

• Trigger: role="combobox" or button + aria-haspopup="listbox", aria-expanded, aria-controls on the list
• List: role="listbox" with aria-activedescendant tracking the highlighted country
• Items: role="option" with aria-selected for the current country
• Keyboard: ↑/↓ to navigate, Home/End, Enter to select, Esc to close + return focus to trigger, type-to-search by country name and dial code
• Focus: focus returns to the tel input after selecting a country (so the user can keep typing)
• Field integration: respects ancestor field machine for disabled/invalid/required/readOnly (same pattern as the existing
  input-style machines)

Open questions

1. Composition vs dedicated machine — as above. Strong preference for whichever the team thinks is the right boundary.
2. Country dataset — assumption is consumer-provided collection, matching the rest of zag-js. Worth confirming.
3. Flags — out of the machine entirely; the consumer renders whatever they want inside Item / ValueText.
4. Formatting boundary — v1 leaves nationalNumber as the raw typed string. Should we leave a hook for a future format/parse
   extension, or keep that purely consumer-side?
5. internationalValue shape — naive concatenation (dialCode + nationalNumber) for v1, with the understanding that this is not
   E.164-correct in edge cases. Acceptable for v1, or should we punt on the derived value entirely and let consumers compute it?

Prior art / references

• @zag-js/combobox — closest existing machine; phone-input shares ~80% of its interaction surface

• Flowbite phone input — UX reference for the pattern

• Lightweight PhoneInput with Country Code Selector chakra-ui#10704 — original discussion that pointed here

  Happy to take this to a spike (machine + tests + Ark binding) once we agree on the shape. This is my first OSS contribution, so guidance on the boundary and any zag-js conventions I should follow is very welcome 🙏
  Plus, I'm not an engineer hence I'm using coding agents for the proposal and the spike 🤖