TabGroup
Composable primitives for building tab navigation with lynx-ui. The package provides `TabsRoot`, `TabsBar`, `TabsItem`, `TabsIndicator`, and an optional swipeable `TabsPanel`.Info
You can check the source code to understand how it works, and you're welcome to submit PRs to enhance its capabilities.
Basic Usage
Render data-driven tabs with custom items, synchronized content, selection state, and an indicator.
Examples
Panel
Connect a tab bar to swipeable, data-driven content panels.
Imperative Selection
Select a tab through a ref with either smooth or instant movement.
Structure
Component API
TabsRoot
Properties
childreniOSAndroidHarmony
children
debugLogiOSAndroidHarmony
Display debug logs. Open it when you find a bug.
enableRTLiOSAndroidHarmony
Enable RTL layout.
indicatorAnimationiOSAndroidHarmony
The animation configuration for the tab indicator when switching tabs.
initialSelectIndexiOSAndroid
The index of the initial display. Please use
selectTab for other updates.selectBehavioriOSAndroid
Controls how the tab bar scrolls and how the indicator moves when a tab is
selected. Use
'smooth' to animate the transition, or 'instant' to jump
to the target tab without animation.Events
onClickItemiOSAndroid
Click callback
onTabChangediOSAndroid
Tab change callback
TabsBar
Properties
androidTouchSlopAndroid
Android touch recognition mode. When inside a component that supports 'paging' mode, 'paging' must be enabled.
bounceableiOSAndroid
Enable bouncing effect
bounceableOptionsiOSAndroid
Props for bouncing effect
childreniOSAndroidHarmony
children
classNameiOSAndroidHarmony
className
dataiOSAndroidHarmony
The data for the Tabs.
debugLogiOSAndroidHarmony
Display debug logs for bounce interactions.
enableNewArchiOSAndroidHarmony
Enable the native
<scroll-view> new architecture. When enabled, bounceableOptions uses native bounces on Android, iOS, and Harmony. Defaults to true on Lynx SDK 4.3 and newer, and false on earlier versions.enableRTLiOSAndroidHarmony
Whether horizontal bounce direction should be mirrored in RTL mode.
enableScrolliOSAndroidHarmony
Enable scroll interaction.
enableScrollMonitoriOSAndroidHarmony
Enable scroll monitor.
estimatedItemStyleiOSAndroid
Estimated height and width of the items need to be set.
experimentalNestedScrollBackwardHarmony
Adapts Harmony nested scroll behavior. 'selfOnly' scrolls only this component. 'selfFirst' scrolls this component first, then the parent after this component reaches a scroll boundary. 'parentFirst' scrolls the parent first, then this component after the parent reaches a scroll boundary. 'parallel' scrolls this component and the parent at the same time.
experimentalNestedScrollForwardHarmony
Adapts Harmony nested scroll behavior. 'selfOnly' scrolls only this component. 'selfFirst' scrolls this component first, then the parent after this component reaches a scroll boundary. 'parentFirst' scrolls the parent first, then this component after the parent reaches a scroll boundary. 'parallel' scrolls this component and the parent at the same time.
exposureBottomiOSAndroid
exposure-screen-margin-bottom
exposureIDiOSAndroidHarmony
exposure-id for global exposure
exposureLeftiOSAndroid
exposure-screen-margin-left
exposureRightiOSAndroid
exposure-screen-margin-right
exposureSceneiOSAndroidHarmony
exposure-scene for global exposure
exposureTopiOSAndroid
exposure-screen-margin-top
firstScreenItemCountiOSAndroid
Estimated first screen item count for lazy rendering. Remaining children will complete rendering based on exposure. When this estimate is small, it may cause a blank screen phenomenon where some nodes exist on the first screen.
getTabKeyiOSAndroidHarmony
Return a stable, unique key for each tab. When omitted, the item index is
used. Provide this function when tabs can be inserted, removed, or reordered.
iOSBouncesiOSAndroid
Open the bouncing effect on iOS. If you want to use it on Android, please refer to the bounceableOption. If the bounceableOption is set, the iOSBounces property will be invalid.
lazyiOSAndroid
When enabled, only the items that are about to enter the viewport are rendered, reducing initial load time and memory usage; remaining items are rendered as they approach visibility during scroll.
lazyOptionsiOSAndroid
When enabled, only the items that are about to enter the viewport are rendered, reducing initial load time and memory usage; remaining items are rendered as they approach visibility during scroll.
main-thread:gestureiOSAndroid
If you want to use gesture, pass it here.
onUIAppeariOSAndroidHarmony
Exposure event for UI
onUIDisappeariOSAndroidHarmony
Disappear event for UI
renderTabItemiOSAndroidHarmony
Render each tab item. TabsItem reads its key from TabsBar automatically.
sceneiOSAndroid
Be used to mark the exposure timing of lazy loading. Please ensure that it is unique throughout the page.
scrollMonitorTagiOSAndroidHarmony
The tag for scroll monitor.
scrollPropagationBehavioriOSAndroid
Controls whether scroll events propagate to parent containers. For now, 'preventPropagate' needs to be used together with temporaryBlockScrollClass and temporaryBlockScrollTag on iOS.
scrollviewIdiOSAndroid
The id of the scrollview.
stickyiOSAndroid
Sticky item, designed for
Tabs.styleiOSAndroidHarmony
style
tabsItemWrapperClassiOSAndroid
The class apply to the internal container of child view inside scroll-view.
temporaryBlockScrollClassiOS
The specific class name of the container that is blocked when 'scrollPropagationBehavior' is set to be 'preventPropagate', must be informed by the container provider. For now, 'preventPropagate' needs to be used together with temporaryBlockScrollClass and temporaryBlockScrollTag on iOS.
temporaryBlockScrollTagiOS
Used to specify the native container tag that is blocked when 'scrollPropagationBehavior' is set to be 'preventPropagate', corresponding to the Tag attribute of UIView. Needs to be specified by the native container provider. For now, 'preventPropagate' needs to be used together with temporaryBlockScrollClass and temporaryBlockScrollTag on iOS.
temporaryNestedScrollAndroid
Android-only temporary flag to control nested scroll; maps to native 'enable-nested-scroll'. Android default value is true.
testingiOSAndroid
Testing Mode.
Events
catchLongPressiOSAndroidHarmony
Same as onLongPress, but stops the event from propagating to parent elements.
catchTouchCanceliOSAndroidHarmony
Same as onTouchCancel, but stops the event from propagating to parent elements.
catchTouchEndiOSAndroidHarmony
Same as onTouchEnd, but stops the event from propagating to parent elements.
catchTouchMoveiOSAndroidHarmony
Same as onTouchMove, but stops the event from propagating to parent elements.
catchTouchStartiOSAndroidHarmony
Same as onTouchStart, but stops the event from propagating to parent elements.
onContentSizeChangeiOSAndroid
Being triggered when scrolling content changes.
onLayoutChangeiOSAndroidHarmony
Send when UI has changed viewport size.
onLongPressiOSAndroidHarmony
Send when a touch-point is held on the UI for a period of time.
onScrolliOSAndroid
Being triggered when scrolling occurs.
onScrollEndiOSAndroid
Being triggered when scrolling stops.
onScrollToLoweriOSAndroid
Being triggered when scrolling to lower.
onScrollToUpperiOSAndroid
Being triggered when scrolling to upper.
onTapiOSAndroidHarmony
Send when a touch-point is tapped on the UI.
onTouchCanceliOSAndroidHarmony
Send when a touch event is interrupted or cancelled before it is completed.
onTouchEndiOSAndroidHarmony
Send when a touch-point is removed from the UI.
onTouchMoveiOSAndroidHarmony
Send when a touch-point is moving on the UI.
onTouchStartiOSAndroidHarmony
Send when a touch-point is placed on the UI.
onWheel
Send when a wheel event is triggered on the scroll-view.
TabsItem
childreniOSAndroidHarmony
The content of the tab item.
classNameiOSAndroidHarmony
className
styleiOSAndroidHarmony
style
tabKeyiOSAndroidHarmony
TabsBar supplies this automatically to items rendered by renderTabItem.
Set it for manually rendered items, matching the key derived from data.
TabsPanel
bouncesiOSAndroid
Enable the native spring effect where supported.
childreniOSAndroid
Render page content. Selection state is intentionally not passed, so a
native swipe does not require React to rerender page content.
classNameiOSAndroidHarmony
className
dataiOSAndroid
Data rendered as pages. ViewPager creates one direct native
viewpager-item child for every entry.
enableScrolliOSAndroid
Enable horizontal swipe gestures.
getItemKeyiOSAndroid
Return a stable, unique key for an entry. When omitted, the item index is
used. Provide this function when items can be inserted, removed, or reordered.
getItemPropsiOSAndroid
Native props for an individual generated item. Its class name is added to
itemClassName; its style overrides matching itemStyle properties. The
item's key, ref, and children are managed by ViewPager.
idiOSAndroid
Identifier applied to the native ViewPager root.
itemClassNameiOSAndroid
Class name applied to every generated viewpager-item.
itemStyleiOSAndroid
Style applied to every generated viewpager-item.
lazyOptionsiOSAndroid
Exposure-driven lazy rendering. The initial page renders immediately;
other pages render when their placeholders enter the configured exposure
area. Rendered pages stay mounted. Omit this prop to render every page.
main-thread:onOffsetChangeiOSAndroid
Main-thread scroll progress handler. Use a main thread function.
main-thread:onPageChangeiOSAndroid
Main-thread page completion handler. Use a main thread function.
main-thread:onPageWillChangeiOSAndroid
Main-thread page transition handler. Use a main thread function.
onOffsetChangeiOSAndroid
Native scroll progress event. Read its data from event.detail.
onPageChangeiOSAndroid
Native page completion event. Read the selected index from event.detail.index.
onPageWillChangeiOSAndroid
Native event before a page transition completes. Read its data from event.detail.
styleiOSAndroidHarmony
style
viewpagerPropsiOSAndroid
Native pager attributes not managed by the component.
TabsIndicator
childreniOSAndroidHarmony
children
classNameiOSAndroidHarmony
className
indicatorPropsiOSAndroidHarmony
Raw props passed to the indicator.
styleiOSAndroidHarmony
style
TabsRootRef
selectTab
Supporting Types
TabsIndicatorAnimation
TabsIndicatorAnimation
TabsIndicatorAnimationSpring
damping
The spring damping of the indicator motion.
mass
The spring mass of the indicator motion.
stiffness
The spring stiffness of the indicator motion.
type
Use a spring transition for indicator motion.
velocity
The initial velocity of the spring animation.
TabsIndicatorAnimationTween
duration
The tween duration in milliseconds.
ease
The easing function of the tween animation.
type
Use a tween transition for indicator motion.