Skip to main content
Version: Next

ScrollView

The scrollable view area. When vertical scrolling is used, a fixed height must set for scroll-view via WXSS. The unit of length of the component's properties is px by default.

Tips: The ScrollView component in H5 is implemented by scrolling inside a container with a fixed height (or width), so it is important to set the height of the container correctly. For example, if the height of the ScrollView expands the body, there will be two scrollbars at the same time (the scrollbar under the body and the scrollbar of the ScrollView). If the ScrollView component in the WeChat mini program is set to scrollX horizontally and has multiple child elements (a single child element with a fixed width will scroll horizontally), you need to set white-space: nowrap with WXSS to ensure that the element does not change lines, and set display: inline-inline for the ScrollView internal elements with display: inline-block to make them scroll horizontally.

Reference

Type​

ComponentType<ScrollViewProps>

Examples​

export default class PageView extends Component {
  constructor() {
    super(...arguments)
  }

  onScrollToUpper() {}

  // or use arrow function
  // onScrollToUpper = () => {}

  onScroll(e){
    console.log(e.detail)
  }

  render() {
    const scrollStyle = {
      height: '150px'
    }
    const scrollTop = 0
    const Threshold = 20
    const vStyleA = {
      height: '150px',
      'background-color': 'rgb(26, 173, 25)'
    }
    const vStyleB = {
       height: '150px',
      'background-color': 'rgb(39,130,215)'
    }
    const vStyleC = {
      height: '150px',
      'background-color': 'rgb(241,241,241)',
      color: '#333'
    }
    return (
      <ScrollView
        className='scrollview'
        scrollY
        scrollWithAnimation
        scrollTop={scrollTop}
        style={scrollStyle}
        lowerThreshold={Threshold}
        upperThreshold={Threshold}
        onScrollToUpper={this.onScrollToUpper.bind(this)} // When using the arrow function, you can write it like `onScrollToUpper={this.onScrollToUpper}`
        onScroll={this.onScroll}
      >
        <View style={vStyleA}>A</View>
        <View style={vStyleB}>B</View>
        <View style={vStyleC}>C</View>
      </ScrollView>
    )
  }
}

ScrollViewProps​

PropertyTypeDefaultRequiredDescription
scrollXbooleanfasleNoSupports horizontal scrolling.
scrollYbooleanfasleNoSupports vertical scrolling.
upperThresholdnumber50NoSpecifies the distance from the top/left of the page when a scrolltoupper event is triggered.
lowerThresholdnumber50NoSpecifies the distance from the bottom/right of the page when a scrolltoupper event is triggered.
scrollTopnumberNoSpecifies the location of the vertical scroll bar.
scrollLeftnumberNoSpecifies the location of the horizontal scroll bar.
scrollIntoViewstringNoSpecifies the direction to which the scroll bar can be moved. Its value should be the ID of a child element (the ID cannot begin with a number), and this child element is scrolled in the direction specified in this property.
scrollWithAnimationbooleanfasleNoUses an animation for transition when setting the scroll bar.
enableBackToTopbooleanfasleNoEnables the scroll bar to return to the top when the top status bar is tapped on iOS or the title bar is double-tapped on Android. Only vertical scrolling is supported.
enableFlexbooleanfasleNoEnables the flexbox layout. When enabled, the current node with display: flex declared becomes a flex container and acts on its children.
scrollAnchoringbooleanfasleNoTurn on the scroll anchoring feature, which controls the scroll position from jittering as the content changes, only on iOS, see the CSS overflow-anchor property on Android.
refresherEnabledbooleanfasleNoEnable custom drop-down refresh.
refresherThresholdnumber45NoSet a custom drop-down refresh threshold.
refresherDefaultStylestring'black'否Set custom dropdown refresh default style, support black | white | none, none means don't use default style.
refresherBackgroundstring'#FFF'NoSet custom drop-down refresh area background color
refresherTriggeredbooleanfasleNoSet the current dropdown refresh status, true means the dropdown refresh has been triggered, false means the dropdown refresh has not been triggered.
onScrollToUpper(event: BaseEventOrigFunction<any>) => anyNoScrolling to the top/left will trigger the scrolltoupper event.
onScrollToLower(event: BaseEventOrigFunction<any>) => anyNoScrolling to the bottom/right will trigger the scrolltolower event.
onScroll(event: BaseEventOrigFunction<onScrollDetail>) => anyNoTriggered on scrolling.
event.detail = { scrollLeft, scrollTop, scrollHeight, scrollWidth, deltaX, deltaY}
onRefresherPulling(event: BaseEventOrigFunction<any>) => anyNoCustom dropdown refresh control is dropped.
onRefresherRefresh(event: BaseEventOrigFunction<any>) => anyNo
onRefresherRestore(event: BaseEventOrigFunction<any>) => anyNoCustom dropdown refresh is reset.
onRefresherAbort(event: BaseEventOrigFunction<any>) => anyNoCustom dropdown refresh is aborted.

Property Support​

PropertyWeChat Mini-ProgramBaidu Smart-ProgramAlipay Mini-ProgramByteDance Micro-AppH5React Native
ScrollViewProps.scrollX✔️✔️✔️✔️✔️✔️(二选一)
ScrollViewProps.scrollY✔️✔️✔️✔️✔️✔️(二选一)
ScrollViewProps.upperThreshold✔️✔️✔️✔️✔️✔️
ScrollViewProps.lowerThreshold✔️✔️✔️✔️✔️✔️
ScrollViewProps.scrollTop✔️✔️✔️✔️✔️✔️
ScrollViewProps.scrollLeft✔️✔️✔️✔️✔️✔️
ScrollViewProps.scrollIntoView✔️✔️✔️✔️✔️
ScrollViewProps.scrollWithAnimation✔️✔️✔️✔️✔️✔️
ScrollViewProps.enableBackToTop✔️✔️✔️
ScrollViewProps.enableFlex✔️
ScrollViewProps.scrollAnchoring✔️
ScrollViewProps.refresherEnabled✔️
ScrollViewProps.refresherThreshold✔️
ScrollViewProps.refresherDefaultStyle✔️
ScrollViewProps.refresherBackground✔️
ScrollViewProps.refresherTriggered✔️
ScrollViewProps.onScrollToUpper✔️✔️✔️✔️✔️✔️
ScrollViewProps.onScrollToLower✔️✔️✔️✔️✔️✔️
ScrollViewProps.onScroll✔️✔️✔️✔️✔️✔️
ScrollViewProps.onRefresherPulling✔️
ScrollViewProps.onRefresherRefresh✔️
ScrollViewProps.onRefresherRestore✔️
ScrollViewProps.onRefresherAbort✔️

onScrollDetail​

PropertyTypeDescription
scrollLeftnumberHorizontal scrollbar position.
scrollTopnumberVertical scrollbar position.
scrollHeightnumberScroll bar height
scrollWidthnumberScroll bar width
deltaXnumber
deltaYnumber