Lists & Navigation
Category Navigation
Horizontal icon and label category strip for compact, scrollable category selection - for example Shopping / Car / Food / Express. Tracks the selected category internally and emits it through onCategorySelect.
Each item uses an Ionicons name. Labels can be shown or hidden via a toggle. Images are no longer supported.
Top navigation areas, category entry sections, and screen-level switching zones.
Available on all plans.
Four things worth knowing
Horizontal scrollable strip
Renders categories in a horizontal row. Each item shows an icon in a rounded container with an optional label below. The strip scrolls when there are more items than fit on screen.
Internal selection state
The component tracks the active category internally and applies selected colors to the icon container and label automatically. The selected item is emitted through onCategorySelect.
Icons only - no images
Each item uses an Ionicons icon name (iconName). Image-based items are no longer supported. Icon size is fixed at 24 and item container size is fixed at 56.
Builder mode vs. preview mode
When isPreview is false, touch interactions are disabled so the block can be dragged on the canvas. Category selection only fires in preview and live runtime.
Find it, drop it, edit the categories
Where to find itAdd it to any screen
- Component picker → Lists & Navigation → Category Navigation.
- Drop it at the top of any screen that needs category filtering.
- Open the edit panel to configure categories.
Before you publishThree things to check
- Set each category’s
label,iconName, andvalue- use valid Ionicons names for icons. - Align selected colors (
selectedIconBackgroundColor,selectedIconColor,selectedLabelColor) with your brand palette. - Test category selection in preview - tapping is disabled on the canvas.
Categories, labels, and layout
Every prop below is set in the property panel. Start with the categories array, then adjust colors and typography to match the brand.
| Prop | Type | Default | Description |
|---|---|---|---|
categories | CategoryItem[] | 2 example items | Array of { label, iconName, value } objects. Use valid Ionicons names for iconName. |
showLabels | boolean | true | Show or hide text labels below icons. |
showBorder | boolean | false | Show or hide the strip border. |
borderRadius | number | 16 | Corner rounding for icon containers. |
fontFamily | string | ’Urbanist-Medium’ | Font face for category labels. |
fontSize | number | 12 | Label text size. |
Make it yours
Every color below is yours to change. The defaults are a neutral starting point - adjust them to match the brand without touching anything else.
| Prop | Default | What it controls |
|---|---|---|
backgroundColor | #FFFFFF | Strip background color. |
iconBackgroundColor | #F5F5F5 | Unselected icon container background. |
selectedIconBackgroundColor | #E8F5E9 | Selected icon container background. |
iconColor | #333333 | Unselected icon color. |
selectedIconColor | #2E7D32 | Selected icon color. |
labelColor | #666666 | Unselected label text color. |
selectedLabelColor | #1a1a1a | Selected label text color. |
borderColor | #E0E0E0 | Strip border color. Only visible when showBorder is on. |
Common mistakes to avoid
Use valid Ionicons names
Each item’s iconName must be a valid Ionicons identifier. Invalid names render a broken icon. Check the Ionicons reference before adding custom categories.
Test selection in preview
Category taps are disabled on the canvas so the block can be dragged. Always switch to preview mode to confirm onCategorySelect fires correctly for each item.
Keep the category list short
The strip scrolls horizontally when items overflow, but long lists are harder to scan. Aim for 4–6 categories - enough to cover the main groupings without overwhelming the user.
Align selected colors with your brand
The default selected colors are green-tinted. Update selectedIconBackgroundColor, selectedIconColor, and selectedLabelColor to match your brand palette before publishing.