Van Address List

Vant AddressList Component

Display a list of receiving addresses with selection, editing, and management features.

When to Invoke

Invoke this skill when:

• User needs to display a list of addresses
• User wants to implement address selection functionality
• User needs to manage multiple addresses (add, edit, delete)
• User wants to show disabled/unavailable addresses
• User asks about default address handling
• User needs address list with radio selection

Features

• Address Display: Show multiple addresses in a list format
• Address Selection: Single or multiple address selection support
• Default Address: Visual indicator for default address
• Disabled Addresses: Support for showing unavailable addresses
• Edit Actions: Built-in edit button for each address
• Add Button: Quick access to add new address
• Customizable: Custom content via slots

API Reference

Props

Events

Address Data Structure

Slots

Types

import type { AddressListProps, AddressListAddress } from 'vant';

Usage Examples

Basic Usage

<template>
  <van-address-list
    v-model="chosenAddressId"
    :list="list"
    :disabled-list="disabledList"
    disabled-text="The following address is out of range"
    default-tag-text="Default"
    @add="onAdd"
    @edit="onEdit"
    @select="onSelect"
  />
</template>

<script setup>
import { ref } from 'vue';
import { showToast } from 'vant';

const chosenAddressId = ref('1');

const list = ref([
  {
    id: '1',
    name: 'John Snow',
    tel: '13000000000',
    address: 'Somewhere in Beijing',
    isDefault: true,
  },
  {
    id: '2',
    name: 'Ned Stark',
    tel: '13100000000',
    address: 'Somewhere in Shanghai',
    isDefault: false,
  },
]);

const disabledList = ref([
  {
    id: '3',
    name: 'Tywin Lannister',
    tel: '13200000000',
    address: 'Somewhere in Guangzhou',
  },
]);

const => {
  showToast('Add new address');
};

const index) => {
  showToast(`Edit address: ${index}`);
};

const index) => {
  showToast(`Selected: ${item.name}`);
};
</script>

Multiple Selection

<template>
  <van-address-list
    v-model="selectedIds"
    :list="list"
    @select="onSelect"
  />
</template>

<script setup>
import { ref } from 'vue';

const selectedIds = ref(['1', '2']);

const list = ref([
  { id: '1', name: 'John', tel: '13000000000', address: 'Beijing' },
  { id: '2', name: 'Jane', tel: '13100000000', address: 'Shanghai' },
  { id: '3', name: 'Bob', tel: '13200000000', address: 'Guangzhou' },
]);

const => {
  console.log('Selected:', item);
};
</script>

With Custom Content

<template>
  <van-address-list
    v-model="chosenAddressId"
    :list="list"
    default-tag-text="Default"
    @add="onAdd"
    @edit="onEdit"
  >
    <template #top>
      <van-notice-bar>Please select a delivery address</van-notice-bar>
    </template>
    <template #item-bottom="{ item }">
      <div class="address-time">
        Last used: {{ item.lastUsed }}
      </div>
    </template>
  </van-address-list>
</template>

<script setup>
import { ref } from 'vue';

const chosenAddressId = ref('1');

const list = ref([
  {
    id: '1',
    name: 'John Snow',
    tel: '13000000000',
    address: 'Beijing',
    lastUsed: '2024-01-15',
  },
]);

const => console.log('Add');
const => console.log('Edit:', item);
</script>

Without Add Button

<template>
  <van-address-list
    v-model="chosenAddressId"
    :list="list"
    :show-add-button="false"
    @select="onSelect"
  />
</template>

<script setup>
import { ref } from 'vue';

const chosenAddressId = ref('1');
const list = ref([
  { id: '1', name: 'John', tel: '13000000000', address: 'Beijing' },
]);

const => {
  console.log('Selected:', item);
};
</script>

With Custom Right Icon

<template>
  <van-address-list
    v-model="chosenAddressId"
    :list="list"
    right-icon="arrow"
    @click-item="onClickItem"
  />
</template>

<script setup>
import { ref } from 'vue';

const chosenAddressId = ref('1');
const list = ref([
  { id: '1', name: 'John', tel: '13000000000', address: 'Beijing' },
]);

const index, { event }) => {
  console.log('Clicked:', item);
};
</script>

Non-Switchable Mode

<template>
  <van-address-list
    v-model="chosenAddressId"
    :list="list"
    :switchable="false"
    @edit="onEdit"
  />
</template>

<script setup>
import { ref } from 'vue';

const chosenAddressId = ref('1');
const list = ref([
  { id: '1', name: 'John', tel: '13000000000', address: 'Beijing' },
]);

const => {
  console.log('Edit:', item);
};
</script>

Best Practices

1. Default Address: Mark one address as default using isDefault property
2. Disabled Addresses: Use disabled-list for addresses that cannot be used
3. User Feedback: Provide clear feedback when address is selected or edited
4. Empty State: Handle empty list gracefully with appropriate UI
5. Address Validation: Validate address data before displaying
6. Performance: For large lists, consider pagination or virtual scrolling