Services
Service Category Grid
A dedicated category browser for service apps. BuilderServiceCategoryGrid renders a 2- or 3-column grid of backend service categories, with optional image, icon, subtitle, provider count, price range, and badge. Tapping a card either filters a sibling Service List in place or navigates to another screen with the category pre-selected.
Set columns to 2 or 3. Two columns works best on most phones; three suits tablets or compact category cards.
Leave detailScreenId empty for sibling filtering, or set it to navigate and pass category as a nav param.
Available on all plans.
Four things worth knowing
Two tap modes, no custom logic
Use the same component for both flows: in-place filtering of a sibling Service List, or navigation to a separate screen with the category already selected.
In-place filtering path
When detailScreenId is empty, the grid emits onCategoryFilter. AppPlayer forwards that selection to a sibling Service List via activeCategoryFilter.
Navigation path
When detailScreenId is set, the grid navigates and passes category as a nav param so the target Service List can pre-filter on load.
Backend-sourced categories and rich cards
Categories come from the same backend data managed in Admin Service Manager. Leave selectedCategoryNames empty to show all categories, or provide exact names to show only a subset. Each card can display image, icon, title, subtitle, provider count, price range, and badge.
Find it, drop it, choose the tap mode
Where to find itAdd it to a browse screen
- Component picker → Services → Service Category Grid.
- Place it above a Service List on a home or browse screen.
- Use it either for sibling filtering or for navigation to a separate category screen.
Before you publishThree things to check
- For in-place filtering, keep
detailScreenIdempty and place Service Category Grid plus Service List on the same screen. - For navigation, set
detailScreenIdto a screen that contains a Service List. - On that target screen, set
showCategoryFilter: falseif only one category should appear.
Selection, layout, and navigation
| Prop | Type | Default | Description |
|---|---|---|---|
selectedCategoryNames | backend-category-picker | [] | Pick which categories to show. Empty = all categories. |
columns | select | 2 | Choose 2 or 3 columns. |
detailScreenId | screen-select | ” | Screen all categories navigate to; receives category as a navigation param. |
Make it yours
Visibility toggles are available for each optional card element. Some presentation details stay fixed in code for the MVP so the grid remains consistent across screens.
| Prop | Default | What it controls |
|---|---|---|
showImage | true | Category image visibility. |
showIcon | true | Icon visibility. |
showSubtitle | true | Subtitle visibility. |
showProviderCount | true | Provider count visibility. |
showPriceRange | true | Price range visibility. |
showBadge | true | Badge visibility. |
Common mistakes to avoid
Pick one interaction mode per grid
If you set detailScreenId, the grid navigates on tap. If you leave it empty, it filters a sibling Service List in place. Do not mix both expectations on one grid instance.
Selected names must match exactly
If you provide selectedCategoryNames, those values must match backend category names exactly or the missing categories will not render.
Some presentation rules are fixed
Image height, card border radius, card spacing, icon size, and max category count are intentionally fixed in code for the MVP. Do not expect those controls in the property editor.
Hide the target chip bar when needed
When navigating to a category-specific Service List screen, set showCategoryFilter: false there if only one category should appear. It keeps the target screen cleaner.