Commerce & Orders
Menu Item Card
A data-driven menu item browser that fetches live menu data, filters by the active category, shows live opening-hours banners, and routes customers to a rich item detail screen with all the data they need to add to the cart.
The main browsing step between category selection and item detail.
Fetches live data in preview mode; falls back to static data in the builder.
Automatically narrows the list to the selected category.
Four things worth knowing
Backend menu fetching
Uses appId and secureApiCall to load live menu data from AWS. Supports hydration from prefetched menu and opening-hours payloads to reduce load time.
Category filtering
Reads activeCategoryFilter to show only items matching the selected category. Works whether the filter comes from navigation params or a sibling Category Card.
Opening-hours banner
Fetches or uses prefetched opening-hours data to render a live status banner at the top of the list - open, closed, or opening soon.
Rich detail navigation
Passes food item name, description, price, image, options, nutrition, allergen, and category data to Menu Item Detail through navigation params.
Builder mode: when isPreview is false the component renders with static preview data and a placeholder banner so layout is always visible on the canvas.
Find it, drop it, wire the detail screen
Where to find itAdd it to your item list screen
- Component picker → Commerce & Orders → Menu Item Card.
- Drop it onto your item list or category destination screen.
- Set
detailScreenIdto route taps to your Menu Item Detail screen.
Before you publishThree things to check
- Enable
showTodayHoursif your venue has time-based availability. - Set
placeNameso it appears in order summaries on the detail screen. - Prefetch menu and opening-hours data at the screen level for faster renders.
Data, filtering, and display
| Prop | Type | Default | Description |
|---|---|---|---|
detailScreenId, onScreenNavigate | string / function | ” / Injected | Shared destination screen for all item taps. Per-item screenId overrides this. |
placeName | string | none | Restaurant name passed as a navigation param to the detail screen for use in order summaries. |
activeCategoryFilter | string | From navigation params | Filters the item list to the matching category. Comes from a sibling Category Tabs component on the same screen. |
layout | select | horizontal | horizontal places the image right with text left. vertical uses a full-width image at the top. |
showPrice, showDescription, showTags, showImage, showBadge | boolean | true | Individual toggles for each visible element on the card. |
showTodayHours, _prefetchedOpeningHours | boolean / object | false / none | Enables the opening-hours banner. Provide prefetched hours data to skip a network call. |
appId, secureApiCall, _prefetchedMenuData | runtime | Injected by AppPlayer | Scopes the menu fetch to the current app. Pass _prefetchedMenuData from a screen-level hook to avoid a second network call. |
Make it yours
Most visual customisation lives in Builder style props. Keep component defaults in sync with registry defaultProps when updating branding tokens.
| Prop | Default | What it controls |
|---|---|---|
backgroundColor, cardBackgroundColor | Theme defaults | Screen and card surface colors. |
titleColor, priceColor, descriptionColor | Theme defaults | Item name, price, and description text hierarchy. |
tagBackgroundColor, tagTextColor | Theme defaults | Pill tag chip background and label color. |
badgeBackgroundColor, badgeTextColor | Theme defaults | Badge chip background and label color. |
borderColor, iconColor | Theme defaults | Card border and icon tint. |
cardBorderRadius, imageBorderRadius | Component defaults | Card corner rounding and image clip radius. |
imageSize, spacing | Component defaults | Thumbnail dimensions and internal card padding. |
fontFamily, titleFontSize, priceFontSize, descriptionFontSize, tagFontSize | Component defaults | Typography family and per-element font scales. |
Common mistakes to avoid
Prefetch for speed
Pass prefetchedMenu and prefetchedOpeningHours from a screen-level data hook to avoid showing a loading spinner every time the screen mounts.
Keep item param shape stable
The data passed to Menu Item Detail must match what that component expects. If you add or rename fields here, update Menu Item Detail at the same time.
Category key must match Card and Header
The category string used as the filter must be identical across Menu Category Card, Menu Item Card, and Menu Section Header for the flow to work correctly.
Builder shows static data by design
When isPreview is false the component renders placeholder items and a static banner. This is intentional - not a loading error.