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="loading"
  :finished="finished"
  finished-text="Finished"
  @load="onLoad"
>
  <van-cell v-for="item in list" :key="item" :title="item" />
</van-list>

import { ref } from 'vue';

export default {
  setup() {
    const list = ref([]);
    const loading = ref(false);
    const finished = ref(false);

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

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

    return {
      list,
      onLoad,
      loading,
      finished,
    };
  },
};

Error Info

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

import { ref } from 'vue';

export default {
  setup() {
    const list = ref([]);
    const error = ref(false);
    const loading = ref(false);
    const onLoad = () => {
      fetchSomeThing().catch(() => {
        error.value = true;
      });
    };

    return {
      list,
      error,
      onLoad,
      loading,
    };
  },
};

PullRefresh

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

import { ref } from 'vue';

export default {
  setup() {
    const list = ref([]);
    const loading = ref(false);
    const finished = ref(false);
    const refreshing = ref(false);

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

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

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

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

    return {
      list,
      onLoad,
      loading,
      finished,
      onRefresh,
      refreshing,
    };
  },
};

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	-	-

Types

Get the type definition of the List instance through ListInstance.

import { ref } from 'vue';
import type { ListInstance } from 'vant';

const listRef = ref<ListInstance>();

listRef.value?.check();

Slots

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

CSS Variables

The component provides the following CSS variables, which can be used to customize styles. Please refer to ConfigProvider component.

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