List - Vant 4
List
🚀 Create infinite scrolling experiences that keep users engaged and coming back for more!
📖 Intro
Build powerful infinite scrolling lists with intelligent loading management! The List component automatically handles pagination, loading states, and error handling, delivering smooth and responsive user experiences for content-heavy applications.
📦 Install
Get infinite scrolling up and running in seconds! Register the List component globally via app.use and start building engaging content experiences. Check out our Component Registration guide for additional setup options.
import { createApp } from'vue'; import { List } from'vant'; const app = createApp(); app.use(List);🎨 Usage
Master infinite scrolling with these powerful examples that showcase real-world scenarios
🌟 Basic Usage
Create your first infinite scrolling list with automatic loading and smooth pagination
import { ref } from'vue'; exportdefault { setup() { const list = ref([]); const loading = ref(false); const finished = ref(false); constonLoad = () => { 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
Handle network failures gracefully with built-in error states! When data loading fails, the List component automatically displays error messages and provides retry functionality, ensuring users never get stuck with broken content.
import { ref } from'vue'; exportdefault { setup() { const list = ref([]); const error = ref(false); const loading = ref(false); constonLoad = () => { fetchSomeThing().catch(() => { loading.value = false; error.value = true; }); }; return { list, error, onLoad, loading, }; }, };🔄 PullRefresh
Combine infinite scrolling with pull-to-refresh for the ultimate content experience! Users can refresh the entire list by pulling down, while still enjoying seamless infinite scrolling for new content.
import { ref } from'vue'; exportdefault { setup() { const list = ref([]); const loading = ref(false); const finished = ref(false); const refreshing = ref(false); constonLoad = () => { 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); }; constonRefresh = () => { finished.value = false; loading.value = true; onLoad(); }; return { list, onLoad, loading, finished, onRefresh, refreshing, }; }, };🔧 API
Fine-tune your infinite scrolling experience with comprehensive configuration options
🎛️ Props
Customize every aspect of list behavior to create the perfect scrolling experience
| 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* |
| 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 |
| disabled | Whether to disable the load event | boolean | false |
| direction | Scroll direction, can be set to up | string | down |
scroller v4.6.4 | Specifies the node that needs to listen for scroll events, defaults to the nearest parent scroll node | Element | - |
📡 Events
React to user interactions and loading states with powerful event handling
| Event | Description | Arguments |
|---|---|---|
| load | Emitted when the distance between the scrollbar and the bottom is less than offset | - |
⚙️ Methods
Programmatically control list behavior with instance methods. Use ref to get List instance and call instance methods.
| Name | Description | Attribute | Return value |
|---|---|---|---|
| check | Check scroll position | - | - |
📝 Types
Leverage TypeScript for type-safe list development. The component exports the following type definitions:
importtype { ListProps, ListInstance, ListDirection } from'vant';ListInstance is the type of component instance:
import { ref } from'vue'; importtype { ListInstance } from'vant'; const listRef = ref<ListInstance>(); listRef.value?.check();🎰 Slots
Customize loading states and content with flexible slot system
| Name | Description |
|---|---|
| default | List content |
| loading | Custom loading tips |
| finished | Custom finished tips |
| error | Custom error tips |
🎨 Theming
Create stunning visual experiences with powerful theming capabilities
🎯 CSS Variables
Customize every visual aspect of your lists to match your brand perfectly. 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-text-color-2) | - |
| --van-list-text-font-size | var(--van-font-size-md) | - |
| --van-list-text-line-height | 50px | - |
| --van-list-loading-icon-size | 16px | - |
❓ FAQ
Get answers to common questions and troubleshooting tips for optimal list performance
How does List component work?
List will listen to the scroll event of the browser and calculate the position. When the distance between the bottom of the list and the visible area is less than offset, the List component will trigger a load event.
Why does the load event triggered immediately after mounted?
A load event will be triggered immediately to load the first screen data. This feature can be disabled by the immediate-check prop.
Why does the load event triggered continuously?
If the amount of data loaded in one request is too small, the List will continue to trigger the load event until the content fills the screen or the data is fully loaded.
Therefore, you need to adjust the amount of data per request. Ideally, the amount of data per request should be able to fill the height of one screen.
What is the meaning of loading and finished?
List has three states, understanding these states will help you use the component:
loading = false: Not in loading. The component will detect whether to trigger theloadevent according to the scroll position (if the content of the list is less than one screen, it will be triggered directly).loading = true: During loading. Indicating that an request is being sent, and theloadevent will not be triggered.finished = true: Loading is complete. Noloadwill not be triggered.
After each request, you need to manually set loading to false, indicating the end of loading.
Always trigger loading after using float layout?
If you use the float layout on the content, you can add the van-clearfix class to the container to clear the float, so that the List can get the element position correctly.
Always trigger loading after setting overflow on html and body?
If the overflow-x: hidden style is set on the html and body tags, it will cause the List to always trigger loading.
html, body { overflow-x: hidden; }The reason is that when an element is styled with overflow-x: hidden, the element's overflow-y will be set to auto by the browser, instead of the default value of visible, causing the List can not determine the scroll container correctly. The workaround is to remove this style, or add the height: 100% style to the html and body tags.
Always trigger loading when the direction prop is set to up?
Setting the direction prop to up will trigger the loading of the List component when the scrollbar is at the page top.
When using this prop, it is recommended to scroll the scroll bar to the page bottom after each data request is completed.
📚 Related Docs
Explore related components and features to enhance your infinite scrolling experience
- 🚀 Lazyload - Lazy loading for images and components
- 📱 Cell - Perfect list item component
- 🔍 Search - Add search functionality to lists
- 📊 IndexBar - Quick navigation for long lists
- 📖 Quick Start - Get started with Vant
- ❓ FAQ - Common questions and solutions