A full-screen map of listings with a floating listings panel, filters and a property detail panel, built on
shadcn/ui (Radix), Tailwind CSS 4, MapLibre GL in the mapcn way,
supercluster, TanStack Virtual, Embla, vaul, react-hook-form + zod, motion and sonner. Light and dark,
phone to wide desktop.
pnpm install
pnpm dev # http://localhost:5301
pnpm build && pnpm start # review build on http://localhost:5300
import { PropertyExplorer } from "@/components/explorer/explorer"
export default function Page() {
return (
<main className="h-dvh">
<PropertyExplorer brand="Roofline" onRequestVisit={async (request) => api.post("/visits", request)} />
</main>
)
}
| Prop | Default | |
|---|
listings | the 60 demo listings | your data, ListingSeed[] (see types.ts); reviews, nearby places and price history are derived |
brand | "Roofline" | the wordmark and the agency name on agent cards |
storagePrefix | "roofline" | localStorage keys: ${prefix}-favourites, ${prefix}-public-filters (versioned, migrated) |
assetBase | "" | prefix for the photos under /images (a CDN) |
stadiaApiKey | — | the Outdoors style outside localhost (Stadia Maps); without it Outdoors falls back to Default |
syncUrl | true | mirror filters, the open property and the camera in the address bar |
dashboardHref, buyHref | /agent/dashboard, /pricing | the footer buttons |
onRequestVisit | — | receives a validated visit request; the success card shows when it resolves |
toaster | true | mounts a sonner <Toaster />; pass false if your app has one |
| initialFilters | — | filters to open with ({ city: "Dubai" } for a /rent/dubai page), over saved ones; the address bar wins |
| initialPropertyId | — | a property to open on load |
The explorer fills its parent: give the parent a height. Its layout follows its own width (under 768 px it is the
phone layout with a bottom sheet), so it also works inside a page section.
What is in it
- Map: CARTO Positron / Dark Matter that follows the theme, OpenFreeMap Streets and Stadia Outdoors with real
previews in the style menu, a loading bar, and a fallback to Default when a style stays blank; clusters with a type
ring and breakdown, spiderfied listings that share an address, 32 px type circles below zoom 11 and price pills from
it, a pulsing halo on the selected listing, muted pills for viewed ones, hover previews, named and focusable markers,
fit-to-results that respects the floating panels, fly-to with panel-aware offsets, "Search this area" and "Search as
I move the map", 3D buildings, my location with sort by distance, a legend that filters, themed credits.
- Listings panel: context title ("Villas · Dubai") with an animated, announced count, sort, card and list views,
favourites, filters badge, a search combobox (cities, neighbourhoods, properties, recent searches,
/), quick chips,
removable active filters, a virtualized list with photo carousels (only the first photo loads up front), hover sync
with the map, keyboard navigation, skeletons, an empty state with ways out, collapse to a rail, drag to resize.
- Filters: docked beside the panel on wide screens, over it below; sort, availability (switch and status kept in
sync), type tiles with counts, a price histogram with a two-thumb slider and exact inputs, bedrooms, bathrooms,
furnishing, parking, rating, amenities, changed-section dots, a live "Show N properties", Save search.
- Property detail: gallery with thumbnails, a full-screen lightbox (keys, swipe, zoom) and "Show all photos";
price with savings, deposit, move-in cost and a six-month trend; key facts with sq ft / m²; Overview, Location (mini
map and walking times), Reviews (breakdown and reviewer photos) and Similar tabs; agent card with real listing count,
call, email, message and "View listings"; Request a Visit (zod validation, past and booked days disabled, time slots,
success card with an
.ics); previous / next, share, save, full-listing view; a sticky action bar.
- Also: compare two or three saved properties, a keyboard cheat sheet (
?), toasts with Undo, URL state,
reduced motion everywhere, a phone layout with a snapping bottom sheet and a card row that follows the markers.
Where things live
| Path | |
|---|
components/explorer/explorer.tsx | PropertyExplorer: providers, persistence, URL state, layout, shortcuts |
components/explorer/store.ts | the zustand store (filters, favourites, UI) and localStorage migration |
components/explorer/lib/ | filtering and sorting, formatting, URL state, photo paths, labels and colours |
components/explorer/map/ | the MapLibre map (adapted from mapcn), clusters and markers, controls and overlays |
components/explorer/panel/, filters/, detail/ | the listings panel, the filters panel, the property detail |
components/explorer/data/listings.ts | the demo listings, agents and reviewers |
components/explorer/data/enrich.ts | derived fields, seeded per listing (stable between visits) |
components/explorer/data/media.ts | gallery assignment and blur previews, generated by pnpm media |
public/images/ | photos (pnpm media, credits in public/images/CREDITS.md) and style previews |
The components/ui/* files are standard shadcn/ui (new-york, Radix). Installed, the explorer follows your own shadcn/ui
theme; for Roofline's emerald look, copy the :root and .dark variables from app/globals.css (also in
registry/demos/roofline-theme.css).
MapLibre's worker. MapLibre GL 6 draws on a Web Worker kept in a file of its own
(node_modules/maplibre-gl/dist/maplibre-gl-worker.mjs) that app bundlers don't ship. Unless you set one, the
explorer fetches the same version's file from unpkg (jsDelivr as a fallback) once and starts it from a blob. To serve
it yourself, copy that file to public/ and call setWorkerUrl("/maplibre-gl-worker.mjs") from maplibre-gl before
the explorer renders. Under a Content-Security-Policy, allow worker-src blob:, data: in connect-src and the map
servers (basemaps.cartocdn.com, tiles.openfreemap.org, tiles.stadiamaps.com).
Scripts
pnpm media downloads and processes every photo (scripts/media-picks.json), node scripts/style-thumbs.mjs renders
the style previews from a running server, pnpm shots takes review screenshots (light and dark, 1440 → 390 px) into
.review/, and node scripts/e2e.mjs clicks through the main interactions, node scripts/a11y.mjs runs axe on the main screens,
pnpm registry writes registry/ (what UpFork lists) and pnpm zip packs roofline.zip (see LISTING.md).
Map data © OpenStreetMap contributors, © CARTO, OpenFreeMap / OpenMapTiles, © Stadia Maps. The map component is
adapted from mapcn (MIT). Photos from Unsplash (see public/images/CREDITS.md). Listings, agents and reviews are
fictional.
