Repository navigation
Phone Field component for Base UI, Radix and React Aria (built on phonefield) #12706
damianricobelli
started this conversation in
Ideas
Replies: 0 comments
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Uh oh!
There was an error while loading. Please reload this page.
Proposal: Phone Field component for Base UI, Radix and React Aria
Hi! I'd like to propose adding a Phone Field component to shadcn/ui. It's built on phonefield, a headless phone input library that I wrote and maintain.
I've already built the component in a fork, following the repo conventions.
CONTRIBUTING.mdasks for new components to start as a discussion, so I'm opening this one to check whether it fits before I open a PR.Branch: https://github.com/damianricobelli/ui/tree/feat/phone-field
Diff against main: main...damianricobelli:ui:feat/phone-field
phonefield: docs and playground · repo · npm
The country picker in the three bases (nova style). They render the same.
React Hook Form example after submitting an incomplete number.
Why
Phone number inputs have come up several times:
phone-inputcomponent based onreact-phone-number-input(closed)react-phone-input-2Today, people either install a third-party component whose styling doesn't match their shadcn setup, or they build their own. Building one well is harder than it looks: you need a searchable country picker, formatting as the user types, validation, E.164 output, paste handling, server-side parsing, and integration with form libraries.
Built on phonefield
phonefield is a composable, accessible, unstyled React phone input for Base UI, Radix UI and React Aria. It uses
libphonenumber-jsfor parsing and formatting. I designed it so a design system like shadcn/ui can own all the markup and styles, while phonefield handles the phone-number logic.One API, three primitive libraries
Each entry point exports the same
PhoneFieldparts and the sameusePhoneField()hook. The value, formatting, validation, FormData and field state work the same in all three. The country picker uses the components of the library you choose and follows that library's composition model:phonefield(Base UI)phonefield/radixphonefield/react-ariaComboboxPopover+ listboxSelect+AutocompleterenderasChildrenderand render propsThe primitive libraries are optional peer dependencies, and each entry point imports only its own library. phonefield's CI tests both ends of every peer range, on React 18 and React 19. MIT licensed, and its only runtime dependency is
libphonenumber-js.What it handles
+44 20 7946 0018selects the United Kingdom and shows020 7946 0018.Cmd/Ctrl+ZandCmd/Ctrl+Shift+Zundo and redo number and country changes.invalidadds an external error, andautoInvalid={false}leaves validation entirely to a form library.isValidisfalsewhen the number belongs to a different country than the selected one.{ countryIso2, countryDialCode, nationalNumber, e164, isValid }.name, the field submits a single FormData entry.fromFormDatarebuilds the value on the server.phonefield/utilsincludesparse,isValid,buildValue,fromFormData,toFormValue,getCountriesandgetExampleNumber, and they run on both the client and the server.countriesand pin entries to the top withpreferredCountries.Intl.DisplayNames, and the picker text can be changed withlabels.data-invalid,data-focused,data-filled,data-disabledand more, so the field can be styled with Tailwind variants.onFocusandonBlurfire for the whole field. Moving between the input, the country trigger and the picker doesn't count as blur, so form libraries don't mark the field as touched too early.Features added for shadcn/ui
I made the latest releases so the component could be built cleanly here, without workarounds in the component code:
data-slotyou pass takes precedence, soInputGroupcan find itsinput-group-control;onFocusandonBlur;autoInvalid;isValidandparseaccept the partial value that forms hold before the user types.focusInputOnSelectturns this off.Why not wrap an existing phone input?
#2694 wrapped
react-phone-number-input, which renders its own markup. Because phonefield is headless, the shadcn component is made of shadcn's own pieces:InputGroup;InputGroupButton;That's why it looks and behaves like the rest of the library in every style.
The hook and helpers are still available
The shadcn component only arranges phonefield's parts, so nothing from phonefield is hidden from developers:
usePhoneField()works inside<PhoneField>. It returnsvalue,state,country,countries,setCountry,setNumberandfocusInput, which is enough to build custom parts such as a native<select>country picker, a drawer, or a validity indicator. The docs include a "Custom Parts" example that adds anInputGroupAddonshowing a check mark once the number is valid. It works the same in all three bases.phonefield/utilsworks anywhere, including on the server. The docs and examples already usegetExampleNumberfor placeholders,isValidin the React Hook Form, TanStack Form and Formisch schemas, andfromFormDatafor server actions.When phonefield adds something new, such as
focusInput()in 2.3, developers can use it without any change to the shadcn component.What it looks like
How it fits the existing system
radix,baseandaria.InputGroup,InputGroupButtonandInputGroupInput, plus the existingcn-combobox-*,cn-menu-targetandcn-menu-translucentstyle classes. No newcn-*classes or style CSS were added.What's included
phone-fieldregistry items forradix,baseandaria, installable withnpx shadcn@latest add phone-fieldusePhoneFieldhook and thephonefield/utilshelpers./createpreviewAccessibility
FieldLabel(viaid) or fromaria-label.Enter.Escapereturns focus to the trigger.aria-invalidwhile the field is invalid.One difference between bases
When the picker is closed by clicking outside it, focus ends up in a different place depending on the base:
body.This is Radix's default for non-modal popovers. After an outside interaction,
onCloseAutoFocusintentionally skips returning focus to the trigger. The existing RadixPopoverin this repo behaves the same way: open it, click outside, and focus lands onbody.I kept the Radix default instead of overriding it, so the phone field behaves like the other Radix popovers in shadcn/ui. For that reason, the docs only describe what's the same in all three bases:
Escapereturns focus to the trigger. If you'd prefer the Radix version to match Base UI here, it's a small change.Verification
pnpm registry:build,pnpm check, andnext buildforapps/v4all pass.shadcn add phone-field) in fresh apps for each base, and they type-check and build.On depending on phonefield
I understand that adding a dependency on a library with one maintainer is a real concern. I'm committed to maintaining phonefield and keeping it compatible with shadcn/ui. If something here needs to change, I'd rather change it in phonefield than work around it in the component. That's what I did for 2.2 and 2.3.
Questions for the maintainers
@phonefield)?phone-fieldto match phonefield's API (PhoneField,PhoneFieldInput). Wouldphone-inputbe easier to find? Any preference?If this direction works for you, I'll open the PR from the branch above. Thanks for taking a look!
All reactions