Commerce & Orders
Menu Category Card
Large image cards for restaurant menu category browsing. Category data comes from your backend (Admin Menu Manager) and is mapped automatically - including a dedicated Combos card. Tapping a card navigates to the destination screen and passes category, title, subtitle, and itemCount as navigation params for item filtering.
Reads categories and dishes from Admin Menu Manager. Falls back to local defaults when unavailable.
Pick below-card or overlay text placement per category.
Route all categories to one screen or give each its own destination.
Four things worth knowing
Backend-driven category mapping
When _prefetchedMenuData or appId is available, the component fetches live categories and dishes, maps them to cards, and appends a dedicated Combos card automatically.
Below and overlay card styles
Controls whether labels and metadata appear below the image or overlaid on top. Both styles support transparent and solid label backgrounds with fixed design constants for height, spacing, and overlay opacity.
Shared or per-category destinations
Point all cards at a single screen via detailScreenId, or override individual cards with their own screenId. Both paths pass the same category filter param to the destination.
Safe image placeholder policy
No external stock URLs are used. If a category has no image, the component shows an Ionicons image-outline placeholder instead - intentional behavior, not a bug.
Find it, drop it, wire the destination
Where to find itAdd it to your category screen
- Component picker → Commerce & Orders → Menu Category Card.
- Drop it onto your menu home or categories screen.
- Set
detailScreenIdto the shared Menu Item Card screen.
Before you publishThree things to check
- Confirm
detailScreenIdpoints to a screen with a Menu Item Card or category-tab component that readsnavigationParams.category. - Verify
cardStyle- useoverlayfor image-rich menus andbelowfor cleaner readability. - Keep
categoryfilter values consistent:appetizer,main-course,dessert,combo.
Data, navigation, and display
| Prop | Type | Default | Description |
|---|---|---|---|
_prefetchedMenuData, appId, secureApiCall | runtime | Injected by AppPlayer | Primary data path. When available, live backend categories are fetched and mapped to cards. |
categories | array | Local defaults | Legacy fallback only. Used when backend data is unavailable. |
detailScreenId | string | ” | Shared destination screen for all category card taps. |
cardStyle | select | below | below - label below image. overlay - label on top of image. |
showItemCount, showDescription | boolean | true | Toggles item count badge and description text on each card. |
Make it yours
Card height, spacing, font sizes, overlay colour, and overlay opacity are fixed design constants inside BuilderMenuCategoryCard.tsx. To change them globally, edit those constants directly rather than through the Builder panel.
| Prop | Default | What it controls |
|---|---|---|
backgroundColor, cardBackgroundColor | Theme defaults | Outer container and card surfaces. |
titleColor | Theme default | Category name text on each card. |
itemCountColor, descriptionColor | Theme defaults | Secondary metadata text hierarchy. |
borderRadius | Component default | Card corner rounding. |
fontFamily | Component default | Typography family across all card text. |
Common mistakes to avoid
Keep category filter values stable
The category param sent on navigation is the filter key read by Menu Item Card and category-tab components. Renaming a value here without updating the target screen breaks item filtering.
Overlay style needs contrast
Overlay text can be hard to read on light or busy images. Add a semi-transparent scrim or switch to below style for categories without a strong hero image.
Per-category screenId overrides should be the exception
Only use a per-card screenId when a category genuinely needs a different layout. A single shared detailScreenId is much easier to maintain.
Regenerate deploy bundle after edits
After changing card UI, registry, or dimensions, run node collectSourceFiles.js from app/ to refresh bundledSourceFiles.ts.