Lists & Navigation

Category Tabs

Horizontal text-tab selector for category filtering and segmented in-screen navigation. Tracks the selected tab internally, calls onTabSelect on press, and drives sibling component filtering through onCategoryFilter - without forcing a full screen change.

Best forIn-screen filtering

Product and menu filters, segmented list views, and category-driven content sections on the same screen.

Sibling filteringonCategoryFilter

Emits the selected category value so connected list or grid components can filter their content automatically.

TierFree

Available on all plans.

What it does

Four things worth knowing

Internal selection with external emission

The component tracks the active tab internally and renders selected/unselected styles automatically. When a tab is pressed, it calls onTabSelect with the full TabItem and onCategoryFilter with the category value for sibling filtering.

Fuzzy matching from activeCategoryFilter

When activeCategoryFilter is set externally (e.g. from a parent player), the component fuzzy-matches it to the nearest existing tab value and highlights the correct tab - even if the value isn’t an exact match.

Text-only tabs - no icons

Each tab renders a label and carries a value used for filtering. An optional screenId can be attached per tab for navigation use cases. No icons are supported.

Builder mode vs. preview mode

When isPreview is false, tab presses are disabled so the block can be dragged on the canvas. Filtering and selection only fire in preview and live runtime.

Builder setup

Find it, drop it, edit the tabs

Where to find itAdd it to any screen

Component picker → Lists & Navigation → Category Tabs.
Drop it above the list or grid it should filter.
Open the edit panel and configure the tabs array.

Before you publishThree things to check

Keep tabs[].value aligned with the category slugs used by connected list or menu components - mismatched values break filtering.
Set selectedValue to the default active tab so the screen opens with a selection already applied.
Test filtering in preview - tab presses are disabled on the canvas.

Category: Lists & NavigationComponent: BuilderCategoryTabsRegistry key: category-tabsTier: Free

Props

Tabs, selection, and layout

Every prop below is set in the property panel. Start with the tabs array and selectedValue, then adjust spacing and typography to match the brand.

Prop	Type	Default	Description
`tabs`	TabItem[]	2 example items	Array of `{ label, value, screenId? }` objects. Keep `value` aligned with sibling component category slugs.
`selectedValue`	string	`’appetizer’`	Default active tab value. Sets the initial selection on first render.
`borderRadius`	number	`20`	Corner rounding for tab pill.
`paddingHorizontal`	number	`16`	Horizontal padding inside each tab.
`paddingVertical`	number	`8`	Vertical padding inside each tab.
`spacing`	number	`8`	Gap between tabs.
`fontSize`	number	`14`	Tab label text size.
`fontFamily`	string	`’Urbanist-Medium’`	Font face for tab labels.
`fontWeight`	string	`’500’`	Unselected label weight.
`selectedFontWeight`	string	`’600’`	Selected label weight.
`showBorder`	boolean	`false`	Show tab border outlines.
`borderWidth`	number	`1`	Border stroke width. Only visible when `showBorder` is on.

Toggles & colours

Make it yours

Every color below is yours to change. The defaults are a neutral starting point - selected tab color is the most impactful change to match your brand.

Prop	Default	What it controls
`backgroundColor`	`transparent`	Strip background color.
`tabBackgroundColor`	`transparent`	Unselected tab background.
`selectedTabBackgroundColor`	`#E8613A`	Selected tab background - the primary brand color to change.
`textColor`	`#666666`	Unselected label text color.
`selectedTextColor`	`#FFFFFF`	Selected label text color.
`borderColor`	`#E0E0E0`	Unselected tab border. Only visible when `showBorder` is on.
`selectedBorderColor`	`transparent`	Selected tab border color.

Tips

Common mistakes to avoid

Keep tab values in sync with sibling components

The value field on each tab must match the category slugs used by any connected list or menu component. Mismatched values mean filtering silently does nothing.

Always set a default selectedValue

Without a selectedValue, no tab appears active on load. Set it to the most relevant default category so the screen opens with content already filtered.

Test filtering in preview

Tab presses are disabled on the canvas. Always switch to preview mode to confirm onCategoryFilter is correctly driving sibling component content before publishing.

Change selected tab color first

The default selected background is orange (#E8613A). This is the single highest-impact color change - update it to your brand primary before adjusting anything else.

We’re almost ready.