# <scroller>

# Summary

Scroller is a component which can have multiple child components in one column. It supports both direcitons. If the content size of child components exceeds the frame of the scroller, the whole child components will be scrollable.

Notes: A <scroller> can be used as a root element or a embed element. The scroll direction of this component is column, and it can't be changed.

# Child Components

Scroller supports all kinds of components, such as div, text, etc. There are two special components that can only be used inside scroller component.

  • refresh 0.6.1 used inside list to add pull-down-to-refresh functionality.
  • loading 0.6.1 used inside list to add pull-up-to-load-more functionality.

# Attributes

  • show-scrollbar: <boolean> true | false, default value is true. This attribute indicates whether show the scroll bar or not.
  • scroll-direction: <string> the scroll direction of component, horizontal or vertical.
    • scroll-direction defines the scrollable axis of scroller and flex-direction defines the layout axis of scroller. scroll-direction and flex-direction must be set to the same direction, otherwise, undefined behavior may happen.
    • Default value for scroll-direction is vertical, and for flex-direction is row .
    • Use scroll-direction:horizontal and flex-direction: row when a horizontal layout and scrollable scroller is expected.
    • Use scroll-direction:vertical and flex-direction: column when a vertical layout and scrollable scroller is expected. But those two values are default, if you don't set them, it also works fine.
  • loadmoreoffset : <number> default value is 0. The loadmore event will be triggered when the list is loadmoreoffset left to reach the bottom. e.g. A list has total content length of 1000, and the loadmoreoffset is set to 400, the loadmore event will be triggered when 600 has beed scrolled and there is less than 400 left.
  • loadmoreretry : <number> default value 0,whether to reset loadmore related UI when loadmore failed, will be deprecated in further release.
  • offset-accuracy:<number> default value is 0, the vertical offset distance required to trigger the scroll event.
  • scrollToBegin : <string> * if scrooler has attr scrollToBegin=false,then scroller will not scroller to begin position auto when content layout change. default is true just for android

# Styles

common styles: check out common styles for components

  • support flexbox related styles
  • support box model related styles
  • support position related styles
  • support opacity, background-color etc.

# Events

common events: check out the common events

  • support click event. Check out common events

  • support appear / disappear event. Check out common events

  • support loadmore event. The loadmore event should be used in concert with loadmoreoffset. If the view has less than loadmoreoffset to scroll down, the event will be triggered.See details in example.

  • support scroll event 0.12+ .The scroll should be used in concert with offset-accuracy. This event is fired when the list scrolls. The current contentOffset value is given in this event callback. See details in example.

  • support scrollstart and scrollend event 0.17+ .These events are fired when the list begins or ends scrolling.The current contentSize and contentOffset value are given in this event callback. See details in example

# Restrictions

Nested lists or scrollers within the same direction are not supported. In other words. nested list/scroller must have different directions. For example, a vertical list nested in a vertical list or scroller is not allowed. However, a vertical list nested in a horizontal list or scroller is legal.

# Vue Example

  <div class="wrapper">
    <scroller class="scroller">
      <div class="row" v-for="(name, index) in rows" :ref="'item'+index">
        <text class="text" :ref="'text'+index">{{name}}</text>
    <div class="group">
      <text @click="goto10" class="button">Go to 10</text>
      <text @click="goto20" class="button">Go to 20</text>

  const dom = weex.requireModule('dom')

  export default {
    data () {
      return {
        rows: []
    created () {
      for (let i = 0; i < 30; i++) {
        this.rows.push('row ' + i)
    methods: {
      goto10 (count) {
        const el = this.$refs.item10[0]
        dom.scrollToElement(el, {})
      goto20 (count) {
        const el = this.$refs.item20[0]
        dom.scrollToElement(el, { offset: 0 })

<style scoped>
  .scroller {
    width: 700px;
    height: 700px;
    border-width: 3px;
    border-style: solid;
    border-color: rgb(162, 217, 192);
    margin-left: 25px;
  .row {
    height: 100px;
    flex-direction: column;
    justify-content: center;
    padding-left: 30px;
    border-bottom-width: 2px;
    border-bottom-style: solid;
    border-bottom-color: #DDDDDD;
  .text {
    font-size: 45px;
    color: #666666;
  .group {
    flex-direction: row;
    justify-content: center;
    margin-top: 60px;
  .button {
    width: 200px;
    padding-top: 20px;
    padding-bottom: 20px;
    font-size: 40px;
    margin-left: 30px;
    margin-right: 30px;
    text-align: center;
    color: #41B883;
    border-width: 2px;
    border-style: solid;
    border-color: rgb(162, 217, 192);
    background-color: rgba(162, 217, 192, 0.2);

try it

# Rax Example

rax-scrollview is the component <scroller> of rax, which can run in web and weex.

import { createElement, render } from 'rax';
import Driver from "driver-universal"
import View from 'rax-view';
import ScrollView from 'rax-scrollview';

function Thumb() {
  return (
    <View style={styles.button}>
      <View style={styles.box} />

let THUMBS = [];
for (let i = 0; i < 20; i++) THUMBS.push(i);
let createThumbRow = (val, i) => <Thumb key={i} />;

function App () {
  return (
    <View style={{ ...styles.container, ...{ height: 500 } }}>

let styles = {
  container: {
    padding: 20,
    borderStyle: 'solid',
    borderColor: '#dddddd',
    borderWidth: 1,
    marginLeft: 20,
    marginRight: 20,
    marginBottom: 10,
  button: {
    margin: 7,
    padding: 5,
    alignItems: 'center',
    backgroundColor: '#eaeaea',
    borderRadius: 3,
  box: {
    width: 64,
    height: 64,

render(<App />, document.body, { driver: Driver });

rax-scrollview doc

Last Updated: 8/15/2022
Excellent docUnusable doc