Creating Lists

In the You.i Engine One workflow, AE components are associated with You.i Engine C++ classes. In AE, you can use the Comments field in the Project panel to display what classes are being used. You can use the Properties panel to set which classes are being used. In addition to supporting Facebook React Native list components (ScrollView, VirtualizedList, and FlatList), You.i React Native provides the following custom components for lists: ScrollRef and ListRef.

Using ListRef

Within a composition, you can define a list by creating an After Effects composition of type List. This can then be referenced as a ListRef child of a Composition. The List Composition doesn’t need to contain any children, but if it does, they should be marked as placeholder items (not to be included in the scene tree when exported). If children of your List aren’t marked as placeholder items, loading them results in a red error screen, listing the incompatible layers (up to a limit of five layers).

ListRef attempts to mirror a React Native FlatList (receiving the benefits of a virtualized list), and ultimately renders it as such. Like a Facebook React Native FlatList, there are some minimum props required to get started.

Prop Description
name Name of List composition
data Array of objects to populate the list
renderItem Method to receive data item (and index) to render a single list item.

List Styling and Direction

You can set the padding, margins, and position of list items (text, images) of a ListRef within the list item’s style in React Native. These props can also be applied to ScrollRef, ScrollView, FlatList, VirtualizedList, and any other kind of list.

Minimum props to get started:

Prop Description
horizontal Boolean indicating if list direction is horizontal or vertical.
ListHeaderComponent Component that is rendered at the beginning of a list.
ListFooterComponent Component that is rendered at the end of a list.

List Magnets

Minimum props to get started:

Prop Description
snapToAlignment [“start” | “center” | “end”] indicating if the list item in focus should stick at the start, center, or end of the visible list area.
snapToInterval Number to specify offset from start, center, or end of screen. Used alongside snapToAlignment.


Similar to a Facebook React Native FlatList, a ListRef supports the notion of specifying the number of columns a vertical list should have. This creates a grid.

Prop Description
numColumns Number to specify offset from start, center, or end of screen. Used alongside snapToAlignment.

The danger of using numColumns as a way to construct a list becomes evident if you intend for the screen to contain any other content above or below the grid that you wish to scroll with the list.

If the desired effect is to have a List grid inline with other components (Facebook or You.i React Native), then using the numColumns property is likely not appropriate. You can use a couple of approaches to achieve the functionality of a continuous scroll down the screen:

  • Use Flexbox to render items in ScrollView
  • Render a vertical ListRef where each row contains a grouping of items

The former is fine if the number of items is small, and you are not worried about the performance impact of loading all items immediately. If you want the benefits of virtualized lists, and have a large dataset, then the latter is appropriate.

List of Lists

Lists of Lists extends the above sample, but instead of using Flexbox to layout a small group of items, you may have a large data source for each lane. This allows you to take advantage of virtualization and magnets on not just the parent list, but the child lists as well.

You can achieve Carousel support on a ListRef through the After Effects Composition and the You.i Properties Panel on a List.

Using ScrollRef

ScrollRef simply renders all of its child components at once. That makes it very easy to understand and use. On the other hand, this has a performance downside if, for example, you need to display several screens full of content. Creating all JS components and native views for everything at once, much of which may not even be shown, contributes to slower initial rendering and greatly increased memory usage. This is where ListRef comes into play.

ListRef or ScrollRef?

Select the best list type for your particular use case. The characteristics of each are explained below:

Using ScrollRef

For the following use cases, use ScrollRef:

  • Non-virtualized lists
  • Small datasets
  • List contains static items

ScrollView simply renders all its react child components at once. This has a performance downside. For more information on ScrollView, click here. For a list of supported ScrollRef properties, see ScrollView.

Pros to using ScrollRef

  • After initial loading, the complete data is present with optimal scrolling performance as no data needs to be loaded again on the fly.
  • Great for smaller data sets where you want content always in memory and want no loading delay while new items are scrolled.

Cons to using ScrollRef

  • Initial loading takes longer as all item views for the list are created at once. Therefore, not ideal for large data sets due to initial load and memory footprint.
  • Memory footprint increases with the size of the list data, as all that list data needs to be retained during the lifetime of the list.
  • Not optimal for devices or platforms with strict memory limitations.
  • Feature set is not as diverse as ListRef’s.

Using ListRef

For the following use cases, use ListRef:

  • Virtualized lists
  • Large datasets
  • Streaming (dynamic) list items
  • Infinite scrolling

FlatList is a wrapper around VirtualizedList. Virtualization massively improves memory consumption and performance of large lists by maintaining a finite render window of active items and replacing all items outside of the render window with appropriately sized blank space. For more about VirtualizedList, click here.

Not all props are supported with You.i React Native. See the FlatList.

Pros to using ListRef

  • Faster initial loading time, as only the item views for relevant subset of the list data is created and rendered.
  • Better memory footprint as only a subset of the list data is loaded at any given time.
  • Great for large data sets and devices or platforms with strict memory limitations.
  • Richer feature set than ScrollRef.

Cons to using ListRef

  • Scrolling experience is sub-optimal as fast scrolling or slow item loading can reveal white spaces in the list where new items are still actively loaded dynamically while the visible data set is being updated.
  • More loading during list scrolling with a ListRef than with a ScrollRef because views get allocated or unallocated dynamically instead of being all loaded at once and retained in memory.