Get Started

React List is a simple, easy to use React component to create different kind of lists. It supports:

• virtual list

• infinite scroll

• index to browse the list easily

• grouping with sticky headers

• reverse list

To start, install react-lists in your React project.

1npm install react-lists

1yarn add react-lists

1import React from 'react'
2  import { List } from '@react-lists/core'
3
4  export default function SampleList() {
5    return (
6      <List
7        listHeight={400}
8        items={["Afghanistan","Albania","Algeria","Andorra","Angola","Anguilla","Antigua &amp; Barbuda","Argentina","Armenia","Aruba","Australia","Austria","Azerbaijan","Bahamas","Bahrain","Bangladesh","Barbados","Belarus","Belgium","Belize","Benin","Bermuda","Bhutan","Bolivia","Bosnia &amp; Herzegovina","Botswana","Brazil","British Virgin Islands","Brunei","Bulgaria","Burkina Faso","Burundi","Cambodia","Cameroon","Cape Verde","Cayman Islands","Chad","Chile","China","Colombia","Congo","Cook Islands","Costa Rica","Cote D Ivoire","Croatia","Cruise Ship","Cuba","Cyprus","Czech Republic","Denmark","Djibouti","Dominica","Dominican Republic","Ecuador","Egypt","El Salvador","Equatorial Guinea","Estonia","Ethiopia","Falkland Islands","Faroe Islands","Fiji","Finland","France","French Polynesia","French West Indies","Gabon","Gambia","Georgia","Germany","Ghana","Gibraltar","Greece","Greenland","Grenada","Guam","Guatemala","Guernsey","Guinea","Guinea Bissau","Guyana","Haiti","Honduras","Hong Kong","Hungary","Iceland","India","Indonesia","Iran","Iraq","Ireland","Isle of Man","Israel","Italy","Jamaica","Japan","Jersey","Jordan","Kazakhstan","Kenya","Kuwait","Kyrgyz Republic","Laos","Latvia","Lebanon","Lesotho","Liberia","Libya","Liechtenstein","Lithuania","Luxembourg","Macau","Macedonia","Madagascar","Malawi","Malaysia","Maldives","Mali","Malta","Mauritania","Mauritius","Mexico","Moldova","Monaco","Mongolia","Montenegro","Montserrat","Morocco","Mozambique","Namibia","Nepal","Netherlands","Netherlands Antilles","New Caledonia","New Zealand","Nicaragua","Niger","Nigeria","Norway","Oman","Pakistan","Palestine","Panama","Papua New Guinea","Paraguay","Peru","Philippines","Poland","Portugal","Puerto Rico","Qatar","Reunion","Romania","Russia","Rwanda","Saint Pierre &amp; Miquelon","Samoa","San Marino","Satellite","Saudi Arabia","Senegal","Serbia","Seychelles","Sierra Leone","Singapore","Slovakia","Slovenia","South Africa","South Korea","Spain","Sri Lanka","St Kitts &amp; Nevis","St Lucia","St Vincent","St. Lucia","Sudan","Suriname","Swaziland","Sweden","Switzerland","Syria","Taiwan","Tajikistan","Tanzania","Thailand","Timor L'Este","Togo","Tonga","Trinidad &amp; Tobago","Tunisia","Turkey","Turkmenistan","Turks &amp; Caicos","Uganda","Ukraine","United Arab Emirates","United Kingdom","Uruguay","Uzbekistan","Venezuela","Vietnam","Virgin Islands (US)","Yemen","Zambia","Zimbabwe"]}
9        itemRenderer={({ item }) => {
10          return item
11        }}
12      />
13    )
14  }

API Reference

The package exports two components that you can use to create your lists.

List

1//...
2import { List } from '@react-lists/core'
3//...

Attributes:

• items: object|string[]

  Items to be rendered.

• itemRenderer: (item) => ReactNode

  Function to determine how the item will be rendered.

• listHeight: number

  The height of the list in pixels. Try to use the height of the parent element or the window to have it dynamically.

• loadingRenderer: () => ReactNode

  Function to determine how the loading will be rendered.

• reverse: boolean

  Render the list in reverse.

• displayLoading: boolean

  Display a loading component when onLoadMore function is executed.

• onBottomReached: () => void

  Callback function executed whenever the list reaches the end.

• onItemClick: (item: object) => void

  Callback function executed whenever the user click on an item.

• onLoadMore: () => void

  Callback function executed whenever the list reaches the bottom, or the top if it is a reverse list.

• onTopReached: () => void

  Callback function executed whenever the list reaches the beginning.

GroupList

Attributes:

• displayIndexMenu: boolean

  Display a index menu to navigate bettween the grouped list.

• displaySubHeaders: boolean

  Display sub headers for the groups.

• stickySubHeaders: boolean

  Make the sub headers sticky.

• subHeaderRenderer: (text: string) => ReactNode

  Function to determine how the sub header will be rendered.

1//...
2import { GroupList } from '@react-lists/core'
3//...

Styles

Simple List

1import React from 'react'
2import faker from 'faker'
3import PropTypes from 'prop-types'
4import { makeStyles } from '@material-ui/core'
5import { List } from '@react-lists/core'
6
7const useStyles = makeStyles(theme => ({
8  animal: {
9    marginBottom: theme.spacing(2),
10    width: '100%'
11  }
12}))
13
14const animals = Array(20).fill({}).map((item, index) => ({
15  id: faker.random.uuid(),
16  url: `${faker.image.animals()}?v=${index}`
17}))
18
19const AnimalRenderer = ({ url }) => {
20  const classes = useStyles()
21
22  return <img className={classes.animal} src={url} />
23}
24
25AnimalRenderer.propTypes = {
26  url: PropTypes.string.isRequired
27}
28
29export default function SimpleList() {
30  return (
31    <List
32      listHeight={400}
33      items={animals}
34      itemRenderer={AnimalRenderer}
35    />
36  )
37}

100.000 Items

Combo Box

News Feed

1import React from 'react'
2import faker from 'faker'
3import PropTypes from 'prop-types'
4import {
5  Avatar,
6  Card,
7  CardHeader,
8  CardMedia,
9  CardContent,
10  CardActions,
11  IconButton,
12  Typography,
13  makeStyles
14} from '@material-ui/core'
15import {
16  Favorite as FavoriteIcon,
17  MoreVert as MoreVertIcon,
18  Share as ShareIcon
19} from '@material-ui/icons'
20import { red } from '@material-ui/core/colors'
21import { List } from '@react-lists/core'
22
23const useStyles = makeStyles(theme => ({
24  root: {
25    margin: '0 auto',
26    marginBottom: theme.spacing(3),
27    width: '80%'
28  },
29  media: {
30    height: 0,
31    paddingTop: '56.25%'
32  },
33  avatar: {
34    backgroundColor: red[500]
35  }
36}))
37
38const DEFAULT_QUANTITY = 20
39
40const fakeData = (quantity = DEFAULT_QUANTITY) => {
41  return Array(quantity).fill({}).map((item, index) => ({
42    id: faker.random.uuid(),
43    user: {
44      name: faker.name.findName()
45    },
46    content: faker.lorem.sentence,
47    imageUrl: `${faker.image.animals()}?v=${index}`,
48    date: new Intl.DateTimeFormat('en', {
49      day: '2-digit',
50      month: 'short',
51      year: 'numeric'
52    }).format(faker.date.past())
53  }))
54}
55
56const initialNews = fakeData()
57
58const NewsRenderer = ({
59  content,
60  date,
61  user,
62  imageUrl
63}) => {
64  const classes = useStyles()
65
66  return (
67    <Card className={classes.root}>
68      <CardHeader
69        avatar={
70          <Avatar className={classes.avatar} src={imageUrl} />
71        }
72        action={
73          <IconButton aria-label="settings">
74            <MoreVertIcon />
75          </IconButton>
76        }
77        title={user.name}
78        subheader={date}
79      />
80      <CardMedia
81        className={classes.media}
82        image={imageUrl}
83      />
84      <CardContent>
85        <Typography variant="body2" color="textSecondary" component="p">
86          {content}
87        </Typography>
88      </CardContent>
89      <CardActions disableSpacing>
90        <IconButton aria-label="add to favorites">
91          <FavoriteIcon />
92        </IconButton>
93        <IconButton aria-label="share">
94          <ShareIcon />
95        </IconButton>
96      </CardActions>
97    </Card>
98  )
99}
100
101NewsRenderer.propTypes = {
102  content: PropTypes.string.isRequired,
103  date: PropTypes.string.isRequired,
104  imageUrl: PropTypes.string.isRequired,
105  user: PropTypes.shape({
106    name: PropTypes.string.isRequired
107  }).isRequired
108}
109
110export default function InfiniteScrollList() {
111  const [news, setNewsFeed] = React.useState(initialNews)
112  const [hasMoreItems, setHasMoreItems] = React.useState(true)
113  const [displayLoading, setDisplayLoading] = React.useState(false)
114
115  const loadMore = () => {
116    if (!hasMoreItems) {
117      return
118    }
119
120    setDisplayLoading(true)
121
122    setTimeout(() => {
123      const newNews = fakeData()
124
125      setNewsFeed(oldNews => {
126        const newssUpdated = [...oldNews, ...newNews]
127
128        setHasMoreItems(newssUpdated.length < DEFAULT_QUANTITY * 4)
129        setDisplayLoading(false)
130
131        return newssUpdated
132      })
133    }, 2000)
134  }
135
136  return (
137    <List
138      displayLoading={displayLoading}
139      items={news}
140      itemRenderer={NewsRenderer}
141      listHeight={600}
142      onLoadMore={loadMore}
143    />
144  )
145}

Contacts

1import React from 'react'
2import faker from 'faker'
3import PropTypes from 'prop-types'
4import { makeStyles } from '@material-ui/core'
5import { GroupList } from '@react-lists/core'
6
7const useStyles = makeStyles(theme => ({
8  contact: {
9    marginBottom: theme.spacing(2),
10    width: '100%'
11  },
12  name: {
13    fontSize: theme.typography.pxToRem(14),
14    fontWeight: 'bold',
15    paddingBottom: 5
16  },
17  phone: {
18    fontSize: theme.typography.pxToRem(16),
19    fontWeight: 'normal',
20    paddingBottom: 5
21  },
22  email: {
23    fontSize: theme.typography.pxToRem(12),
24    fontWeight: 'normal'
25  },
26  listSubHeader: {
27    background: '#fafafa',
28    borderBottom: '1px solid #cccccc'
29  }
30}))
31
32const contacts = Array(100).fill({}).map(() => ({
33  id: faker.random.uuid(),
34  name: faker.name.findName(),
35  phone: faker.phone.phoneNumberFormat(),
36  email: faker.internet.email()
37}))
38.sort((contactA, contactB) => contactA.name.localeCompare(contactB.name))
39.reduce((list, contact) => {
40  const firstChar = contact.name[0].toUpperCase()
41
42  if (!list.hasOwnProperty(firstChar)) {
43    list[firstChar] = {
44      data: [],
45      header: firstChar
46    }
47  }
48
49  list[firstChar].data.push(contact)
50
51  return list
52}, {})
53
54const ContactRenderer = ({ email, name, phone }) => {
55    const classes = useStyles()
56
57    return (
58    <div className={classes.contact}>
59      <div className={classes.name}>{name}</div>
60      <div className={classes.phone}>{phone}</div>
61      <div className={classes.email}>
62        <a href={`mailto:${email}`}>{email}</a>
63      </div>
64    </div>
65  )
66}
67
68ContactRenderer.propTypes = {
69  email: PropTypes.string.isRequired,
70  name: PropTypes.string.isRequired,
71  phone: PropTypes.string.isRequired
72}
73
74const SubHeaderRenderer = ({ text }) => {
75  const classes = useStyles()
76  return <div className={classes.listSubHeader}>{text}</div>
77}
78
79SubHeaderRenderer.propTypes = {
80  text: PropTypes.string.isRequired
81}
82
83export default function ContactGroupedList() {
84  return (
85    <GroupList
86      displayIndexMenu
87      items={contacts}
88      itemRenderer={ContactRenderer}
89      listHeight={500}
90      subHeaderRenderer={SubHeaderRenderer}
91    />
92  )
93}

Chat Messages

1import React from 'react'
2import faker from 'faker'
3import PropTypes from 'prop-types'
4import { makeStyles } from '@material-ui/core'
5import { GroupList } from '@react-lists/core'
6
7const useStyles = makeStyles(theme => ({
8  message: {
9    background: '#f1f1f1',
10    borderRadius: 7.5,
11    color: '#4a4a4a',
12    maxWidth: 'max-content',
13    minWidth: '40%',
14    margin: '10px',
15    padding: '10px 15px',
16    width: '80%'
17  },
18  messageSender: {
19    background: '#dcf8c6',
20    marginLeft: 'auto'
21  },
22  header: {
23    fontWeight: 'bold',
24    fontSize: theme.typography.pxToRem(14),
25    marginBottom: theme.spacing(2),
26    textAlign: 'left'
27  },
28  body: {
29    fontWeight: 'normal',
30    fontSize: theme.typography.pxToRem(14),
31    marginBottom: theme.spacing(2)
32  },
33  footer: {
34    fontWeight: 'normal',
35    fontSize: theme.typography.pxToRem(12),
36    textAlign: 'right'
37  },
38  listSubHeader: {
39    paddingTop: 10
40  },
41  listSubHeaderContent: {
42    background: 'rgba(225, 245, 254, 0.92)',
43    borderRadius: 7.5,
44    fontWeight: 'bold',
45    margin: '5px auto',
46    padding: '10px 15px',
47    width: 'max-content'
48  }
49}))
50
51let date = faker.date.past()
52const DEFAULT_QUANTITY = 100
53
54const mapMessages = (item, index) => {
55  if (index % 10 === 0) {
56    date = faker.date.past()
57  } else {
58    const newDate = date.getTime() + 1 * 60 * 60 * 1000
59    date.setTime(newDate)
60  }
61
62  return {
63    id: faker.random.uuid(),
64    text: faker.lorem.text(),
65    sender: {
66      id: Math.floor(Math.random() * (10 - 1 + 1)) + 1,
67      name: faker.name.findName()
68    },
69    date: new Intl.DateTimeFormat('en', {
70      day: '2-digit',
71      month: 'short',
72      year: 'numeric'
73    }).format(date),
74    datetime: new Intl.DateTimeFormat('en', {
75      day: '2-digit',
76      month: 'short',
77      year: 'numeric',
78      hour: 'numeric',
79      minute: 'numeric'
80    }).format(date),
81    timestemp: date.getTime()
82  }
83}
84
85const sortMessages = (a, b) => b.timestemp - a.timestemp
86
87const groupMessagesByDate = (groupByDate, message) => {
88  if (!groupByDate[message.date]) {
89    groupByDate[message.date] = {
90      header: message.date,
91      data: []
92    }
93  }
94
95  groupByDate[message.date].data.push(message)
96
97  return groupByDate
98}
99
100const fakeMessages = () => Array(DEFAULT_QUANTITY).fill({}).map(mapMessages)
101
102const MessageRenderer = ({ text, sender, datetime }) => {
103  const classes = useStyles()
104  let messageStyles = classes.message
105
106  if (sender.id === 1) {
107    messageStyles += ` ${classes.messageSender}`
108  }
109
110  return (
111    <div className={messageStyles}>
112      <div className={classes.header}>{sender.name}</div>
113      <div className={classes.body}>{text}</div>
114      <div className={classes.footer}>{datetime}</div>
115    </div>
116  )
117}
118
119MessageRenderer.propTypes = {
120  datetime: PropTypes.string.isRequired,
121  text: PropTypes.string.isRequired,
122  sender: PropTypes.shape({
123    id: PropTypes.number.isRequired,
124    name: PropTypes.string.isRequired
125  }).isRequired
126}
127
128const SubHeaderRenderer = ({ text }) => {
129  const classes = useStyles()
130  return (
131    <div className={classes.listSubHeader}>
132      <div className={classes.listSubHeaderContent}>
133        {text}
134      </div>
135    </div>
136  )
137}
138
139SubHeaderRenderer.propTypes = {
140  text: PropTypes.string.isRequired
141}
142
143const initialMessages = fakeMessages()
144
145export default function ChatMessagesReverseList() {
146  const [messages, setMessages] = React.useState(initialMessages)
147  const [hasMoreItems, setHasMoreItems] = React.useState(true)
148  const [displayLoading, setDisplayLoading] = React.useState(false)
149
150  const loadMore = () => {
151    if (!hasMoreItems) {
152      return
153    }
154
155    setDisplayLoading(true)
156
157    setTimeout(() => {
158      const newMessages = fakeMessages()
159
160      setMessages(oldMessages => {
161        const messagesUpdated = [...oldMessages, ...newMessages]
162
163        setHasMoreItems(messagesUpdated.length < DEFAULT_QUANTITY * 2)
164        setDisplayLoading(false)
165
166        return messagesUpdated
167      })
168    }, 2000)
169  }
170
171return (
172  <GroupList
173    displayLoading={displayLoading}
174    items={messages.sort(sortMessages).reduce(groupMessagesByDate, {})}
175    itemRenderer={MessageRenderer}
176    listHeight={400}
177    reverse
178    subHeaderRenderer={SubHeaderRenderer}
179    onLoadMore={loadMore}
180  />
181)