List

Demos

How to import

<script setup lang="ts">
    import { List, ListItem } from '@fibrous/semi-ui-vue';
</script>

In templates, ListItem can also be written as List.Item.

Basic Usage

You can use size to size list. Supported values include large, default, small. Customize the header and footer with the #header and #footer slots, and render each entry of dataSource with the #item="{ item, index }" scoped slot.

Default Size

Header

从明天起，做一个幸福的人
喂马，劈柴，周游世界
从明天起，关心粮食和蔬菜
我有一所房子，面朝大海，春暖花开

Footer

Small Size

Header

从明天起，做一个幸福的人
喂马，劈柴，周游世界
从明天起，关心粮食和蔬菜
我有一所房子，面朝大海，春暖花开

Footer

Large Size

Header

从明天起，做一个幸福的人
喂马，劈柴，周游世界
从明天起，关心粮食和蔬菜
我有一所房子，面朝大海，春暖花开

Footer

Code

<script setup lang="ts">
    import { List, ListItem } from '@fibrous/semi-ui-vue';

    const data = ['从明天起，做一个幸福的人', '喂马，劈柴，周游世界', '从明天起，关心粮食和蔬菜', '我有一所房子，面朝大海，春暖花开'];
</script>

<template>
    <div>
        <div :style="{ marginRight: '16px' }">
            <h3 :style="{ marginBottom: '16px' }">Default Size</h3>
            <List bordered :dataSource="data">
                <template #header>
                    <div>Header</div>
                </template>
                <template #footer>
                    <div>Footer</div>
                </template>
                <template #item="{ item }">
                    <ListItem>{{ item }}</ListItem>
                </template>
            </List>
        </div>
        <div :style="{ marginRight: '16px' }">
            <h3 :style="{ margin: '16px 0' }">Small Size</h3>
            <List bordered :dataSource="data" size="small">
                <template #header>
                    <div>Header</div>
                </template>
                <template #footer>
                    <div>Footer</div>
                </template>
                <template #item="{ item }">
                    <ListItem>{{ item }}</ListItem>
                </template>
            </List>
        </div>
        <div :style="{ marginRight: '16px' }">
            <h3 :style="{ margin: '16px 0' }">Large Size</h3>
            <List bordered :dataSource="data" size="large">
                <template #header>
                    <div>Header</div>
                </template>
                <template #footer>
                    <div>Footer</div>
                </template>
                <template #item="{ item }">
                    <ListItem>{{ item }}</ListItem>
                </template>
            </List>
        </div>
    </div>
</template>

Template

List.Item has a built-in template provided through the #header, #main and #extra slots. The alignment of header and main set by align properties using one of flex-start(default), flex-end, center, baseline, and stretch .

SE
示例标题
Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统。设计系统包含设计语言以及一整套可复用的前端组件，帮助设计师与开发者更容易地打造高质量的、用户体验一致的、符合设计规范的 Web 应用。
SE
示例标题
Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统。设计系统包含设计语言以及一整套可复用的前端组件，帮助设计师与开发者更容易地打造高质量的、用户体验一致的、符合设计规范的 Web 应用。
SE
示例标题
Semi Design 以用户中心、内容优先、设计人性化的设计系统，打造一致、好看、好用、高效的用户体验。

Code

<script setup lang="ts">
    import { Avatar, Button, ButtonGroup, List } from '@fibrous/semi-ui-vue';

    const text = 'Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统。设计系统包含设计语言以及一整套可复用的前端组件，帮助设计师与开发者更容易地打造高质量的、用户体验一致的、符合设计规范的 Web 应用。';

    const data = [
        {
            text,
            style: {
                color: 'var(--semi-color-text-2)',
                margin: '4px 0',
                width: '420px',
                whiteSpace: 'nowrap',
                overflow: 'hidden',
                textOverflow: 'ellipsis',
            },
        },
        { text, style: { color: 'var(--semi-color-text-2)', margin: '4px 0', width: '500px' } },
        {
            text: 'Semi Design 以用户中心、内容优先、设计人性化的设计系统，打造一致、好看、好用、高效的用户体验。',
            style: { color: 'var(--semi-color-text-2)', margin: '4px 0', width: '500px' },
        },
    ];
</script>

<template>
    <div :style="{ padding: '12px', border: '1px solid var(--semi-color-border)', margin: '12px' }">
        <List :dataSource="data">
            <template #item="{ item }">
                <List.Item>
                    <template #header>
                        <Avatar color="blue">SE</Avatar>
                    </template>
                    <template #main>
                        <div>
                            <span :style="{ color: 'var(--semi-color-text-0)', fontWeight: 500 }">示例标题</span>
                            <p :style="item.style">{{ item.text }}</p>
                        </div>
                    </template>
                    <template #extra>
                        <ButtonGroup theme="borderless">
                            <Button>编辑</Button>
                            <Button>更多</Button>
                        </ButtonGroup>
                    </template>
                </List.Item>
            </template>
        </List>
    </div>
</template>

Layout

Use layout property to set list layout, one of vertical(default) or horizontal.

SE
Semi Design Title 1
Semi Design 设计系统包含设计语言以及一整套可复用的前端组件，帮助设计师与开发者更容易地打造高质量的、用户体验一致的、符合设计规范的 Web 应用。
SE
Semi Design Title 2
Semi Design 设计系统包含设计语言以及一整套可复用的前端组件，帮助设计师与开发者更容易地打造高质量的、用户体验一致的、符合设计规范的 Web 应用。
SE
Semi Design Title 3
Semi Design 设计系统包含设计语言以及一整套可复用的前端组件，帮助设计师与开发者更容易地打造高质量的、用户体验一致的、符合设计规范的 Web 应用。

Code

<script setup lang="ts">
    import { Avatar, List, ListItem, type AvatarColor } from '@fibrous/semi-ui-vue';

    interface Item {
        title: string;
        color: AvatarColor;
    }

    const data: Item[] = [
        { title: 'Semi Design Title 1', color: 'light-blue' },
        { title: 'Semi Design Title 2', color: 'grey' },
        { title: 'Semi Design Title 3', color: 'light-green' },
    ];
</script>

<template>
    <div :style="{ padding: '12px', border: '1px solid var(--semi-color-border)', margin: '12px' }">
        <List :dataSource="data" layout="horizontal">
            <template #item="{ item }">
                <ListItem>
                    <template #header>
                        <Avatar :color="item.color">SE</Avatar>
                    </template>
                    <template #main>
                        <div>
                            <span :style="{ color: 'var(--semi-color-text-0)', fontWeight: 500 }">{{ item.title }}</span>
                            <p :style="{ color: 'var(--semi-color-text-2)', margin: '4px 0' }">Semi Design 设计系统包含设计语言以及一整套可复用的前端组件，帮助设计师与开发者更容易地打造高质量的、用户体验一致的、符合设计规范的 Web 应用。</p>
                        </div>
                    </template>
                </ListItem>
            </template>
        </List>
    </div>
</template>

Grid

Use grid property to set grid layout. Use span to set the number of occupying spaces for each item and gutter for spacing between items.

Semi UI

满意度
反馈数	124

Semi DSM

满意度
反馈数	108

Semi D2C

满意度
反馈数	244

Code

<script setup lang="ts">
    import { Button, ButtonGroup, Descriptions, DescriptionsItem, List, ListItem, Rating } from '@fibrous/semi-ui-vue';

    const data = [
        { title: 'Semi UI', rating: 4.5, feedbacks: 124 },
        { title: 'Semi DSM', rating: 4, feedbacks: 108 },
        { title: 'Semi D2C', rating: 4.5, feedbacks: 244 },
    ];

    const grid = { gutter: 12, span: 6 };

    const itemStyle = {
        border: '1px solid var(--semi-color-border)',
        backgroundColor: 'var(--semi-color-bg-2)',
        borderRadius: '3px',
        paddingLeft: '20px',
    };
</script>

<template>
    <div>
        <List :dataSource="data" :grid="grid">
            <template #item="{ item }">
                <ListItem :style="itemStyle">
                    <div>
                        <h3 :style="{ color: 'var(--semi-color-text-0)', fontWeight: 500 }">{{ item.title }}</h3>
                        <Descriptions align="center" row size="small">
                            <DescriptionsItem>
                                <template #itemKey>满意度</template>
                                <Rating allowHalf :modelValue="item.rating" size="small" />
                            </DescriptionsItem>
                            <DescriptionsItem>
                                <template #itemKey>反馈数</template>
                                {{ item.feedbacks }}
                            </DescriptionsItem>
                        </Descriptions>
                        <div :style="{ margin: '12px 0', display: 'flex', justifyContent: 'flex-end' }">
                            <ButtonGroup :style="{ marginTop: '8px' }" theme="borderless">
                                <Button>编辑</Button>
                                <Button>更多</Button>
                            </ButtonGroup>
                        </div>
                    </div>
                </ListItem>
            </template>
        </List>
    </div>
</template>

Responsive List

Refer to Grid for responsive dimensions.

审核管理平台

满意度
反馈数	124

扁鹊

满意度
反馈数	108

直播审核平台

满意度
反馈数	244

抖音安全测试

满意度
反馈数	189

内容平台

满意度
反馈数	128

策略平台

满意度
反馈数	156

Code

<script setup lang="ts">
    import { Button, ButtonGroup, Descriptions, DescriptionsItem, List, Rating } from '@fibrous/semi-ui-vue';

    const data = [
        { title: '审核管理平台', rating: 4.5, feedbacks: 124 },
        { title: '扁鹊', rating: 4, feedbacks: 108 },
        { title: '直播审核平台', rating: 3.5, feedbacks: 244 },
        { title: '抖音安全测试', feedbacks: 189 },
        { title: '内容平台', rating: 3, feedbacks: 128 },
        { title: '策略平台', rating: 4, feedbacks: 156 },
    ];

    const grid = { gutter: 12, xs: 0, sm: 0, md: 12, lg: 8, xl: 8, xxl: 6 };

    const style = {
        border: '1px solid var(--semi-color-border)',
        backgroundColor: 'var(--semi-color-bg-2)',
        borderRadius: '3px',
        paddingLeft: '20px',
        margin: '8px 2px',
    };
</script>

<template>
    <div>
        <List :dataSource="data" :grid="grid">
            <template #item="{ item }">
                <List.Item :style="style">
                    <div>
                        <h3 :style="{ color: 'var(--semi-color-text-0)', fontWeight: 500 }">{{ item.title }}</h3>
                        <Descriptions align="center" row size="small">
                            <DescriptionsItem>
                                <template #itemKey>满意度</template>
                                <Rating allowHalf :modelValue="item.rating" size="small" />
                            </DescriptionsItem>
                            <DescriptionsItem>
                                <template #itemKey>反馈数</template>
                                {{ item.feedbacks }}
                            </DescriptionsItem>
                        </Descriptions>
                        <div :style="{ margin: '12px 0', display: 'flex', justifyContent: 'flex-end' }">
                            <ButtonGroup :style="{ marginTop: '8px' }" theme="borderless">
                                <Button>编辑</Button>
                                <Button>更多</Button>
                            </ButtonGroup>
                        </div>
                    </div>
                </List.Item>
            </template>
        </List>
    </div>
</template>

Load More

You can use the #loadMore slot to achieve loading state for more incoming contents.

Code

<script setup lang="ts">
    import { onBeforeUnmount, ref } from 'vue';
    import { Avatar, Button, List, Skeleton } from '@fibrous/semi-ui-vue';

    interface Book {
        title?: string;
        loading: boolean;
    }

    const count = 3;
    const data: Book[] = [];
    for (let i = 0; i < 40; i++) {
        data.push({ title: `Semi Design Title ${i}`, loading: false });
    }
    const placeholders: Book[] = [0, 1, 2].map(() => ({ loading: true }));

    const fetchData = (page: number) =>
        new Promise<Book[]>((resolve) => {
            setTimeout(() => resolve(data.slice(page * count, page * count + count)), 1000);
        });

    const dataSource = ref<Book[]>([]);
    const loading = ref(true);
    const noMore = ref(false);
    let page = 0;
    let disposed = false;
    onBeforeUnmount(() => {
        disposed = true;
    });

    const load = async () => {
        loading.value = true;
        const newDataSource = await fetchData(page);
        if (disposed) return;
        dataSource.value = [...dataSource.value, ...newDataSource];
        loading.value = false;
        noMore.value = !newDataSource.length;
    };

    const onLoadMore = () => {
        page += 1;
        void load();
    };

    void load();
</script>

<template>
    <List :dataSource="loading ? [...dataSource, ...placeholders] : dataSource" :loading="loading">
        <template #item="{ item }">
            <Skeleton :loading="item.loading">
                <template #placeholder>
                    <div
                        :style="{
                            display: 'flex',
                            alignItems: 'flex-start',
                            padding: '12px',
                            borderBottom: '1px solid var(--semi-color-border)',
                        }"
                    >
                        <Skeleton.Avatar :style="{ marginRight: '12px' }" />
                        <div>
                            <Skeleton.Title :style="{ width: '120px', marginBottom: '12px', marginTop: '12px' }" />
                            <Skeleton.Paragraph :rows="2" :style="{ width: '600px' }" />
                        </div>
                    </div>
                </template>
                <List.Item>
                    <template #header>
                        <Avatar color="grey">SE</Avatar>
                    </template>
                    <template #main>
                        <div>
                            <span :style="{ color: 'var(--semi-color-text-0)', fontWeight: 500 }">{{ item.title }}</span>
                            <p :style="{ color: 'var(--semi-color-text-2)', margin: '4px 0' }">Semi Design 设计系统包含设计语言以及一整套可复用的前端组件，帮助设计师与开发者更容易地打造高质量的、用户体验一致的、符合设计规范的 Web 应用。</p>
                        </div>
                    </template>
                </List.Item>
            </Skeleton>
        </template>
        <template v-if="!loading && !noMore" #loadMore>
            <div :style="{ textAlign: 'center', marginTop: '12px', height: '32px', lineHeight: '32px' }">
                <Button @click="onLoadMore">显示更多</Button>
            </div>
        </template>
    </List>
</template>

Scroll to Load

You can listen to the scroll event of the scroll container and load the next page near the bottom. Recommended interaction could be reveal a loadmore button after three scrolling loads.

暂无数据

Code

<script setup lang="ts">
    import { onBeforeUnmount, ref } from 'vue';
    import { Avatar, Button, List, Spin } from '@fibrous/semi-ui-vue';

    interface Book {
        title: string;
    }

    const count = 5;
    const dataList: Book[] = [];
    for (let i = 0; i < 100; i++) {
        dataList.push({ title: `Semi Design Title ${i}` });
    }

    const fetchData = (page: number) =>
        new Promise<Book[]>((resolve) => {
            setTimeout(() => resolve(dataList.slice(page * count, page * count + count)), 1000);
        });

    const dataSource = ref<Book[]>([]);
    const loading = ref(true);
    const hasMore = ref(true);
    const page = ref(0);
    let disposed = false;
    onBeforeUnmount(() => {
        disposed = true;
    });

    const load = async () => {
        loading.value = true;
        const newDataSource = await fetchData(page.value);
        if (disposed) return;
        dataSource.value = [...dataSource.value, ...newDataSource];
        loading.value = false;
        hasMore.value = !!newDataSource.length;
    };

    const onLoadMore = () => {
        page.value += 1;
        void load();
    };

    const showLoadMore = () => (page.value + 1) % 4 === 0;

    const onScroll = (event: Event) => {
        const el = event.currentTarget as HTMLElement;
        if (loading.value || !hasMore.value || showLoadMore()) return;
        if (el.scrollHeight - el.scrollTop - el.clientHeight <= 20) onLoadMore();
    };

    void load();
</script>

<template>
    <section aria-label="可滚动列表" class="light-scrollbar" :style="{ height: '420px', overflow: 'auto', border: '1px solid var(--semi-color-border)', padding: '10px' }" tabindex="0" @scroll="onScroll">
        <List :dataSource="dataSource">
            <template #item="{ item }">
                <List.Item>
                    <template #header>
                        <Avatar color="grey">SE</Avatar>
                    </template>
                    <template #main>
                        <div>
                            <span :style="{ color: 'var(--semi-color-text-0)', fontWeight: 500 }">{{ item.title }}</span>
                            <p :style="{ color: 'var(--semi-color-text-2)', margin: '4px 0' }">Semi Design 设计系统包含设计语言以及一整套可复用的前端组件，帮助设计师与开发者更容易地打造高质量的、用户体验一致的、符合设计规范的 Web 应用。</p>
                        </div>
                    </template>
                </List.Item>
            </template>
            <template v-if="!loading && hasMore && showLoadMore()" #loadMore>
                <div :style="{ textAlign: 'center', marginTop: '12px', height: '32px', lineHeight: '32px' }">
                    <Button @click="onLoadMore">显示更多</Button>
                </div>
            </template>
        </List>
        <div v-if="loading && hasMore" :style="{ textAlign: 'center' }">
            <Spin />
        </div>
    </section>
</template>

Scroll to Load Infinite Lists

You can integrate TanStack Virtual to implement infinite scrolling lists with virtualization, which renders only the visible rows and improves the performance for large amounts of data.

Code

<script setup lang="ts">
    import { computed, shallowReactive, useTemplateRef, watch } from 'vue';
    import { useVirtualizer } from '@tanstack/vue-virtual';
    import { Avatar, List, Spin } from '@fibrous/semi-ui-vue';

    interface Book {
        title: string;
    }

    const rowCount = 50;
    const rowHeight = 118;
    // Rows fetched ahead of the window so they arrive before they scroll into view
    const prefetch = 15;
    const dataList: Book[] = Array.from({ length: rowCount }, (_, i) => ({ title: `Semi Design Title ${i}` }));

    const scroller = useTemplateRef('scroller');
    const loaded = shallowReactive(new Set<number>());
    // A requested index is never fetched again, even while pending
    const requested = new Set<number>();
    const virtualizer = useVirtualizer({ count: rowCount, getScrollElement: () => scroller.value, estimateSize: () => rowHeight, overscan: 2 });

    const items = computed(() => virtualizer.value.getVirtualItems());
    const rows = computed(() => items.value.filter((item) => loaded.has(item.index)));

    watch(items, (current) => {
        if (!current.length) return;
        const wanted: number[] = [];
        for (let i = current[0].index; i <= Math.min(current[current.length - 1].index + prefetch, rowCount - 1); i++) {
            if (!requested.has(i)) {
                requested.add(i);
                wanted.push(i);
            }
        }
        if (!wanted.length) return;
        setTimeout(() => {
            for (const i of wanted) loaded.add(i);
        }, 1000);
    });
</script>

<template>
    <div :style="{ border: '1px solid var(--semi-color-border)', padding: '10px' }">
        <section ref="scroller" aria-label="虚拟滚动列表" :style="{ height: '500px', overflow: 'auto' }" tabindex="0">
            <List :style="{ position: 'relative', height: `${virtualizer.getTotalSize()}px` }">
                <!-- Replaces the locale's empty text until a row of the window arrives -->
                <template #emptyContent>
                    <Spin />
                </template>
                <List.Item v-for="item in rows" :key="item.index" :style="{ position: 'absolute', insetInline: '0', top: `${item.start}px`, height: `${rowHeight}px` }">
                    <template #header>
                        <Avatar color="grey">SE</Avatar>
                    </template>
                    <template #main>
                        <div>
                            <span :style="{ color: 'var(--semi-color-text-0)', fontWeight: 500 }">{{ dataList[item.index].title }}</span>
                            <p :style="{ color: 'var(--semi-color-text-2)', margin: '4px 0' }">Semi Design 设计系统包含设计语言以及一整套可复用的前端组件，帮助设计师与开发者更容易地打造高质量的、用户体验一致的、符合设计规范的 Web 应用。</p>
                        </div>
                    </template>
                </List.Item>
            </List>
        </section>
    </div>
</template>

Drag Sort

You can integrate the Vue build of dnd-kit (@dnd-kit/vue) to implement drag and drop sort. The dragged element is the li rendered by ListItem; give every item returned from #item a :key, so that Vue can match the nodes to the right data after dnd-kit has reordered the DOM.

SE
Semi Design Title 1
Semi Design 设计系统包含设计语言以及一整套可复用的前端组件，帮助设计师与开发者更容易地打造高质量的、用户体验一致的、符合设计规范的 Web 应用。
SE
Semi Design Title 2
Semi Design 设计系统包含设计语言以及一整套可复用的前端组件，帮助设计师与开发者更容易地打造高质量的、用户体验一致的、符合设计规范的 Web 应用。
SE
Semi Design Title 3
Semi Design 设计系统包含设计语言以及一整套可复用的前端组件，帮助设计师与开发者更容易地打造高质量的、用户体验一致的、符合设计规范的 Web 应用。
SE
Semi Design Title 4
Semi Design 设计系统包含设计语言以及一整套可复用的前端组件，帮助设计师与开发者更容易地打造高质量的、用户体验一致的、符合设计规范的 Web 应用。
SE
Semi Design Title 5
Semi Design 设计系统包含设计语言以及一整套可复用的前端组件，帮助设计师与开发者更容易地打造高质量的、用户体验一致的、符合设计规范的 Web 应用。

Code

<script setup lang="ts">
    import { defineComponent, h, shallowRef, type ComponentPublicInstance, type SlotsType, type VNode } from 'vue';
    import { RestrictToVerticalAxis } from '@dnd-kit/abstract/modifiers';
    import { Accessibility } from '@dnd-kit/dom';
    import { move } from '@dnd-kit/helpers';
    import { DragDropProvider, type DragDropProviderProps, type DragEndEvent } from '@dnd-kit/vue';
    import { useSortable } from '@dnd-kit/vue/sortable';
    import { Avatar, List, ListItem, type AvatarColor } from '@fibrous/semi-ui-vue';

    interface Item {
        id: number;
        title: string;
        color: AvatarColor;
    }

    const listItems = shallowRef<Item[]>([
        { id: 1, title: 'Semi Design Title 1', color: 'red' },
        { id: 2, title: 'Semi Design Title 2', color: 'grey' },
        { id: 3, title: 'Semi Design Title 3', color: 'light-green' },
        { id: 4, title: 'Semi Design Title 4', color: 'light-blue' },
        { id: 5, title: 'Semi Design Title 5', color: 'pink' },
    ]);

    // useSortable must run inside the item's own component; the li itself is dragged, so items stay direct children.
    // A demo is a single SFC, hence the component is defined here.
    const SortableListItem = defineComponent({
        props: {
            id: { type: Number, required: true },
            index: { type: Number, required: true },
        },
        slots: Object as SlotsType<{ header: () => VNode[]; main: () => VNode[] }>,
        setup(props, { slots }) {
            const element = shallowRef<ComponentPublicInstance | null>(null);
            const { isDragging } = useSortable({ id: () => props.id, index: () => props.index, element });
            return () =>
                h(
                    ListItem,
                    {
                        ref: (instance) => {
                            element.value = instance as ComponentPublicInstance | null;
                        },
                        class: { isDragging: isDragging.value },
                        style: {
                            border: '1px solid var(--semi-color-border)',
                            marginBottom: '12px',
                            cursor: 'grabbing',
                            ...(isDragging.value ? { zIndex: 999, position: 'relative', backgroundColor: 'var(--semi-color-bg-0)' } : {}),
                        },
                    },
                    { header: slots.header, main: slots.main }
                );
        },
    });

    // Accessibility would add role="button" and a Tab stop to each li; pointer dragging only
    const plugins: DragDropProviderProps['plugins'] = (defaults) => defaults.filter((plugin) => plugin !== Accessibility);
    const modifiers = [RestrictToVerticalAxis];

    const handleDragEnd = (event: DragEndEvent) => {
        if (!event.canceled) {
            listItems.value = move(listItems.value, event);
        }
    };
</script>

<template>
    <div :style="{ padding: '12px', border: '1px solid var(--semi-color-border)', margin: '12px' }">
        <DragDropProvider :modifiers="modifiers" :plugins="plugins" @dragEnd="handleDragEnd">
            <List :dataSource="listItems">
                <template #item="{ item, index }">
                    <!-- dnd-kit reorders li nodes mid-drag; an index key would hand a node another item's data -->
                    <SortableListItem :id="item.id" :key="item.id" :index="index">
                        <template #header>
                            <Avatar :color="item.color">SE</Avatar>
                        </template>
                        <template #main>
                            <div>
                                <span :style="{ color: 'var(--semi-color-text-0)', fontWeight: 500 }">
                                    {{ item.title }}
                                </span>
                                <p :style="{ color: 'var(--semi-color-text-2)', margin: '4px 0' }">Semi Design 设计系统包含设计语言以及一整套可复用的前端组件，帮助设计师与开发者更容易地打造高质量的、用户体验一致的、符合设计规范的 Web 应用。</p>
                            </div>
                        </template>
                    </SortableListItem>
                </template>
            </List>
        </DragDropProvider>
    </div>
</template>

With Pagination

You can use Pagination in combination to achieve a paged List

围城
平凡的世界（全三册）
三体（全集）
雪中悍刀行（全集）

Code

<script setup lang="ts">
    import { computed, ref } from 'vue';
    import { List, Pagination } from '@fibrous/semi-ui-vue';

    const data = ['围城', '平凡的世界（全三册）', '三体（全集）', '雪中悍刀行（全集）', '撒哈拉的故事', '明朝那些事', '一禅小和尚', '沙丘', '被讨厌的勇气', '罪与罚', '月亮与六便士', '沉默的大多数'];
    const pageSize = 4;
    const page = ref(1);
    const pageData = computed(() => data.slice((page.value - 1) * pageSize, page.value * pageSize));
</script>

<template>
    <div>
        <div :style="{ marginRight: '16px', width: '280px', display: 'flex', flexWrap: 'wrap' }">
            <List class="component-list-demo-booklist" :dataSource="pageData" size="small" :split="false" :style="{ border: '1px solid var(--semi-color-border)', flexBasis: '100%', flexShrink: 0 }">
                <template #item="{ item }">
                    <List.Item class="list-item">{{ item }}</List.Item>
                </template>
            </List>
            <Pagination v-model:currentPage="page" :pageSize="pageSize" size="small" :style="{ width: '100%', flexBasis: '100%', justifyContent: 'center' }" :total="data.length" />
        </div>
    </div>
</template>

With filter

You can use it by assembling Input to filter the List

围城
平凡的世界（全三册）
三体（全集）
雪中悍刀行（全集）
撒哈拉的故事
明朝那些事
一禅小和尚
沙丘
被讨厌的勇气
罪与罚

Code

<script setup lang="ts">
    import { shallowRef } from 'vue';
    import { IconSearch } from '@fibrous/semi-icons-vue';
    import { Input, List, ListItem } from '@fibrous/semi-ui-vue';

    const data = ['围城', '平凡的世界（全三册）', '三体（全集）', '雪中悍刀行（全集）', '撒哈拉的故事', '明朝那些事', '一禅小和尚', '沙丘', '被讨厌的勇气', '罪与罚'];

    const list = shallowRef(data);

    const onSearch = (keyword?: string) => {
        list.value = keyword ? data.filter((item) => item.includes(keyword)) : data;
    };
</script>

<template>
    <div>
        <div
            :style="{
                marginRight: '16px',
                width: '280px',
                display: 'flex',
                flexWrap: 'wrap',
                border: '1px solid var(--semi-color-border)',
            }"
        >
            <List class="component-list-demo-booklist" :dataSource="list" size="small" :split="false" :style="{ flexBasis: '100%', flexShrink: 0, borderBottom: '1px solid var(--semi-color-border)' }">
                <template #header>
                    <Input placeholder="搜索" @change="(value) => !value && onSearch()" @compositionend="(event) => onSearch((event.target as HTMLInputElement).value)">
                        <template #prefix>
                            <IconSearch />
                        </template>
                    </Input>
                </template>
                <template #item="{ item }">
                    <ListItem class="list-item">{{ item }}</ListItem>
                </template>
            </List>
        </div>
    </div>
</template>

Add delete item

围城
平凡的世界（全三册）
三体（全集）
雪中悍刀行（全集）
撒哈拉的故事
明朝那些事
一禅小和尚
沙丘

新增书籍

Code

<script setup lang="ts">
    import { shallowRef } from 'vue';
    import { IconMinusCircle, IconPlusCircle } from '@fibrous/semi-icons-vue';
    import { Button, List } from '@fibrous/semi-ui-vue';

    const data = ['围城', '平凡的世界（全三册）', '三体（全集）', '雪中悍刀行（全集）', '撒哈拉的故事', '明朝那些事', '一禅小和尚', '沙丘', '被讨厌的勇气', '罪与罚', '月亮与六便士', '沉默的大多数', '第一人称单数'];

    const list = shallowRef(data.slice(0, 8));

    const removeItem = (item: string) => {
        list.value = list.value.filter((book) => book !== item);
    };
    const addItem = () => {
        list.value = list.value.concat(data.slice(list.value.length, list.value.length + 1));
    };
</script>

<template>
    <div>
        <div
            :style="{
                marginRight: '16px',
                width: '280px',
                display: 'flex',
                flexWrap: 'wrap',
                border: '1px solid var(--semi-color-border)',
            }"
        >
            <List class="component-list-demo-booklist" :dataSource="list" size="small" :split="false" :style="{ flexBasis: '100%', flexShrink: 0, borderBottom: '1px solid var(--semi-color-border)' }">
                <template #item="{ item }">
                    <li :key="item" class="list-item" :style="{ margin: '4px' }">
                        <Button :aria-label="`删除${item}`" :style="{ marginRight: '4px' }" theme="borderless" type="danger" @click="removeItem(item)">
                            <template #icon>
                                <IconMinusCircle />
                            </template>
                        </Button>
                        {{ item }}
                    </li>
                </template>
            </List>
            <div :style="{ margin: '4px', fontSize: '14px' }">
                <Button aria-label="新增书籍" :style="{ marginRight: '4px', color: 'var(--semi-color-info)' }" theme="borderless" @click="addItem">
                    <template #icon>
                        <IconPlusCircle />
                    </template>
                </Button>
                新增书籍
            </div>
        </div>
    </div>
</template>

Single or multiple selection

You can enhance the List into a list selector by combining Radio or Checkbox

Code

<script setup lang="ts">
    import { computed, ref } from 'vue';
    import { Checkbox, CheckboxGroup, List, Radio, RadioGroup, type CheckboxValue, type RadioValue } from '@fibrous/semi-ui-vue';

    const data = ['围城', '平凡的世界（全三册）', '三体（全集）', '雪中悍刀行（全集）', '撒哈拉的故事', '明朝那些事', '一禅小和尚', '沙丘', '被讨厌的勇气', '罪与罚', '月亮与六便士', '沉默的大多数', '第一人称单数'];
    const pageData = computed(() => data.slice(0, 8));
    const checkboxVal = ref<CheckboxValue[]>([data[0]]);
    const radioVal = ref<RadioValue | undefined>(data[0]);
    const listStyle = { border: '1px solid var(--semi-color-border)', flexBasis: '100%', flexShrink: 0 };
</script>

<template>
    <div :style="{ display: 'flex' }">
        <div :style="{ marginRight: '16px', width: '280px', display: 'flex', flexWrap: 'wrap' }">
            <CheckboxGroup v-model="checkboxVal">
                <List class="component-list-demo-booklist" :dataSource="pageData" size="small" :split="false" :style="listStyle">
                    <template #item="{ item }">
                        <List.Item class="list-item">
                            <Checkbox :value="item">{{ item }}</Checkbox>
                        </List.Item>
                    </template>
                </List>
            </CheckboxGroup>
        </div>
        <div :style="{ marginRight: '16px', width: '280px', display: 'flex', flexWrap: 'wrap' }">
            <RadioGroup v-model="radioVal">
                <List class="component-list-demo-booklist" :dataSource="pageData" size="small" :split="false" :style="listStyle">
                    <template #item="{ item }">
                        <List.Item class="list-item">
                            <Radio :value="item">{{ item }}</Radio>
                        </List.Item>
                    </template>
                </List>
            </RadioGroup>
        </div>
    </div>
</template>

Keyboard events

You can monitor the keyboard events of the corresponding keys by yourself to realize the selection of different items. As in the following example, you can use the up and down arrow keys to select different items

围城
平凡的世界（全三册）
三体（全集）
雪中悍刀行（全集）
撒哈拉的故事
明朝那些事
一禅小和尚
沙丘
被讨厌的勇气
罪与罚

Code

<script setup lang="ts">
    import { onBeforeUnmount, onMounted, shallowRef } from 'vue';
    import { List, ListItem } from '@fibrous/semi-ui-vue';

    const list = ['围城', '平凡的世界（全三册）', '三体（全集）', '雪中悍刀行（全集）', '撒哈拉的故事', '明朝那些事', '一禅小和尚', '沙丘', '被讨厌的勇气', '罪与罚'];

    const hoverIndex = shallowRef(-1);

    const changeIndex = (offset: number) => {
        let index = hoverIndex.value + offset;
        if (index < 0) {
            index = list.length - 1;
        }
        if (index >= list.length) {
            index = 0;
        }
        hoverIndex.value = index;
    };

    const onKeydown = (event: KeyboardEvent) => {
        if (event.key === 'ArrowUp') {
            event.preventDefault();
            changeIndex(-1);
        } else if (event.key === 'ArrowDown') {
            event.preventDefault();
            changeIndex(1);
        }
    };

    onMounted(() => window.addEventListener('keydown', onKeydown));
    onBeforeUnmount(() => window.removeEventListener('keydown', onKeydown));
</script>

<template>
    <div>
        <div
            :style="{
                marginRight: '16px',
                width: '280px',
                display: 'flex',
                flexWrap: 'wrap',
                border: '1px solid var(--semi-color-border)',
            }"
        >
            <List class="component-list-demo-booklist" :dataSource="list" size="small" :split="false" :style="{ flexBasis: '100%', flexShrink: 0, borderBottom: '1px solid var(--semi-color-border)' }">
                <template #item="{ item, index }">
                    <ListItem :class="{ 'component-list-demo-booklist-active-item': index === hoverIndex }">
                        {{ item }}
                    </ListItem>
                </template>
            </List>
        </div>
    </div>
</template>

The custom styles involved in the Demo of the above book list example are as follows

.component-list-demo-booklist {
    .list-item {
        &:hover {
            background-color: var(--semi-color-fill-0);
        }
        &:active {
            background-color: var(--semi-color-fill-1);
        }
    }
}

.component-list-demo-booklist-active-item {
    background-color: var(--semi-color-fill-0);
}

Accessibility

Pass aria-label or aria-labelledby to List to describe the list; the root element then gets role="group".

A List.Item with @click or @rightClick (including those set on the List) stays an <li> list item and renders a native <button type="button"> inside it as its only focus target, which screen readers announce as a button.

The button wraps the content of the #header and #main slots (or the default slot when there are none) and its click area covers the whole row. After tabbing to it, Enter or Space triggers @click and the context-menu key triggers @rightClick
#extra is rendered outside the button on a higher layer, so buttons and links in it can be focused and clicked normally, and clicking them does not trigger the Item's @click
When the default slot is combined with #header or #main, the default slot sits outside the button and is covered by the full-row button, so put interactive content in #extra
A List.Item without a click callback renders no button and is not focusable

A List.Item used outside a List renders as a plain list item without grid. With grid, the Row that holds the items has role="list" and the Col around each item has role="none", so screen readers read the items as members of that list.

API reference

Props

Property	Description	Type	Default
bordered	Whether to show a border.	`boolean`	`semiDefault("List", "bordered", false)`
dataSource	Data source of the list; each entry is rendered through the item slot.	`T[]`	`semiGlobalDefault("List", "dataSource")`
grid	Grid configuration: align, gutter, justify and type of Row, and span, offset, order, push, pull, the responsive breakpoints, class and style of Col. class and style land on the Col around each item.	`Grid`	`semiGlobalDefault("List", "grid")`
layout	List layout: vertical or horizontal.	`"vertical" \| "horizontal"`	`semiDefault("List", "layout", "vertical")`
loading	Whether the list is loading; a Spin is shown when true.	`boolean`	`semiDefault("List", "loading", false)`
size	List size: small, default or large.	`Size`	`semiDefault("List", "size", "default")`
split	Whether to show dividers between items.	`boolean`	`semiDefault("List", "split", true)`
onClick	Click handler for the items that have no onClick of their own; an item with a handler renders a native button. Callers write @click; it remains a function prop because its presence decides whether an item renders a button.	`Type`	`undefined`
onRightClick	Context-menu handler for the items that have no onRightClick of their own; those items also render a native button. Callers write @rightClick; it remains a function prop for the same reason as onClick.	`Type`	`undefined`

Events

Event	Description	Callback parameters
None

Slots

Slot	Description	Scope parameters
default	List.Item children, rendered after the items of dataSource.	`any`
item	Renders each entry of dataSource, receiving item and index and returning one or more List.Item.	`Type`
header	List header.	`any`
footer	List footer.	`any`
emptyContent	Content shown when there is no data; the locale's empty text by default.	`any`
loadMore	Load-more button.	`any`

Exposes

Name	Description	Type
None

class, style and native attributes fall through to the root element; when aria-label or aria-labelledby is passed without a role, the root element gets role="group". The payload of @click and @rightClick is the native MouseEvent, and they act on the items, not on the root element.

List grid props

grid accepts only the Row props align, gutter, justify, type and the Col props span, offset, order, push, pull, the responsive breakpoints, class and style; other attributes are not accepted. class and style land on the Col around each item. Refer to Grid for their meaning.

Properties	Instructions	type	Default
span	Number of grid spaces	number	-
gutter	Grid spacing	number	0
xs	`< 576px` responsive grid, a number or an object containing other attributes	number\|object	-
sm	`≥ 576px` responsive grid, a number or an object containing other properties	number\|object	-
md	`≥ 768px` responsive grid, a number or an object containing other properties	number\|object	-
lg	`≥ 992px` responsive grid, a number or an object containing other properties	number\|object	-
xl	`≥ 1200px` responsive grid, a number or an object containing other properties	number\|object	-
xxl	`≥ 1600px` responsive grid, a number or an object containing other properties	number\|object	-

List.Item

Props

Property	Description	Type	Default
align	Vertical alignment of header and main: flex-start, flex-end, center, baseline or stretch; flex-start when omitted.	`"flex-start" \| "flex-end" \| "center" \| "baseline" \| "stretch"`	`undefined`
onClick	Click handler, taking precedence over the List's onClick; an item with a handler renders a native button. Callers write @click; it remains a function prop for the same reason as on List.	`Type`	`undefined`
onRightClick	Context-menu handler, taking precedence over the List's onRightClick; an item with only this handler also renders a native button. Callers write @rightClick.	`Type`	`undefined`

Events

Event	Description	Callback parameters
None

Slots

Slot	Description	Scope parameters
default	Item content; inside the button when the item is clickable and has no header or main slot, otherwise outside it.	`any`
header	Item header content.	`any`
main	Item main content.	`any`
extra	Additional item content, rendered outside the button; interactive elements in it stay focusable and clickable, and clicking them does not trigger the row's click.	`any`

Exposes

Name	Description	Type
None

class, style, data-*, aria-* and native attributes fall through to the li, not to the outer Col in grid mode.

Content Guidelines

Capitalize the first letter
do not follow punctuation at the end
Grammatical parallelism: mixed use of active and passive, declarative and imperative sentences

Design Tokens

These are the component's internal Sass variables and cannot be overridden. To customize styles, override the --semi-* CSS variables (see the Design Token page) or write unlayered CSS rules.

Sass variable	Value	Usage
$color-list_default-border-default	var(--semi-color-border)	列表描边颜色
$color-list_empty-text-default	var(--semi-color-text-2)	空状态下列表文字颜色
$spacing-list_empty-paddingX	0px	空状态列表水平内边距
$spacing-list_empty-paddingY	$spacing-base-tight	空状态列表垂直内边距
$spacing-list_footer-paddingX	$spacing-base-tight	列表 footer 水平内边距
$spacing-list_footer-paddingY	$spacing-loose	列表 footer 垂直内边距
$spacing-list_item-paddingX	$spacing-base-tight	列表 item 水平内边距 - 默认尺寸
$spacing-list_item-paddingY	$spacing-loose	列表 item 垂直内边距 - 默认尺寸
$spacing-list_small-paddingX	$spacing-tight	列表 item 水平内边距 - 小尺寸
$spacing-list_small-paddingY	$spacing-base	列表 item 垂直内边距 - 小尺寸
$spacing-list_large-paddingX	$spacing-base	列表 item 水平内边距 - 大尺寸
$spacing-list_large-paddingY	$spacing-loose	列表 item 垂直内边距 - 大尺寸
$spacing-list_header-marginRight	$spacing-base-loose	列表 header 右侧外边距
$spacing-list_extra-marginLeft	$spacing-super-loose	列表 extra 额外内容左侧外边距