React Native Timeline Flatlist

Timeline component for React Native App work for Android and iOS

Written in TypeScript — type definitions are bundled with the package, so no separate @types package is needed.

Examples in examples folder

DEMO HERE

Table of Contents

• Installation
• TypeScript support
• Usage
  • Basic usage
  • Custom example
  • Circle dot example
  • Icon example
  • Override render example
  • Pull to refresh and load more example
• Column Format (in v.0.2.0)
  • Single column right
  • Two column
  • Time container hiding
• Configuration
  • Data Object
  • Timeline
• Troubleshooting
  • Shift problem
  • Timeline is rendered, but not displayed until scroll

Installation

npm install react-native-timeline-flatlist

or

yarn add react-native-timeline-flatlist

Peer dependencies: react >= 17.0.0 and react-native >= 0.64.0.

TypeScript support

The library ships with its own type definitions built from the TypeScript source — no @types/react-native-timeline-flatlist needed. You can import the types directly:

import Timeline, { TimelineProps, Data } from 'react-native-timeline-flatlist'

const data: Data[] = [
  { time: '09:00', title: 'Event 1', description: 'Event 1 Description' },
]

Basic Usage

import Timeline from 'react-native-timeline-flatlist'

const data = [
  {time: '09:00', title: 'Event 1', description: 'Event 1 Description'},
  {time: '10:45', title: 'Event 2', description: 'Event 2 Description'},
  {time: '12:00', title: 'Event 3', description: 'Event 3 Description'},
  {time: '14:00', title: 'Event 4', description: 'Event 4 Description'},
  {time: '16:30', title: 'Event 5', description: 'Event 5 Description'}
]

export default function BasicExample() {
  return <Timeline data={data} />
}

see full basic example

Custom

export default function CustomExample() {
  return (
    <Timeline
      //..other props
      circleSize={20}
      circleColor='rgb(45,156,219)'
      lineColor='rgb(45,156,219)'
      timeContainerStyle={{minWidth: 52, marginTop: -5}}
      timeStyle={{textAlign: 'center', backgroundColor: '#ff9797', color: 'white', padding: 5, borderRadius: 13}}
      descriptionStyle={{color: 'gray'}}
      options={{
        style: {paddingTop: 5}
      }}
      isUsingFlatlist={true}
    />
  )
}

see full custom example

Circle Dot

export default function CircleDotExample() {
  return (
    <Timeline
      //..other props
      innerCircle={'dot'}
    />
  )
}

see full circle dot example

Icon

const data = [
  {time: '09:00', title: 'Archery Training', description: 'The Beginner Archery and Beginner Crossbow course does not require you to bring any equipment, since everything you need will be provided for the course. ', lineColor: '#009688', icon: require('../img/archery.png')},
  {time: '10:45', title: 'Play Badminton', description: 'Badminton is a racquet sport played using racquets to hit a shuttlecock across a net.', icon: require('../img/badminton.png')},
  {time: '12:00', title: 'Lunch', icon: require('../img/lunch.png')},
  {time: '14:00', title: 'Watch Soccer', description: 'Team sport played between two teams of eleven players with a spherical ball. ', lineColor: '#009688', icon: require('../img/soccer.png')},
  {time: '16:30', title: 'Go to Fitness center', description: 'Look out for the Best Gym & Fitness Centers around me :)', icon: require('../img/dumbbell.png')}
]

export default function IconExample() {
  return (
    <Timeline
      //..other props
      data={data}
      innerCircle={'icon'}
    />
  )
}

Also you can pass any React element as icon or iconDefault:

const data = [
  //...
  {time: '12:00', title: 'Custom rendered icon', icon: <Image
    style={{width: 20, height: 20}}
    source={{uri: 'https://reactnative.dev/img/tiny_logo.png'}}
  />},
  //...
]

see full icon example

Override Render

const data = [
  {
    time: '09:00',
    title: 'Archery Training',
    description: 'The Beginner Archery and Beginner Crossbow course does not require you to bring any equipment, since everything you need will be provided for the course. ',
    lineColor: '#009688',
    icon: require('../img/archery.png'),
    imageUrl: 'https://cloud.githubusercontent.com/assets/21040043/24240340/c0f96b3a-0fe3-11e7-8964-fe66e4d9be7a.jpg'
  },
  {
    time: '10:45',
    title: 'Play Badminton',
    description: 'Badminton is a racquet sport played using racquets to hit a shuttlecock across a net.',
    icon: require('../img/badminton.png'),
    imageUrl: 'https://cloud.githubusercontent.com/assets/21040043/24240405/0ba41234-0fe4-11e7-919b-c3f88ced349c.jpg'
  },
  {
    time: '12:00',
    title: 'Lunch',
    icon: require('../img/lunch.png'),
  },
  {
    time: '14:00',
    title: 'Watch Soccer',
    description: 'Team sport played between two teams of eleven players with a spherical ball. ',
    lineColor: '#009688',
    icon: require('../img/soccer.png'),
    imageUrl: 'https://cloud.githubusercontent.com/assets/21040043/24240419/1f553dee-0fe4-11e7-8638-6025682232b1.jpg'
  },
  {
    time: '16:30',
    title: 'Go to Fitness center',
    description: 'Look out for the Best Gym & Fitness Centers around me :)',
    icon: require('../img/dumbbell.png'),
    imageUrl: 'https://cloud.githubusercontent.com/assets/21040043/24240422/20d84f6c-0fe4-11e7-8f1d-9dbc594d0cfa.jpg'
  }
]

export default function OverrideRenderExample() {
  const renderDetail = (rowData, rowID) => {
    const title = <Text style={styles.title}>{rowData.title}</Text>
    let desc = null
    if (rowData.description && rowData.imageUrl) {
      desc = (
        <View style={styles.descriptionContainer}>
          <Image source={{uri: rowData.imageUrl}} style={styles.image} />
          <Text style={styles.textDescription}>{rowData.description}</Text>
        </View>
      )
    }

    return (
      <View style={{flex: 1}}>
        {title}
        {desc}
      </View>
    )
  }

  return (
    <Timeline
      //..other props
      data={data}
      renderDetail={renderDetail}
    />
  )
}

see full override render example

Pull to refresh and load more

export default function RefreshLoadMoreExample() {
  const [data, setData] = useState(initialData)
  const [isRefreshing, setIsRefreshing] = useState(false)
  const [waiting, setWaiting] = useState(false)

  const onRefresh = () => {
    //set initial data
  }

  const onEndReached = () => {
    //fetch next data
  }

  const renderFooter = () => {
    //show loading indicator
    if (waiting) {
      return <ActivityIndicator />
    }
    return <Text>~</Text>
  }

  return (
    <Timeline
      //..other props
      data={data}
      options={{
        refreshControl: (
          <RefreshControl
            refreshing={isRefreshing}
            onRefresh={onRefresh}
          />
        ),
        ListFooterComponent: renderFooter,
        onEndReached: onEndReached
      }}
    />
  )
}

see full refresh and load more example

Column Format

Single Column Right

export default function SingleColumnRightExample() {
  return (
    <Timeline
      //..other props
      columnFormat='single-column-right'
    />
  )
}

see full single column right example

Two Column

export default function TwoColumnExample() {
  return (
    <Timeline
      //..other props
      columnFormat='two-column'
    />
  )
}

see full two column example

Time container hiding

export default function HideTimeExample() {
  return (
    <Timeline
      //..other props
      showTime={false}
    />
  )
}

Configuration

Data Object:

Property	Type	Default	Description
time	string	null	event time
title	string	null	event title
description	string or React.Element	null	event description
lineWidth	number	same as lineWidth of 'Timeline'	event line width
lineStyle	string	same as lineStyle of 'Timeline'	event line style : 'solid', 'dashed', 'dotted'
lineColor	string	same as lineColor of 'Timeline'	event line color
eventContainerStyle	object	null	custom styles of line
circleSize	number	same as circleSize of 'Timeline'	event circle size
circleColor	string	same as circleColor of 'Timeline'	event circle color
dotColor	string	same as dotColor of 'Timeline'	event dot color (innerCircle = 'dot')
icon	image source, URI string or React.Element	iconDefault	event icon (innerCircle = 'icon' or 'element')
iconDefault	image source or React.Element	same as iconDefault of 'Timeline'	fallback icon for this event (innerCircle = 'icon')
position	string	null	event side in 'two-column' layout : 'left', 'right'
titleStyle	object	same as titleStyle of 'Timeline'	custom styles of this event's title
descriptionStyle	object	same as descriptionStyle of 'Timeline'	custom styles of this event's description
columnSideMargin	number	same as columnSideMargin of 'Timeline'	custom event line side margin
columnSidePadding	number	same as columnSidePadding of 'Timeline'	custom event line side padding

Timeline:

Property	Type	Default	Description
data	Data[]	null	timeline data
innerCircle	string	'none'	timeline mode : 'none', 'dot', 'icon', 'element'
separator	boolean	false	render separator line of events
columnFormat	string	'single-column-left'	can be 'single-column-left', 'single-column-right', 'two-column'
lineWidth	number	2	timeline line width
lineStyle	string	'solid'	timeline line style : 'solid', 'dashed', 'dotted'
lineColor	string	'#007AFF'	timeline line color
circleSize	number	16	timeline circle size
circleColor	string	'#007AFF'	timeline circle color
dotColor	string	'white'	timeline dot color (innerCircle = 'dot')
dotSize	number	circleSize / 2	timeline dot size (innerCircle = 'dot')
iconDefault	image source or React.Element	null	default event icon (used when an event has no icon of its own)
style	object	null	custom styles of Timeline container
circleStyle	object	null	custom styles of event circle
listViewStyle	object	null	custom styles of inner FlatList
listViewContainerStyle	object	null	custom styles of inner FlatList content container
timeStyle	object	null	custom styles of event time
titleStyle	object	null	custom styles of event title
descriptionStyle	object	null	custom styles of event description
iconStyle	object	null	custom styles of event icon
separatorStyle	object	null	custom styles of separator
rowContainerStyle	object	null	custom styles of event container
eventContainerStyle	object	null	custom styles of the event part of the row (line)
eventDetailStyle	object	null	custom styles of the event detail part of the row (line)
timeContainerStyle	object	null	custom styles of container of event time
detailContainerStyle	object	null	custom styles of container of event title and event description
onEventPress	function(event)	null	function to be invoked when event was pressed
renderTime	function(rowData, rowID)	null	custom render event time
renderDetail	function(rowData, rowID)	null	custom render event title and event description
renderCircle	function(rowData, rowID)	null	custom render circle
renderFullLine	boolean	false	render event border on last timeline item
options	object	null	FlatList props, passed to the underlying FlatList
showTime	boolean	true	Time container options
isUsingFlatlist	boolean	true	Render inner components in FlatList (if false - render in View)
isAllowFontScaling	boolean	true	Allow font scaling on time, title and description text
columnSideMargin	number	20	Custom event line side margin
columnSidePadding	number	20	Custom event line side padding

Shift problem

Text width of event time may not be the same.

fix by add 'minWidth' in 'timeContainerStyle' to appropriate value

export default function ShiftFixExample() {
  return (
    <Timeline
      //..other props
      timeContainerStyle={{minWidth: 72}}
    />
  )
}

Timeline is rendered, but not displayed until scroll

fix by add removeClippedSubviews: false into options

export default function RenderFixExample() {
  return (
    <Timeline
      //..other props
      options={{
        removeClippedSubviews: false
      }}
    />
  )
}