Convenience Store Pickup

The "pick up at a convenience store" flow that shows up in almost every Taiwanese e-commerce checkout, packaged as a self-contained stepper panel: step one picks the chain with color-swatch chips, step two derives city and district dropdowns from the store data, and step three lets you choose from a searchable list — each row shows the address, opening hours, a 24-hour badge and (optionally) a distance label. Once a store is chosen the panel collapses into a summary card (chain swatch + store name + address + a "Change" button) and calls onSelect(store). Steps slide horizontally, list items stagger in and the selected item gets a check mark; it supports controlled value and uncontrolled defaultValue, an isLoading skeleton and fully overridable copy. The component ships no real brand logos or names — chains and stores always come in through props.

Playground

Tune the props live — the code snippet updates as you go, so you can dial in the look you want before copying it.

<ConvenienceStorePickup />

Installation

Usage

import {
  ConvenienceStorePickup,
  type PickupChain,
  type PickupStore,
} from "@/components/ui/convenience-store-pickup";

// Chains and stores come from your API; the values below are fictional
const chains: PickupChain[] = [
  { id: "sudah", name: "速達超商", color: "#e8541e" },
  { id: "neighbor", name: "好鄰居便利店", color: "#2e7d32" },
];

const stores: PickupStore[] = [
  {
    id: "sd-001",
    chainId: "sudah",
    name: "大安樂活門市",
    address: "臺北市大安區樂活路 12 號",
    city: "臺北市",
    district: "大安區",
    open24h: true,
    distanceText: "350 公尺",
  },
  {
    id: "nb-001",
    chainId: "neighbor",
    name: "大安木棉店",
    address: "臺北市大安區木棉巷 6 號",
    city: "臺北市",
    district: "大安區",
    hours: "07:00–22:30",
  },
];

// Controlled: keep the store id in your checkout form state
<ConvenienceStorePickup
  chains={chains}
  stores={stores}
  value={form.pickupStoreId}
  onChange={(id) => setForm({ ...form, pickupStoreId: id })}
  onSelect={(store) => console.log("pickup store", store.name, store.address)}
/>

// Uncontrolled: you only care about the final pick
<ConvenienceStorePickup
  chains={chains}
  stores={stores}
  defaultValue="sd-001"
  onSelect={(store) => console.log(store.id)}
  compact
/>

Props

PickupChain

PickupStore

ConvenienceStorePickupLabels

filterPickupStores(stores, { chainId, city, district, query }) is also a named export — the same filter the component uses internally (the query matches store name and address, case-insensitively), handy for counting stores at the form layer or pre-filtering on the server.

How it works

• Three-step navigation: the step bar lets you jump back to any completed step; steps whose prerequisites are not met yet (e.g. picking a store before a chain) are disabled. Switching chains clears the chosen city/district, staying on the same chain keeps them. Choosing a district advances to the store list automatically; when you return to step two a "View stores" button takes you forward again.
• Options derived from data: cities and districts are de-duplicated from that chain's stores, preserving the order you passed in (north to south, say) — no separate administrative-region table to maintain.
• Collapses into a summary card: after a store is picked the stepper collapses and only the summary card remains; "Change" re-opens it straight at that store's list with the store pre-set as the active row. In controlled mode, setting value back to null from outside re-opens the panel too.
• Distance text is up to you: the component does no geolocation or distance math, it only renders distanceText; showDistance={false} hides it entirely.
• Motion: direction-aware horizontal slide between steps (forward slides left, back slides right), the first 8 list rows stagger in, the check mark uses a spring scale and the summary card expands by height.

Accessibility

• The step bar is an ol list; the current step carries aria-current="step" and steps whose prerequisites are unmet are disabled
• Chain chips are aria-pressed buttons inside a role="group"; city/district use native select elements (with label), so mobile devices open the system picker
• The store list is a focusable role="listbox" with role="option" rows and aria-selected, pointing at the current row via aria-activedescendant; ↑/↓/Home/End move, Enter/Space selects, ↓ in the search input jumps straight into the list and Enter selects the current row (never misfires while a CJK IME is composing)
• After a store is chosen focus moves to the summary card's "Change" button; after "Change" focus returns to the search input, so the keyboard flow never breaks; the store count is announced via aria-live="polite"
• The isLoading skeleton announces itself with role="status", aria-busy and sr-only text
• When the user has "reduce motion" enabled at the system level, step changes become a plain cross-fade, list rows no longer stagger, and the check mark and summary card drop their scale/height animations, leaving instant switches only