vant/src/list

List

Intro

A list component to show items and control loading status.

Install

Register component globally via app.use, refer to Component Registration for more registration ways.

import { createApp } from 'vue';
import { List } from 'vant';

const app = createApp();
app.use(List);

Usage

Basic Usage

<van-list
  v-model:loading="state.loading"
  :finished="state.finished"
  finished-text="Finished"
  @load="onLoad"
>
  <van-cell v-for="item in state.list" :key="item" :title="item" />
</van-list>

import { reactive } from 'vue';

export default {
  setup() {
    const state = reactive({
      list: [],
      loading: false,
      finished: false,
    });

    const onLoad = () => {
      setTimeout(() => {
        for (let i = 0; i < 10; i++) {
          state.list.push(state.list.length + 1);
        }
        state.loading = false;

        if (state.list.length >= 40) {
          state.finished = true;
        }
      }, 1000);
    };

    return {
      state,
      onLoad,
    };
  },
};

Error Info

<van-list
  v-model:loading="state.loading"
  v-model:error="state.error"
  error-text="Request failed. Click to reload"
  @load="onLoad"
>
  <van-cell v-for="item in state.list" :key="item" :title="item" />
</van-list>

import { reactive } from 'vue';

export default {
  setup() {
    const state = reactive({
      list: [],
      error: false,
      loading: false,
    });

    const onLoad = () => {
      fetchSomeThing().catch(() => {
        state.error = true;
      });
    };

    return {
      state,
      onLoad,
    };
  },
};

PullRefresh

<van-pull-refresh v-model="state.refreshing" @refresh="onRefresh">
  <van-list
    v-model:loading="state.loading"
    :finished="state.finished"
    finished-text="Finished"
    @load="onLoad"
  >
    <van-cell v-for="item in state.list" :key="item" :title="item" />
  </van-list>
</van-pull-refresh>

import { reactive } from 'vue';

export default {
  setup() {
    const state = reactive({
      list: [],
      loading: false,
      finished: false,
      refreshing: false,
    });

    const onLoad = () => {
      setTimeout(() => {
        if (state.refreshing) {
          state.list = [];
          state.refreshing = false;
        }

        for (let i = 0; i < 10; i++) {
          state.list.push(state.list.length + 1);
        }
        state.loading = false;

        if (state.list.length >= 40) {
          state.finished = true;
        }
      }, 1000);
    };

    const onRefresh = () => {
      state.finished = false;
      state.loading = true;
      onLoad();
    };

    return {
      state,
      onLoad,
      onRefresh,
    };
  },
};

API

Props

Attribute	Description	Type	Default
v-model:loading	Whether to show loading info，the load event will not be Emitted when loading	boolean	false
v-model:error	Whether loading is error，the load event will be Emitted only when error text clicked	boolean	false
finished	Whether loading is finished，the load event will not be Emitted when finished	boolean	false
offset	The load event will be Emitted when the distance between the scrollbar and the bottom is less than offset	number | string	300
loading-text	Loading text	string	Loading...
finished-text	Finished text	string	-
error-text	Error loaded text	string	-
immediate-check	Whether to check loading position immediately after mounted	boolean	true
direction	Scroll direction，can be set to up	string	down

Events

Event	Description	Arguments
load	Emitted when the distance between the scrollbar and the bottom is less than offset	-

Methods

Use ref to get List instance and call instance methods.

Name	Description	Attribute	Return value
check	Check scroll position	-	-

Slots

Name	Description
default	List content
loading	Custom loading tips
finished	Custom finished tips
error	Custom error tips

Less Variables

How to use: Custom Theme.

Name	Default Value	Description
@list-text-color	@gray-6	-
@list-text-font-size	@font-size-md	-
@list-text-line-height	50px	-
@list-loading-icon-size	16px	-