List

Display a list of items with support for pagination and loading states.

Import

import { List } from 'asterui'

Examples

Basic List

Simple list with items.

</>

• Racing car sprints past
• Japanese princess unveiled
• Australian walks 100km
• Man charged over missing wedding

import { List } from 'asterui'

function App() {
  const basicData = [
    'Racing car sprints past',
    'Japanese princess unveiled',
    'Australian walks 100km',
    'Man charged over missing wedding',
  ];
  
  return (
      <List
        dataSource={basicData}
        renderItem={(item) => <List.Item>{item}</List.Item>}
      />
    )
}

export default App

With Avatar

List items with avatars and descriptions.

</>

• 

  Alice Johnson

  alice@example.com
• 

  Bob Smith

  bob@example.com
• 

  Carol White

  carol@example.com

import { List, Avatar } from 'asterui'

function App() {
  const avatarData = [
    {
      name: 'Alice Johnson',
      email: 'alice@example.com',
      avatar: 'https://i.pravatar.cc/150?img=5',
    },
    {
      name: 'Bob Smith',
      email: 'bob@example.com',
      avatar: 'https://i.pravatar.cc/150?img=12',
    },
    {
      name: 'Carol White',
      email: 'carol@example.com',
      avatar: 'https://i.pravatar.cc/150?img=9',
    },
  ];
  
  return (
      <List
        dataSource={avatarData}
        renderItem={(item) => (
          <List.Item>
            <List.Item.Meta
              avatar={<Avatar src={item.avatar} alt={item.name} />}
              title={item.name}
              description={item.email}
            />
          </List.Item>
        )}
      />
    )
}

export default App

Loading State

List in loading state with skeleton.

</>

Loading

import { List } from 'asterui'

function App() {
  return (
      <List
        dataSource={[]}
        renderItem={(item) => <List.Item>{item}</List.Item>}
        loading
      />
    )
}

export default App

With Pagination

List with pagination controls.

</>

• Item 1
• Item 2
• Item 3
• Item 4
• Item 5

«‹12345›»

import { List } from 'asterui'
import { useState } from 'react'

function App() {
  const allData = Array.from({ length: 23 }, (_, i) => `Item ${i + 1}`);
  const [page, setPage] = useState(1);
  const pageSize = 5;
  const start = (page - 1) * pageSize;
  const end = start + pageSize;
  const currentData = allData.slice(start, end);
  
  return (
      <List
        dataSource={currentData}
        renderItem={(item) => <List.Item>{item}</List.Item>}
        pagination={{
          current: page,
          pageSize,
          total: allData.length,
          onChange: setPage,
        }}
      />
    )
}

export default App

API

List

Property	Description	Type	Default
dataSource	Array of data items to render	T[]	-
renderItem	Function to render each item	(item: T, index: number) => React.ReactNode	-
header	List header content	React.ReactNode	-
footer	List footer content	React.ReactNode	-
loading	Whether the list is in loading state	boolean	false
pagination	Pagination configuration	ListPaginationConfig | false	false
grid	Grid layout configuration	ListGridConfig	-
bordered	Show border around list	boolean	true
split	Show divider between items	boolean	true
size	Size variant	'sm' | 'md' | 'lg'	'md'
itemLayout	Layout direction for items	'horizontal' | 'vertical'	'horizontal'
locale	Internationalization text	{ emptyText?: React.ReactNode }	-
loadMore	Load more content (e.g., button)	React.ReactNode	-
rowKey	Custom key extraction for items	keyof T | ((item: T) => React.Key)	-
data-testid	Test ID for the component	string	'list'
aria-label	Accessible label for the list	string	-

List.Item

Property	Description	Type	Default
children	Item content	React.ReactNode	-
actions	Action buttons displayed on the right	React.ReactNode[]	-
extra	Extra content on the right side	React.ReactNode	-
className	Additional CSS classes	string	-

List.Item.Meta

Property	Description	Type	Default
avatar	Avatar or icon element	React.ReactNode	-
title	Title content	React.ReactNode	-
description	Description content	React.ReactNode	-

Accessibility

• Use aria-label to provide context for the list
• List items are rendered in semantic <ul> or <ol> elements
• Loading state is communicated to screen readers
• Pagination controls are keyboard accessible
• Empty state content is properly announced