For AI agents: the complete documentation index is available at /next/llms.txt, the full documentation bundle is available at /next/llms-full.txt, and this page is available as Markdown at /next/ui/components/tab-group.md.
lynx-ui logo
lynx-ui
  • English
  • 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

    <TabsRoot>
      <TabsBar
        data={tabs}
        renderTabItem={(tab, index) => <TabsItem />}
      >
        <TabsIndicator />
      </TabsBar>
      <TabsPanel data={panels}>
        {(panel, index) => <PanelContent />}
      </TabsPanel>
    </TabsRoot>

    Component API

    TabsRoot

    Properties
    childreniOSAndroidHarmony
    TypeReactNode
    children
    debugLogiOSAndroidHarmony
    Typeboolean·Defaultfalse
    Display debug logs. Open it when you find a bug.
    enableRTLiOSAndroidHarmony
    Typeboolean·Defaultfalse
    Enable RTL layout.
    indicatorAnimationiOSAndroidHarmony
    TypeTabsIndicatorAnimation·Default{ type: 'spring', stiffness: 300, damping: 30, mass: 1 }
    The animation configuration for the tab indicator when switching tabs.
    initialSelectIndexiOSAndroid
    Typenumber·Default0
    The index of the initial display. Please use selectTab for other updates.
    selectBehavioriOSAndroid
    Typesmooth | instant·Default'smooth'
    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
    Type(index: number) => void
    Click callback
    onTabChangediOSAndroid
    Type(index: number) => void
    Tab change callback

    TabsBar

    Properties
    androidTouchSlopAndroid
    Typedefault | paging
    Android touch recognition mode. When inside a component that supports 'paging' mode, 'paging' must be enabled.
    bounceableiOSAndroid
    Typeboolean
    Enable bouncing effect
    bounceableOptionsiOSAndroid
    Typeboolean | {alwaysBouncing?: boolean, enableBounceEventInFling?: boolean, enableBounces: boolean, endBounceTriggerDistance?: number, estimatedHeight?: number, estimatedWidth?: number, lowerBounceItem?: any, onScrollToBounces?: (e: ScrollToBouncesInfo) => void, singleSidedBounce?: upper | lower | both | iOSBounces | none, startBounceTriggerDistance?: number, upperBounceItem?: any, validAnimationVersion?: boolean}·Default{ enableBounces: true, singleSidedBounce: "iOSBounces" },
    Props for bouncing effect
    childreniOSAndroidHarmony
    TypeReactNode
    children
    classNameiOSAndroidHarmony
    Typestring
    className
    dataiOSAndroidHarmony
    TypeT[]
    The data for the Tabs.
    debugLogiOSAndroidHarmony
    Typeboolean·Defaultfalse
    Display debug logs for bounce interactions.
    enableNewArchiOSAndroidHarmony
    Typeboolean·Defaulttrue on Lynx SDK >= 4.3; false otherwise
    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
    Typeboolean·Defaultfalse
    Whether horizontal bounce direction should be mirrored in RTL mode.
    enableScrolliOSAndroidHarmony
    Typeboolean·Defaulttrue
    Enable scroll interaction.
    enableScrollMonitoriOSAndroidHarmony
    Typeboolean·Defaultfalse
    Enable scroll monitor.
    estimatedItemStyleiOSAndroid
    TypeCSSProperties
    Estimated height and width of the items need to be set.
    experimentalNestedScrollBackwardHarmony
    TypeselfOnly | selfFirst | parentFirst | parallel
    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
    TypeselfOnly | selfFirst | parentFirst | parallel
    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
    Typestring·Default'10px'
    exposure-screen-margin-bottom
    exposureIDiOSAndroidHarmony
    Typestring
    exposure-id for global exposure
    exposureLeftiOSAndroid
    Typestring·Default'10px'
    exposure-screen-margin-left
    exposureRightiOSAndroid
    Typestring·Default'10px'
    exposure-screen-margin-right
    exposureSceneiOSAndroidHarmony
    Typestring
    exposure-scene for global exposure
    exposureTopiOSAndroid
    Typestring·Default'10px'
    exposure-screen-margin-top
    firstScreenItemCountiOSAndroid
    Typenumber·Default1
    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
    Type(tabItem: T, index: number) => string
    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
    Typeboolean·Defaulttrue
    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
    Typeboolean·Defaulttrue
    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
    TypeLazyOptions·Defaulttrue
    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
    TypeBaseGesture<BaseGestureConfig, GestureChangeEvent>
    If you want to use gesture, pass it here.
    onUIAppeariOSAndroidHarmony
    Type(e: CommonEvent) => void
    Exposure event for UI
    onUIDisappeariOSAndroidHarmony
    Type(e: CommonEvent) => void
    Disappear event for UI
    renderTabItemiOSAndroidHarmony
    Type(tabItem: T, index: number) => ReactNode
    Render each tab item. TabsItem reads its key from TabsBar automatically.
    sceneiOSAndroid
    Typestring
    Be used to mark the exposure timing of lazy loading. Please ensure that it is unique throughout the page.
    scrollMonitorTagiOSAndroidHarmony
    Typestring·Defaultfalse
    The tag for scroll monitor.
    scrollPropagationBehavioriOSAndroid
    TypeScrollPropagationBehaviorOption·Default'native'
    Controls whether scroll events propagate to parent containers. For now, 'preventPropagate' needs to be used together with temporaryBlockScrollClass and temporaryBlockScrollTag on iOS.
    scrollviewIdiOSAndroid
    Typestring·Default"scrollview"
    The id of the scrollview.
    stickyiOSAndroid
    TypeReactElement<any, string | JSXElementConstructor<any>>
    Sticky item, designed for Tabs.
    styleiOSAndroidHarmony
    TypeCSSProperties
    style
    tabsItemWrapperClassiOSAndroid
    Typestring
    The class apply to the internal container of child view inside scroll-view.
    temporaryBlockScrollClassiOS
    Typestring·Default'BDXLynxViewPager'
    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
    Typenumber·Default0
    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
    Typeboolean
    Android-only temporary flag to control nested scroll; maps to native 'enable-nested-scroll'. Android default value is true.
    testingiOSAndroid
    Typeboolean
    Testing Mode.
    Events
    catchLongPressiOSAndroidHarmony
    Type(e: EventHandler<BaseTouchEvent<Target>> | undefined) => void
    Same as onLongPress, but stops the event from propagating to parent elements.
    catchTouchCanceliOSAndroidHarmony
    Type(e: TouchEvent) => void
    Same as onTouchCancel, but stops the event from propagating to parent elements.
    catchTouchEndiOSAndroidHarmony
    Type(e: TouchEvent) => void
    Same as onTouchEnd, but stops the event from propagating to parent elements.
    catchTouchMoveiOSAndroidHarmony
    Type(e: TouchEvent) => void
    Same as onTouchMove, but stops the event from propagating to parent elements.
    catchTouchStartiOSAndroidHarmony
    Type(e: TouchEvent) => void
    Same as onTouchStart, but stops the event from propagating to parent elements.
    onContentSizeChangeiOSAndroid
    Type(res: {detail: {scrollHeight: number, scrollWidth: number}}) => void
    Being triggered when scrolling content changes.
    onLayoutChangeiOSAndroidHarmony
    Type(e: EventHandler<LayoutChangeDetailEvent<Target>> | undefined) => void
    Send when UI has changed viewport size.
    onLongPressiOSAndroidHarmony
    Type(e: EventHandler<BaseTouchEvent<Target>> | undefined) => void
    Send when a touch-point is held on the UI for a period of time.
    onScrolliOSAndroid
    Type(e: ScrollEvent) => void
    Being triggered when scrolling occurs.
    onScrollEndiOSAndroid
    Type(e: ScrollEndEvent) => void·Defaultundefined
    Being triggered when scrolling stops.
    onScrollToLoweriOSAndroid
    Type(e: ScrollToLowerEvent) => void·Defaultundefined
    Being triggered when scrolling to lower.
    onScrollToUpperiOSAndroid
    Type(e: ScrollToUpperEvent) => void·Defaultundefined
    Being triggered when scrolling to upper.
    onTapiOSAndroidHarmony
    Type(e: EventHandler<BaseTouchEvent<Target>> | undefined) => void
    Send when a touch-point is tapped on the UI.
    onTouchCanceliOSAndroidHarmony
    Type(e: TouchEvent) => void
    Send when a touch event is interrupted or cancelled before it is completed.
    onTouchEndiOSAndroidHarmony
    Type(e: TouchEvent) => void
    Send when a touch-point is removed from the UI.
    onTouchMoveiOSAndroidHarmony
    Type(e: TouchEvent) => void
    Send when a touch-point is moving on the UI.
    onTouchStartiOSAndroidHarmony
    Type(e: TouchEvent) => void
    Send when a touch-point is placed on the UI.
    onWheel
    Type(e: CommonEvent) => void
    Send when a wheel event is triggered on the scroll-view.

    TabsItem

    childreniOSAndroidHarmony
    TypeReactNode
    The content of the tab item.
    classNameiOSAndroidHarmony
    Typestring
    className
    styleiOSAndroidHarmony
    TypeCSSProperties
    style
    tabKeyiOSAndroidHarmony
    Typestring
    TabsBar supplies this automatically to items rendered by renderTabItem. Set it for manually rendered items, matching the key derived from data.

    TabsPanel

    bouncesiOSAndroid
    Typeboolean·Defaulttrue
    Enable the native spring effect where supported.
    childreniOSAndroid
    Type(item: T, index: number) => ReactNode
    Render page content. Selection state is intentionally not passed, so a native swipe does not require React to rerender page content.
    classNameiOSAndroidHarmony
    Typestring
    className
    dataiOSAndroid
    Typereadonly T[]
    Data rendered as pages. ViewPager creates one direct native viewpager-item child for every entry.
    enableScrolliOSAndroid
    Typeboolean·Defaulttrue
    Enable horizontal swipe gestures.
    getItemKeyiOSAndroid
    Type(item: T, index: number) => string | number
    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
    Type(item: T, index: number) => ViewPagerItemProps
    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
    Typestring
    Identifier applied to the native ViewPager root.
    itemClassNameiOSAndroid
    Typestring
    Class name applied to every generated viewpager-item.
    itemStyleiOSAndroid
    TypeCSSProperties
    Style applied to every generated viewpager-item.
    lazyOptionsiOSAndroid
    TypeViewPagerLazyOptions
    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
    Type(event: ViewPagerOffsetChangeEvent) => void
    Main-thread scroll progress handler. Use a main thread function.
    main-thread:onPageChangeiOSAndroid
    Type(event: ViewPagerChangeEvent) => void
    Main-thread page completion handler. Use a main thread function.
    main-thread:onPageWillChangeiOSAndroid
    Type(event: ViewPagerWillChangeEvent) => void
    Main-thread page transition handler. Use a main thread function.
    onOffsetChangeiOSAndroid
    Type(event: ViewPagerOffsetChangeEvent) => void
    Native scroll progress event. Read its data from event.detail.
    onPageChangeiOSAndroid
    Type(event: ViewPagerChangeEvent) => void
    Native page completion event. Read the selected index from event.detail.index.
    onPageWillChangeiOSAndroid
    Type(event: ViewPagerWillChangeEvent) => void
    Native event before a page transition completes. Read its data from event.detail.
    styleiOSAndroidHarmony
    TypeCSSProperties
    style
    viewpagerPropsiOSAndroid
    TypeOmit<ViewPagerProps, children | className | style | id | bounces | ref | initial-select-index | align-width | enable-scroll | allow-horizontal-gesture | keep-item-view | bindchange | bindwillchange | bindoffsetchange | main-thread:bindchange | main-thread:bindwillchange | main-thread:bindoffsetchange>
    Native pager attributes not managed by the component.

    TabsIndicator

    childreniOSAndroidHarmony
    TypeReactNode
    children
    classNameiOSAndroidHarmony
    Typestring
    className
    indicatorPropsiOSAndroidHarmony
    TypeStandardProps
    Raw props passed to the indicator.
    styleiOSAndroidHarmony
    TypeCSSProperties
    style

    TabsRootRef

    selectTab
    Type(index: number, smooth: boolean) => void

    Supporting Types

    TabsIndicatorAnimation

    TabsIndicatorAnimation
    TypeTabsIndicatorAnimationSpring | TabsIndicatorAnimationTween

    TabsIndicatorAnimationSpring

    damping
    Typenumber
    The spring damping of the indicator motion.
    mass
    Typenumber
    The spring mass of the indicator motion.
    stiffness
    Typenumber
    The spring stiffness of the indicator motion.
    type
    Type"spring"
    Use a spring transition for indicator motion.
    velocity
    Typenumber
    The initial velocity of the spring animation.

    TabsIndicatorAnimationTween

    duration
    Typenumber
    The tween duration in milliseconds.
    ease
    Type(t: number) => number
    The easing function of the tween animation.
    type
    Type"tween"
    Use a tween transition for indicator motion.
    Except as otherwise noted, this work is licensed under a Creative Commons Attribution 4.0 International License, and code samples are licensed under the Apache License 2.0.