List

A component that organizes items with various styling options including plain, separated, or divided variants.

Import

import List from '@/components/layout/List';

Features

Multiple visual variants (plain, separated, divided)
Customizable spacing between items
Accepts any React components as children
Dark mode compatible
Customizable with Tailwind classes

Props

Prop	Type	Default	Description
`variant`	`'plain' \| 'separated' \| 'divided'`	`'plain'`	Visual style of the list
`spacing`	`number`	`0`	Gap between list items in pixels
`className`	`string`	`''`	Additional Tailwind classes
`style`	`ViewStyle`	—	Additional style object
`children`	`React.ReactNode`	—	List items to render

Basic Usage

// Simple plain list
<List>
  <Text>Item 1</Text>
  <Text>Item 2</Text>
  <Text>Item 3</Text>
</List>
 
// Divided list with separator lines
<List variant="divided">
  <Text className="py-3">Item 1</Text>
  <Text className="py-3">Item 2</Text>
  <Text className="py-3">Item 3</Text>
</List>
 
// Separated list with spacing
<List variant="separated" spacing={16}>
  <View className="p-4 bg-gray-100 dark:bg-gray-800 rounded-lg">
    <Text>Item 1</Text>
  </View>
  <View className="p-4 bg-gray-100 dark:bg-gray-800 rounded-lg">
    <Text>Item 2</Text>
  </View>
</List>

List Variants

Plain

The default variant with no decorations, suitable for simple lists:

<List>
  <Text className="py-2">Simple list item 1</Text>
  <Text className="py-2">Simple list item 2</Text>
  <Text className="py-2">Simple list item 3</Text>
</List>

Divided

Adds dividers between list items, ideal for settings or menus:

<List variant="divided">
  <Text className="py-3">List item with divider 1</Text>
  <Text className="py-3">List item with divider 2</Text>
  <Text className="py-3">List item with divider 3</Text>
</List>

Separated

Creates visual separation between items without lines, useful for card-like items:

<List variant="separated" spacing={12}>
  <View className="bg-gray-100 dark:bg-gray-800 p-4 rounded-lg">
    <Text>Separated item 1</Text>
  </View>
  <View className="bg-gray-100 dark:bg-gray-800 p-4 rounded-lg">
    <Text>Separated item 2</Text>
  </View>
  <View className="bg-gray-100 dark:bg-gray-800 p-4 rounded-lg">
    <Text>Separated item 3</Text>
  </View>
</List>

Best Practices

Choose the Right Variant

Select the appropriate variant based on your content type:

// For simple content with no visual separation
<List variant="plain">
  {/* Simple items */}
</List>
 
// For structured content with clear separation
<List variant="divided">
  {/* Settings, menu items, etc. */}
</List>
 
// For card-like items that need space between them
<List variant="separated" spacing={16}>
  {/* Card items */}
</List>

Consistent Item Structure

Maintain consistent structure across list items for better UX:

// Good: Consistent item structure
<List variant="divided">
  <View className="flex-row justify-between items-center py-3">
    <Text>Item 1</Text>
    <Icon name="ChevronRight" />
  </View>
  
  <View className="flex-row justify-between items-center py-3">
    <Text>Item 2</Text>
    <Icon name="ChevronRight" />
  </View>
</List>
 
// Avoid: Inconsistent item structure
<List variant="divided">
  <Text className="py-3">Item 1</Text>
  
  <View className="flex-row justify-between items-center py-3">
    <Text>Item 2</Text>
    <Icon name="ChevronRight" />
  </View>
</List>

Pair with Section Component

Use List with the Section component for organized content hierarchies:

<Section title="User Settings" padding="md">
  <List variant="divided">
    <Pressable className="py-3">
      <Text>Profile</Text>
    </Pressable>
    <Pressable className="py-3">
      <Text>Privacy</Text>
    </Pressable>
    <Pressable className="py-3">
      <Text>Notifications</Text>
    </Pressable>
  </List>
</Section>

Implementation Details

The List component uses React Native's View component as a container for list items. It applies different styling based on the selected variant:

Plain: No additional styling, just renders items with specified spacing
Separated: Similar to plain but with semantic separation (no dividers)
Divided: Adds dividers between items using Tailwind's divide-y utility

The component handles spacing between items using the gap property in the style object, which provides consistent spacing regardless of the variant chosen.

The List component automatically adapts to dark mode for divided variants, using appropriate divider colors that work in both light and dark themes.

Notes

The List component doesn't add any padding by default; add padding to individual list items or to the List itself via className
When using the divided variant, remember that the divider color automatically adapts to dark mode
For advanced customization, combine with custom item components or wrap in a Card for elevated list sections

List

On this page