# Mobile App Home > A React mobile app home screen for a marketplace: large title, search, stories, quick actions, recommended ads, feed tabs and a tab bar. - Type: React block (Blocks) - Access: Pro (the source needs a Wingo UI Pro plan, see https://wingo-ui.com/pricing) - Version: 1.1.0 - Install: `npx wingo-ui@latest add mobile-app-home` - Docs: https://wingo-ui.com/components/mobile-app-home ## Interaction Scroll and the large title "Home" hands over to a compact glass bar; the feed tabs stick under it. Pull down at the top (touch, or a trackpad scroll up) and the iOS spinner refreshes "For you" with a haptic tick and a fade. Tap the search field: the page swaps to your recent searches (tap one to search it again, x removes it, Clear all clears them), typing filters every ad by title and place, Enter saves the query and calls onSearch, Cancel or Escape closes the search. Tap a story circle to open its full-height sheet with three new ads and See all; the ring turns gray once seen (drag the handle down, tap outside, the close button or Escape to close). Quick action tiles and the bell are links with count badges. Recommended ads sit in a 2-column grid: Show more reveals the next row in place, See all opens the full list, and a heart saves an ad (shared between the grid and the feed). Switch For you, Nearby and Following by tapping, swiping the list sideways or with the arrow keys on the tabs; Load more shows the next page. The bottom tab bar hides while you scroll down and comes back on scroll up; Search focuses the search, Home scrolls back to the top and the raised Post button posts an ad. On a desktop the app is a centered 440px column on a gray backdrop. ## Installation ```bash npx wingo-ui@latest add mobile-app-home ``` Pro item: run `npx wingo-ui@latest login` once with a Pro account. The CLI adds the files, their dependencies and a version record for updates. With shadcn: `npx shadcn@latest add @wingo-ui/mobile-app-home` (needs the @wingo-ui registry with your API key in components.json) Files: - `components/blocks/mobile-app-home.tsx` - `components/blocks/mobile-app-home-data.ts` npm dependencies: `npm i motion lucide-react` Wingo UI dependencies (installed automatically): - [Avatar](https://wingo-ui.com/components/avatar) ([Markdown](https://wingo-ui.com/components/avatar.md)) - [Badge](https://wingo-ui.com/components/badge) ([Markdown](https://wingo-ui.com/components/badge.md)) - [Bottom Tab Bar](https://wingo-ui.com/components/bottom-tab-bar) ([Markdown](https://wingo-ui.com/components/bottom-tab-bar.md)) - [Button](https://wingo-ui.com/components/button) ([Markdown](https://wingo-ui.com/components/button.md)) - [Drawer](https://wingo-ui.com/components/drawer) ([Markdown](https://wingo-ui.com/components/drawer.md)) - [Empty State](https://wingo-ui.com/components/empty-state) ([Markdown](https://wingo-ui.com/components/empty-state.md)) - [Favorite button](https://wingo-ui.com/components/favorite-button) ([Markdown](https://wingo-ui.com/components/favorite-button.md)) - [Large Title Header](https://wingo-ui.com/components/large-title-header) ([Markdown](https://wingo-ui.com/components/large-title-header.md)) - [List](https://wingo-ui.com/components/list) ([Markdown](https://wingo-ui.com/components/list.md)) - [Listing card](https://wingo-ui.com/components/listing-card) ([Markdown](https://wingo-ui.com/components/listing-card.md)) - [Price](https://wingo-ui.com/components/price) ([Markdown](https://wingo-ui.com/components/price.md)) - [Pull To Refresh](https://wingo-ui.com/components/pull-to-refresh) ([Markdown](https://wingo-ui.com/components/pull-to-refresh.md)) - [Skeleton](https://wingo-ui.com/components/skeleton) ([Markdown](https://wingo-ui.com/components/skeleton.md)) - [Swipeable Tabs](https://wingo-ui.com/components/swipeable-tabs) ([Markdown](https://wingo-ui.com/components/swipeable-tabs.md)) - [useControllableState](https://wingo-ui.com/components/use-controllable-state) ([Markdown](https://wingo-ui.com/components/use-controllable-state.md)) - [Haptics](https://wingo-ui.com/components/haptics) ([Markdown](https://wingo-ui.com/components/haptics.md)) - [Motion presets](https://wingo-ui.com/components/motion) ([Markdown](https://wingo-ui.com/components/motion.md)) - [Navigation](https://wingo-ui.com/components/navigation) ([Markdown](https://wingo-ui.com/components/navigation.md)) - [Number format](https://wingo-ui.com/components/number-format) ([Markdown](https://wingo-ui.com/components/number-format.md)) - [Relative time](https://wingo-ui.com/components/relative-time) ([Markdown](https://wingo-ui.com/components/relative-time.md)) - [Text match](https://wingo-ui.com/components/text-match) ([Markdown](https://wingo-ui.com/components/text-match.md)) - [Tones](https://wingo-ui.com/components/tones) ([Markdown](https://wingo-ui.com/components/tones.md)) - [UIProvider](https://wingo-ui.com/components/ui-config) ([Markdown](https://wingo-ui.com/components/ui-config.md)) ## Usage ```tsx // app/(app)/page.tsx "use client" import Link from "next/link" import { useRouter } from "next/navigation" import { MobileAppHome } from "@/components/blocks/mobile-app-home" export default function HomePage() { const router = useRouter() return ( router.push(`/search?q=${encodeURIComponent(query)}`)} onRefresh={() => router.refresh()} /> ) } ``` ## Props | Prop | Type | Default | Description | | --- | --- | --- | --- | | `title?` | `ReactNode` | `"Home"` | The large title; it shrinks into the bar as you scroll. | | `subtitle?` | `ReactNode` | `"Hi, Emma"` | The line under the large title. | | `stories?` | `AppStory[]` | | Story circles { id, label, image?, icon?, seen?, href?, description?, ring?, listings? }; [] hides the rail. Defaults to MOBILE_APP_HOME_SAMPLE.stories (Deals, Bikes, Phones, Homes, Daniel Reed, Greenleaf). | | `quickActions?` | `AppQuickAction[]` | | Up to 8 tiles { id, label, icon, href?, badge?, onSelect? } in a 4-column grid; [] hides them. Defaults to Post an ad, Favorites (4), Saved searches (2), My orders. | | `recommended?` | `ListingData[]` | | The 2-column grid of ad cards; [] hides it. Defaults to MOBILE_APP_HOME_SAMPLE.recommended (the 8 canonical ads). | | `feeds?` | `Partial>` | | The ads of each tab, merged over MOBILE_APP_HOME_SAMPLE.feeds (20 each); an empty array shows the tab's empty state. | | `recentSearches?` | `AppRecentSearch[]` | | { id, query } rows shown while the search is open; defaults to MOBILE_APP_HOME_SAMPLE.recentSearches. | | `user?` | `{ name: string; avatar?: string }` | | The signed-in person shown as the avatar in the header; defaults to Emma Carter. | | `hrefs?` | `Partial` | | Where the bell, avatar, Messages, Post, See all and the empty state's action go (notifications, account, messages, add, recommended, discover). | | `labels?` | `Partial` | | Every visible string (Romanian by default, DEFAULT_MOBILE_APP_HOME_LABELS); MOBILE_APP_HOME_LABELS_EN is the English set. Nested listingCard, pullToRefresh, swipeableTabs and list pass strings to the composed items. | | `tab?` | `"for-you" \| "nearby" \| "following"` | | Controlled feed tab; pair it with onTabChange. | | `defaultTab?` | `"for-you" \| "nearby" \| "following"` | `"for-you"` | The feed tab the screen opens on while uncontrolled. | | `onTabChange?` | `(tab: MobileAppHomeTab) => void` | | Called when a tab is tapped or swiped to. | | `defaultStory?` | `string` | `""` | The id of a story whose sheet is open on mount; empty for none. | | `notificationsCount?` | `number` | `3` | The count on the bell; 0 hides the badge. | | `messagesCount?` | `number` | `2` | The count on the Mesaje tab; 0 hides it. | | `showStories?` | `boolean` | `true` | The story circles rail. | | `showQuickActions?` | `boolean` | `true` | The grid of quick action tiles. | | `showRecommended?` | `boolean` | `true` | The recommended ads grid. | | `recommendedCount?` | `number` | `4` | Recommended ads shown at first; Show more adds this many again until all are shown. | | `pullToRefresh?` | `boolean` | `true` | Pull down at the top to refresh the feed (off while searching or loading). | | `refreshShortcut?` | `string` | `""` | A key combo in mod+k notation that refreshes the feed like a pull; none by default. | | `tabBar?` | `boolean` | `true` | The bottom tab bar with the raised Post action. | | `tabBarVariant?` | `"bar" \| "floating"` | `"bar"` | A full-width glass bar on the bottom edge, or a floating glass pill. | | `desktop?` | `"column" \| "full"` | `"column"` | column: from 768px the app is a centered 440px column on a gray backdrop. full: it stretches (a real PWA on a tablet). | | `pageSize?` | `number` | `8` | Ads per page of a feed; Load more shows the next page. | | `tone?` | `"neutral" \| "brand" \| "success" \| "warning" \| "danger" \| "info"` | `"neutral"` | Unseen story rings, the active tab, the tab bar's active color and raised action, and the text actions. | | `loading?` | `boolean` | `false` | Skeleton story circles, tiles, cards and rows in the real layout. | | `animateIn?` | `boolean` | `true` | Sections rise in once on mount; off in thumbnails and under reduced motion. | | `locale?` | `string` | `"en-US"` | Intl locale for prices, distances, times and counts. | | `currency?` | `string` | `"USD"` | The currency of ads that do not set their own. | | `now?` | `Date \| number` | `"useNow()"` | The clock for "Today at 2:32 PM"; pass it for stable renders (the demo uses Sep 24, 2026 4:40 PM). | | `onRefresh?` | `() => (void \| Promise)` | | The pull to refresh; the spinner runs until it settles. Without it the feed reshuffles after 1,2 s. | | `onSearch?` | `(query: string) => void` | | Enter in the search field; the query is also added to the recent searches. | | `onStoryOpen?` | `(story: AppStory) => void` | | A story circle was tapped (its sheet opens and it turns seen). | | `onFavoriteChange?` | `(listing: ListingData, favorite: boolean) => (void \| Promise)` | | A heart was toggled; a rejected promise rolls it back. | | `onLoadMore?` | `(tab: MobileAppHomeTab) => (void \| Promise)` | | Load more; the button spins until it settles, then the next page shows. Simulated (900 ms) without it. | | `linkComponent?` | `(props: LinkComponentProps) => ReactNode` | `""` | The router link for every link on the screen (next/link in an app). | | `className?` | `string` | | Classes for the app column. | | `classNames?` | `Partial>` | | Classes for backdrop, header, search, stories, story, actions, recommended, feed and tabBar. | ## Parts ### mobileAppHomeContent (function) Maps a sample (stories and quick actions with icon names) to the block's props with real icons. Spread its result on MobileAppHome. ### DEFAULT_MOBILE_APP_HOME_LABELS (constant) Every English string of the home screen: title, search, sections, feed tabs, tab bar and refresh. Spread it and override what you translate. ### MOBILE_APP_HOME_LABELS_EN (constant) An alias of DEFAULT_MOBILE_APP_HOME_LABELS, kept so older imports keep working. ### createMobileAppHomeSample (function) Builds the demo content: stories, quick actions, recommended ads, the For you, Nearby and Following feeds, recent searches and badge counts. ### MOBILE_APP_HOME_SAMPLE (constant) The demo content built once by createMobileAppHomeSample. Replace it with data from your API. ### MOBILE_APP_HOME_SAMPLE_EN (constant) The same demo content under its older name, kept so existing imports keep working. ### shuffleFeed (function) Reorders a feed in a stable way per round, so pull to refresh shows new items in the same order on every device. ### mulberry32 (function) A tiny seeded random number generator, so the sample is the same on the server and the client. ### MOBILE_APP_HOME_NOW (constant) The fixed "now" of the sample (September 24, 2026, 4:40 PM) that ad ages are measured from. ## Examples - **Nearby**: Opens on the Nearby tab: ads around the Pearl District, closest first, with their distance. - **A story open**: The Bikes story sheet, full height: three new ads and a See all action. - **Floating tab bar, brand**: tabBarVariant floating with tone brand: story rings, tabs, the raised action and the links in orange. - **Loading**: Skeleton story circles, action tiles, cards and rows in the real layout. - **Empty following tab**: No followed sellers yet: the Following tab shows its empty state with one action. - **British English**: Locale en-GB with prices in euro: dates, distances and counts follow the locale. ## See also - [Large Title Header](https://wingo-ui.com/components/large-title-header) ([Markdown](https://wingo-ui.com/components/large-title-header.md)) - [Bottom Tab Bar](https://wingo-ui.com/components/bottom-tab-bar) ([Markdown](https://wingo-ui.com/components/bottom-tab-bar.md)) - [Pull To Refresh](https://wingo-ui.com/components/pull-to-refresh) ([Markdown](https://wingo-ui.com/components/pull-to-refresh.md)) - [Swipeable Tabs](https://wingo-ui.com/components/swipeable-tabs) ([Markdown](https://wingo-ui.com/components/swipeable-tabs.md)) - [Listing card](https://wingo-ui.com/components/listing-card) ([Markdown](https://wingo-ui.com/components/listing-card.md)) - [Drawer](https://wingo-ui.com/components/drawer) ([Markdown](https://wingo-ui.com/components/drawer.md)) --- Canonical: https://wingo-ui.com/components/mobile-app-home More components: https://wingo-ui.com/components ยท Index for agents: https://wingo-ui.com/llms.txt