Skip to main content

Props

ScrollView Props​

Inherits ScrollView Props.

Standard Props​

Required data​

For simplicity, data is a plain array containing the items to render.

TypeRequired
arrayYes, if sections are not specified

Examples​

[1, 2, 3, 4, 5, 6 /* ... */];
[
  { label: "1", value: 1 /* ... */ },
  { label: "2", value: 2 /* ... */ },
  /* ... */
];

Required renderItem​

renderItem({ item: unknown, index: number, section: number });

Takes an item from data and renders it into the list.

Using data arguments will be an object with the item and its index.

Using sections arguments will be an object with the item and its section index and row index.

note

You need also to specify the height using itemHeight.

TypeRequired
functionYes

controlItemRender​

Removes the wrapping view component that is added by BigList.

Using controlItemRender will add more arguments to renderItem.

renderItem({
  item: unknown,
  index: number,
  section: number,
  key: string,
  style: object,
});
note

You will need to apply style to your rendered View for this to work properly.

TypeRequiredDefault
booleanNofalse

Required itemHeight​

Specify the item height.

This is needed to have a great performance boost for lists of several thousands items.

Function example:

itemHeight(section: number, index: number)
TypeRequiredDefault
number, functionYes50

Required sections​

For simplicity, sections is a plain array containing another plain array with the items (section items) to render.

caution

Specifying this prop you'll overwrite data prop and so it'll be ignored. It's required if no data is specified or if you want to use sticky headers/sections separators (look also at renderSectionHeader and renderSectionFooter).

TypeRequired
arrayYes, if you want to use it instead of data

Examples​

[
  // Section 1
  [1, 2],
  // Section 2
  [3, 4],
  /* ... */
];
[
  [
    // Section 1
    { label: "1", value: 1 /* ... */ },
    { label: "2", value: 2 /* ... */ },
  ],
  [
    // Section 2
    { label: "3", value: 3 /* ... */ },
    { label: "4", value: 4 /* ... */ },
  ],
  /* ... */
];

keyExtractor​

(item: object, index: number) => string;

Used to extract a unique key for a given item at the specified index. Key is used for caching and as the react key to track item re-ordering. The default extractor checks item.key, then item.id, and then falls back to using the index, like React does.

Type
function

renderEmpty​

Rendered when the list is empty.

TypeRequired
functionNo

renderHeader​

Rendered at the top of all the items.

note

You need also to specify the height using headerHeight.

TypeRequired
functionNo

renderFooter​

Rendered at the bottom of all the items.

note

You need also to specify the height using footerHeight.

TypeRequired
functionNo

renderSectionHeader​

renderSectionHeader(section: number)

Rendered at the top of all the section's items.

note

You need also to specify the height using sectionHeaderHeight.

TypeRequired
functionNo

renderSectionFooter​

renderSectionFooter(section: number)

Rendered at the bottom of all the section's items.

note

You need also to specify the height using sectionFooterHeight.

TypeRequired
functionNo

renderScrollViewWrapper​

Wrap the entire list into an accessory component.

TypeRequired
functionNo

ScrollViewComponent​

Custom component to use instead of react-native's ScrollView (e.g. ScrollView from react-native-gesture-handler)

TypeRequiredDefault
componentNoreact-native's ScrollView

renderAccessory​

renderAccessory(list: BigList)

Rendered accessory at the bottom of the list.

TypeRequired
functionNo

headerHeight​

Specify the header item height.

TypeRequiredDefault
number, functionNo0

footerHeight​

Specify the footer item height.

TypeRequiredDefault
number, functionNo0

sectionHeaderHeight​

Specify the section header height.

Function example:

sectionHeaderHeight(section: number)
TypeRequiredDefault
number, functionNo0

sectionFooterHeight​

Specify the section footer height.

Function example:

sectionFooterHeight(section: number)
TypeRequiredDefault
number, functionNo0

placeholder​

Enable placeholder on fast scrolling. Disabled as default on web.

When list can't render your items fast enough the non-rendered components will appear as blank space. The placeholder so let you fill the blank spaces that usually can be seen scrolling fast. The list has two main blank spaces. The first space starts from the top of the scroll view area end to the first loaded item. The second space starts from the last loaded item to the end of the scroll area.

This setting permit you to replace or add a repeated background to this two blank spaces and so to make the illusion of a shimmer scrolling fast.

TypeRequiredDefault
booleanNofalse

placeholderImage​

Placeholder background repeated on fast scrolling.

note

Be careful to different screens resolutions, this solution could be no responsive if you use a single image per screen resolution.

TypeRequired
ImageSourceNo

placeholderComponent​

Placeholder component on fast scrolling. This item could be an SVG pattern or whatever you want to fill the blank space on fast scrolling.

note

This will replace the placeholderImage and need placeholder equal to true.

TypeRequired
component, elementNo

stickySectionHeadersEnabled​

Makes section headers stick to the top of the screen until the next one pushes it off.

TypeRequiredDefault
booleanNotrue

numColumns​

Format the list in column format by placing the elements side by side with x elements per x number of columns per row.

TypeRequiredDefault
numberNo1

inverted​

Reverses the direction of scroll. Uses scale transforms of -1.

TypeRequiredDefault
booleanNofalse

initialScrollIndex​

Specify the initial scroll from the top of the list.

TypeRequiredDefault
numberNo0

insetTop​

Specify the top inset.

TypeRequiredDefault
numberNo0

insetBottom​

Specify the bottom inset.

TypeRequiredDefault
numberNo0

contentInset​

The amount by which the scroll view content is inset from the edges of the scroll view.

TypeRequiredDefault
object: {top: number, left: number, bottom: number, right: number}No{ top: 0, right: 0, left: 0, bottom: 0 }

columnWrapperStyle​

Optional custom style for multi-item rows generated when numColumns > 1.

TypeRequired
View StyleNo

refreshing​

Set this true while waiting for new data from a refresh.

TypeRequiredDefault
booleanNofalse

onViewableItemsChanged​

Called when the viewability of rows changes.

TypeRequired
(callback: { changed: array of ViewTokens, viewableItems: array of ViewTokens }) => voidNo

onRefresh​

If provided, a standard RefreshControl will be added for "Pull to Refresh" functionality. Make sure to also set the refreshing prop correctly.

TypeRequired
functionNo

onEndReached​

onEndReached(info: {distanceFromEnd: number})
TypeRequired
functionNo

Called once when the scroll position gets within onEndReachedThreshold of the rendered content.

onEndReachedThreshold​

How far from the end (in units of visible length of the list) the bottom edge of the list must be from the end of the content to trigger the onEndReached callback. Thus a value of 0.5 will trigger onEndReached when the end of the content is within half the visible length of the list.

TypeRequiredDefault
numberNo0

batchSizeThreshold​

info

A lower value of this prop improve performance and memory usage.
Minimum value limited to 0.5 to display all elements on the visible list with no gaps.

How much threshold must be applied to the batch size to render the elements before rendering the other batch of elements. Thus a value of 0.5 will make the batch size equal to half the visible length of the list (above and below from the current position of the batch).

TypeRequiredDefault
numberNo1

hideMarginalsOnEmpty​

Hide header and footer on empty list.

TypeRequiredDefault
booleanNofalse

hideHeaderOnEmpty​

Hide header on empty list.

TypeRequiredDefault
booleanNofalse

hideFooterOnEmpty​

Hide footer on empty list.

TypeRequiredDefault
booleanNofalse

FlatList Props​

Compatibility

These are compatibility props for a faster FlatList replacement and all these props have an alias. These props will replace their related alias standard props. All of them should be replaced with their related props as best practice.

getItemLayout​

(data, index) => {length: number, offset: number, index: number}

getItemLayout is an optional optimization that allows skipping the measurement of dynamic content if you know the size (height or width) of items ahead of time. getItemLayout is efficient if you have fixed size items, for example:

getItemLayout={(data, index) => (
  {length: ITEM_HEIGHT, offset: ITEM_HEIGHT * index, index}
)}

Adding getItemLayout can be a great performance boost for lists of several thousands items.

Compatibility

This is a compatibility prop for FlatList replacement and so it'll replace the itemHeight prop.

TypeRequired
functionNo

ListEmptyComponent​

Rendered when the list is empty. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

Compatibility

This is a compatibility prop for FlatList replacement and so it'll replace the renderEmpty prop.

TypeRequired
component, elementNo

ListFooterComponent​

Rendered at the bottom of all the items. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

note

You need also to specify the footer height with footerHeight prop or using ListFooterComponentStyle.

Compatibility

This is a compatibility prop for FlatList replacement and so it'll replace the renderFooter prop. If you are creating for the first time the list we suggest to use renderFooter prop instead.

TypeRequired
component, elementNo

ListFooterComponentStyle​

info

This will works only if ListFooterComponent is specified.

Styling for internal View for ListFooterComponent.

TypeRequired
View StyleNo

ListHeaderComponent​

Rendered at the top of all the items. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

note

You need also to specify the header height with headerHeight prop or using ListHeaderComponentStyle.

Compatibility

This is a compatibility prop for FlatList replacement and so it'll replace the renderHeader prop. If you are creating for the first time the list we suggest to use renderHeader prop instead.

TypeRequired
component, elementNo

ListHeaderComponentStyle​

info

This will works only if ListHeaderComponent is specified.

Styling for internal View for ListHeaderComponent.

TypeRequired
View StyleNo