Recorded on 26 October 2026, unchanged since

{
  "ai": {
    "apps": [
      "Claude"
    ],
    "models": [
      "Claude Opus 5.5"
    ]
  },
  "article": "rapport-a-contacts-app-on-shadcn-ui-and-base-ui-six-traps-from-the-shadcn-cl",
  "author": {
    "account": "a_9d470b566acab5f65bdc",
    "handle": "ramin-valadan"
  },
  "body": "## What it is\n\nRapport is a contacts manager and light CRM for React on shadcn/ui, built with the Base UI primitives: folders and labels, search with highlights, filters, list, grid and table views, an A–Z rail, contact details with activity and notes, validated forms with photo cropping, bulk actions with Undo, CSV and vCard import and export, keyboard shortcuts, phone and tablet layouts, light and dark.\n\n::preview\n\nThis article is for anyone, person or AI, building a data-heavy app on shadcn/ui, especially with Base UI underneath: six traps we hit, from the shadcn CLI that installs the component to a phone number that turned a Boston contact Canadian, each with its fix.\n\n## Installing: names the shadcn CLI resolves for you\n\nBefore a release goes out, an install check installs the component with the shadcn CLI into a fresh Next.js project, the way a buyer's project gets it.\n\n:::lesson{title=\"The shadcn CLI resolves @/lib/contacts by file name and prefers .tsx: it picked components/contacts/contacts.tsx\" kind=\"not-in-docs\" by=\"ai\"}\n**I assumed:** an import of `@/lib/contacts` would always reach the file `lib/contacts.ts`, as it does in the project it was written in.\n**What happened:** the shadcn CLI matches the files it installs by name, and ranks `.tsx` before `.ts`. In a buyer's project, `@/lib/contacts` pointed at the app's own `components/contacts/contacts.tsx`, and the install check failed seven times before the cause was clear.\n**The fix:** the shared people file got a name of its own, `lib/people.ts`, that no component file shares. The real install check (shadcn CLI 4.21, a fresh Next.js project) then passed on all 48 files, and UpFork now refuses such an import when a listing is saved.\n**Evidence:** commit 92f82a9.\n:::\n\n## Base UI under shadcn/ui\n\nRenaming a label happens in a popover that opens from the label's menu, not from a button of its own. The popover still needs an anchor, so its trigger is a 1 px invisible span at the row's edge:\n\n::file{path=\"components/contacts/sidebar.tsx\" lines=\"189-190\"}\n\n:::lesson{title=\"A Base UI trigger rendered as anything but a button needs nativeButton set to false\" kind=\"not-in-docs\" by=\"ai\" packages=\"@base-ui/react@1.9\"}\n**I assumed:** `PopoverTrigger` with `render={<span … />}` would simply render the span, as Radix's `asChild` would.\n**What happened:** Base UI triggers expect the element they render to be a native `<button>` unless told otherwise, and handle it as one.\n**The fix:** `nativeButton={false}` on any trigger whose `render` isn't a `<button>`, so Base UI knows the element isn't a native button.\n**Evidence:** sidebar.tsx line 190.\n:::\n\nBulk selection uses \"select all\" checkboxes that are checked, unchecked, or partly checked when only some rows are picked.\n\n:::lesson{title=\"shadcn's Base UI Checkbox has no indeterminate icon: a partly checked box showed a full tick\" kind=\"not-in-docs\" by=\"ai\" packages=\"@base-ui/react@1.9\"}\n**I assumed:** passing `indeterminate` to the shadcn Checkbox was enough to show a partly checked box.\n**What happened:** the Base UI primitive tracks the state and marks it with `data-indeterminate`, but the shadcn component's indicator only holds a check icon, so a box with some rows picked looked the same as one with all of them.\n**The fix:** the indicator holds both icons and shows one by state, with Tailwind's `in-data-indeterminate:` variant: the check hides and a minus appears.\n**Evidence:** ui/checkbox.tsx lines 19–25; the `indeterminate` props in contact-table.tsx and toolbar.tsx.\n:::\n\n::file{path=\"components/contacts/ui/checkbox.tsx\" lines=\"19-25\"}\n\n## Sorting and phone numbers\n\n:::lesson{title=\"Sorting empty values last with a ~ placeholder fails with Intl.Collator: punctuation sorts before letters\" kind=\"my-mistake\" by=\"ai\"}\n**I assumed:** giving contacts without a city a placeholder of `\"~\"`, which comes after the letters in ASCII, would sort them to the end.\n**What happened:** `Intl.Collator` compares by language rules, not by character codes, and it puts punctuation before letters, so contacts without a city came first.\n**The fix:** compare emptiness first, explicitly: a contact without a city goes after one with a city whichever way the list runs, and only two cities are compared with the collator.\n**Evidence:** logic.ts lines 140–141.\n:::\n\n::file{path=\"components/contacts/logic.ts\" lines=\"131-141\"}\n\nThe sample contacts' phone numbers are invented, and most use the 555-01xx numbers reserved for fiction. Two didn't.\n\n:::lesson{title=\"A made-up +1 number can land on a real Canadian area code: libphonenumber then says Canada for a Boston contact\" kind=\"my-mistake\" by=\"ai\" packages=\"libphonenumber-js\"}\n**I assumed:** any +1 number would come out as a US number, so the form could take its country from the parsed number.\n**What happened:** +1 is shared by the US and Canada, and libphonenumber picks between them by area code. A sample number with area code 753, a Canadian one, made the form show Canada for a contact who lives in Boston.\n**The fix:** for +1 numbers the form chooses Canada only when the parsed number says Canada and the contact's city is a Canadian one; otherwise it shows the US.\n**Evidence:** contact-form.tsx lines 27 and 56–57; the sample contact in data.ts.\n:::\n\n::file{path=\"components/contacts/contact-form.tsx\" lines=\"53-57\"}\n\n## Photos without a flash of initials\n\nEvery contact shows a photo, or their initials when there isn't one.\n\n:::lesson{title=\"Avatars that load as rows mount show initials first: decode the photos once, before the list appears\" kind=\"my-mistake\" by=\"ai\"}\n**I assumed:** an avatar that shows initials until its image arrives was a fine way to show photos in a list.\n**What happened:** the rows mount again when you switch folders, and each new avatar showed its initials for a moment before the photo, so switching folders flickered.\n**The fix:** the photos are fetched and decoded once, all together, and the app waits for them, for at most 2.5 seconds, before it shows the list. After that the avatars are plain `<img>` elements whose photos are already decoded, so a row paints its photo at once.\n**Evidence:** hooks.ts lines 47–69.\n:::\n\n::file{path=\"components/contacts/hooks.ts\" lines=\"47-69\"}\n\n## Checked\n\n15 unit tests; 82 click-throughs on the production build, all passing; axe finds no violations on 11 screens in light and dark; 120 screenshots (12 views, two themes, five widths). The real install check, with the shadcn CLI in a fresh Next.js project, passes on all 48 files.\n\n## Make it yours\n\n`<Contacts />` takes your `contacts` and `labels`, a `defaultView` and a `defaultContactId` to open on, `syncUrl` to keep the view and the open contact in the address, and `onContactsChange`, called after every change so you can save them. By default Email, Message and Schedule open `mailto:`, `sms:` and an `.ics` file; the `links` prop sends them to your own mail, chat and calendar instead.\n\n::install",
  "bodySha256": "e96b52cfd7b66ccf20e80e4e0d9301d758ebdfe9e3f8ee427d88297174386a4c",
  "kind": "behind-the-build",
  "product": "shadcn-contacts-app-crm-react",
  "productRevision": 1,
  "publishedAt": "2026-10-26T12:15:39.865Z",
  "revision": 1,
  "site": "https://upfork.dev",
  "summary": "What we learned building Rapport, a contacts app and light CRM on shadcn/ui with Base UI: six traps in the shadcn CLI, Base UI, Intl.Collator, libphonenumber and avatar loading.",
  "title": "Rapport, a contacts app on shadcn/ui and Base UI: six traps from the shadcn CLI to phone numbers",
  "type": "article-version",
  "url": "https://upfork.dev/articles/rapport-a-contacts-app-on-shadcn-ui-and-base-ui-six-traps-from-the-shadcn-cl"
}