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/scroll-coordinator.md.
lynx-ui logo
lynx-ui
  • English
  • ScrollCoordinator

    A headless collapsible header that coordinates scrolling with nested lists, scroll views, and paged content in ReactLynx.
    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

    Coordinate a collapsible header, persistent toolbar, and vertical list.

    Examples

    Refresh Coordinator

    Add pull-to-refresh to the whole coordinator with imperative start and finish controls.

    Refresh Page

    Give each paged feed its own pull-to-refresh lifecycle inside the coordinator.

    ViewPager

    Share a collapsible header and toolbar across horizontally paged vertical lists.

    ViewPager List

    Synchronize tabs, a pager, and nested lists within one coordinated scroll surface.

    Structure

    <ScrollCoordinator headers={<Header />} slot={<Content />} />

    Component API

    ScrollCoordinator

    Coordinates a collapsible header with nested vertical lists or scroll views.

    bouncesiOS
    Typeboolean·Defaultfalse
    Enable bounce on supported platforms. Outer refresh always enables it unless popupOptions disables it.
    classNameiOSAndroidHarmony
    Typestring
    className
    coordinatorPropsiOSAndroid
    TypeOmit<ScrollCoordinatorProps, ref | children | id | style | className>
    Native properties passed explicitly to the coordinator. Managed properties take precedence.
    enableScrolliOSAndroid
    Typeboolean·Defaulttrue
    Enable vertical coordinator scrolling.
    granularityiOSAndroid
    Typenumber·Default0.01
    Offset event granularity as a fraction of the collapse range. Also sets the sticky threshold.
    headerOverSlotiOSAndroid
    Typeboolean·Defaultfalse
    Place the overflowing header above the slot.
    headersiOSAndroid
    TypeReactNode
    Collapsible header content.
    idiOSAndroid
    Typestring
    Optional native coordinator ID. Imperative methods use instance-local node refs.
    main-thread:gestureiOSAndroid
    TypeBaseGesture<BaseGestureConfig, GestureChangeEvent>
    Native gesture attached to the coordinator.
    main-thread:onOffsetChangeiOSAndroid
    Type(event: ScrollCoordinatorOffset) => void
    Header offset callback on the main thread. Pass a function with the 'main thread' directive.
    onLeaveStickyiOSAndroid
    Type() => void
    Called once when the header leaves the sticky threshold.
    onOffsetChangeiOSAndroid
    Type(event: ScrollCoordinatorOffset) => void
    Header offset and total collapse range, in px.
    onStickyiOSAndroid
    Type() => void
    Called once when the header reaches the sticky threshold.
    popupOptionsiOSAndroid
    Type{enableHalfToFullScreen: boolean, name: string}
    Native host popup integration for hosts that support half-to-full-screen expansion.
    refreshInSlotiOSAndroid
    Typeboolean·Defaultfalse
    Use independent refresh elements inside the slot. Each nested refresh must finish its own refresh through its ref; finishRefresh only affects the outer wrapper.
    refreshOptionsiOSAndroid
    Typefalse | ScrollCoordinatorRefreshOptions·Defaultfalse
    Configure outer native refresh. Enabled outer refresh takes precedence over refreshInSlot. Providing an options object mounts the refresh wrapper, even while enableRefresh is false. className and style apply to this wrapper; otherwise they apply to the native coordinator. No implementation mode is required.
    scrollBarEnableiOSAndroid
    Typeboolean·Defaultfalse
    Show the coordinator scrollbar on supported platforms.
    scrollWithNativeAndroid
    Typeboolean·Defaultfalse
    Participate as a nested scrolling child of a native Android container.
    slotiOSAndroid
    TypeReactNode
    Content below the header, typically a vertical List, ScrollView, or ViewPager of lists.
    styleiOSAndroidHarmony
    TypeCSSProperties
    style
    toolbariOSAndroid
    TypeReactNode
    Persistent toolbar. Its height is subtracted from the header's collapse range.

    State-based styling & rendering

    This component exposes runtime states through one or both of the following channels. The table lists only the channels available for each state:

    • UI variant class — when supported, a class like ui-<state> is toggled on the corresponding component node for selectors such as .ui-<state> { ... }.
    • Render-prop field — when supported and children is a function, the state is passed in via children({ <state>: boolean, ... }) for runtime-driven rendering.

    UI variants applied by ScrollCoordinator.

    Class NameDescription
    ui-stickyApplied to the coordinator and outer refresh wrapper while the header is collapsed.

    ScrollCoordinatorRef

    finishRefreshiOSAndroid
    Type() => void
    End the outer refresh, including after a failed request. An existing refresh can still finish after enableRefresh becomes false. Does not reset list offsets.
    scrollIntoViewiOSAndroid
    Type(id: string, animated: boolean, success?: (result: unknown) => void, fail?: (result: unknown) => void) => void
    Scroll to an element inside headers, measured relative to this instance's header.
    scrollToiOSAndroid
    Type(offset: px | rpx, animated: boolean, success?: (result: unknown) => void, fail?: (result: unknown) => void) => void
    Set the header offset. The native coordinator clamps it to the scrollable range.
    scrollToStickyiOSAndroid
    Type(animated: boolean, success?: (result: unknown) => void, fail?: (result: unknown) => void) => void
    Collapse the header to its sticky position.
    scrollToTopiOSAndroid
    Type(animated: boolean, success?: (result: unknown) => void, fail?: (result: unknown) => void) => void
    Expand the header. Does not reset the nested list's own scroll position.
    startRefreshiOSAndroid
    Type() => void
    Start the outer refresh through its native node. Requires enableRefresh. onStartRefresh reports triggeredBy: 'startRefresh'. Does not control slot refresh instances.

    Supporting Types

    ScrollCoordinatorOffset

    heightiOSAndroidHarmony
    Typenumber
    The absolute value of the scrollable distance (header height - toolbar height), in px
    offsetiOSAndroidHarmony
    Typenumber
    The absolute value of the header scroll offset, in px

    ScrollCoordinatorRefreshOptions

    Native refresh options with the same callback shapes as FeedList.

    enableRefreshiOSAndroid
    Typeboolean
    Allow pull gestures and startRefresh() to start the outer refresh. Toggle this flag to preserve the mounted content and its scroll position.
    headerContentiOSAndroid
    TypeReactNode
    Refresh header content. Give it a nonzero height to define the pull threshold. Keep its dimensions stable while refreshing to avoid resetting the native header position.
    onHeaderReleasediOSAndroid
    Type(event: {headerSize: number, offset: number}) => void
    The native header was released. Reports the latest offset and measured height in px.
    onRefreshOffsetChangeiOSAndroid
    Type(event: {headerSize: number, isDragging: boolean, offset: number}) => void
    Pull offset and measured header height in px. The height is zero until layout. Progress is offset / headerSize when headerSize > 0, and may exceed 1.
    onRefreshStateChangeiOSAndroid
    Type(event: {state: number}) => void
    Native state: 0 idle, 1 released past the threshold, 2 refreshing. Event order is platform-dependent. Use isDragging from the offset event for drag state.
    onStartRefreshiOSAndroid
    Type(event: {triggeredBy: startRefresh | drag}) => void
    Start loading data. Always call ref.finishRefresh() when the request settles. Returning a Promise does not automatically end the refresh.
    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.