0
# Render System
1

2
The render system provides the type interfaces and patterns for rendering list items with proper positioning and styling support.
3

4
## Capabilities
5

6
### Render Function Type
7

8
The core render function interface that defines how individual list items are rendered.
9

10
```typescript { .api }
11
/**
12
 * Function type for rendering individual list items (available through ListProps.children)
13
 * @param item - The data item to render
14
 * @param index - Position of the item in the data array
15
 * @param props - Additional rendering properties
16
 * @returns React node representing the rendered item
17
 */
18
type RenderFunc<T> = (
19
  item: T,
20
  index: number,
21
  props: { 
22
    style: React.CSSProperties; 
23
    offsetX: number;
24
  }
25
) => React.ReactNode;
26
```
27

28
The render function is called for each visible item and receives:
29
- `item`: The actual data from the `data` array
30
- `index`: The item's position in the original data array
31
- `props.style`: CSS styles for positioning (crucial for virtualization)
32
- `props.offsetX`: Horizontal offset for horizontal scrolling
33

34
**Usage Examples:**
35

36
```typescript
37
import List from "rc-virtual-list";
38

39
// Basic render function
40
<List data={items} height={300} itemHeight={50} itemKey="id">
41
  {(item, index) => (
42
    <div>{item.name}</div>
43
  )}
44
</List>
45

46
// Using all render parameters
47
<List data={items} height={300} itemHeight={50} itemKey="id">
48
  {(item, index, { style, offsetX }) => (
49
    <div 
50
      style={style} // Important: Apply the provided style
51
      className={index % 2 === 0 ? 'even' : 'odd'}
52
    >
53
      <span>#{index}: {item.name}</span>
54
      {offsetX > 0 && <span>Offset: {offsetX}px</span>}
55
    </div>
56
  )}
57
</List>
58

59
// Complex item rendering
60
<List data={products} height={400} itemHeight={80} itemKey="id">
61
  {(product, index, { style }) => (
62
    <div style={style} className="product-item">
63
      <img src={product.image} alt={product.name} />
64
      <div className="product-details">
65
        <h3>{product.name}</h3>
66
        <p>{product.description}</p>
67
        <span className="price">${product.price}</span>
68
      </div>
69
    </div>
70
  )}
71
</List>
72
```
73

74
### Extra Render Information
75

76
Information provided to the `extraRender` function for advanced rendering scenarios.
77

78
```typescript { .api }
79
/**
80
 * Information provided to extraRender function
81
 */
82
interface ExtraRenderInfo {
83
  /** First visible item index */
84
  start: number;
85
  /** Last visible item index */
86
  end: number;
87
  /** Whether virtualization is currently active */
88
  virtual: boolean;
89
  /** Current horizontal offset for horizontal scrolling */
90
  offsetX: number;
91
  /** Current vertical offset */
92
  offsetY: number;
93
  /** Whether the list is in RTL mode */
94
  rtl: boolean;
95
  /** Function to get size information for items */
96
  getSize: GetSize;
97
}
98
```
99

100
**Usage Example:**
101

102
```typescript
103
import List from "rc-virtual-list";
104

105
const ListWithExtra = () => {
106
  const extraRender = (info: ExtraRenderInfo) => {
107
    return (
108
      <div style={{ 
109
        position: 'absolute', 
110
        top: 0, 
111
        right: 0, 
112
        padding: '8px',
113
        background: 'rgba(0,0,0,0.5)',
114
        color: 'white'
115
      }}>
116
        Showing items {info.start}-{info.end}
117
        {info.virtual && ' (virtualized)'}
118
      </div>
119
    );
120
  };
121

122
  return (
123
    <List
124
      data={data}
125
      height={300}
126
      itemHeight={50}
127
      itemKey="id"
128
      extraRender={extraRender}
129
    >
130
      {(item) => <div>{item.name}</div>}
131
    </List>
132
  );
133
};
134
```
135

136
### Get Size Function Type
137

138
```typescript { .api }
139
/**
140
 * Function to get size information for item ranges
141
 * @param startKey - Starting item key
142
 * @param endKey - Ending item key (optional)
143
 * @returns Size bounds information
144
 */
145
type GetSize = (
146
  startKey: React.Key, 
147
  endKey?: React.Key
148
) => { 
149
  top: number; 
150
  bottom: number; 
151
};
152
```
153

154
### Shared Configuration
155

156
```typescript { .api }
157
/**
158
 * Shared configuration object passed through the rendering system
159
 */
160
interface SharedConfig<T> {
161
  /** Function to extract keys from data items */
162
  getKey: (item: T) => React.Key;
163
}
164
```
165

166
### Key Extraction Type
167

168
```typescript { .api }
169
/**
170
 * Function type for extracting unique keys from data items
171
 */
172
type GetKey<T> = (item: T) => React.Key;
173
```
174

175
### Best Practices
176

177
#### Style Application
178
Always apply the provided `style` prop to maintain proper virtualization:
179

180
```typescript
181
// ✅ Correct - applies positioning styles
182
{(item, index, { style }) => (
183
  <div style={style}>
184
    {item.content}
185
  </div>
186
)}
187

188
// ❌ Incorrect - virtualization will break
189
{(item, index, { style }) => (
190
  <div>
191
    {item.content}
192
  </div>
193
)}
194
```
195

196
#### Key Stability
197
Use stable, unique keys for optimal performance:
198

199
```typescript
200
// ✅ Good - stable unique key
201
itemKey="id"
202

203
// ✅ Good - function returning stable key
204
itemKey={(item) => item.uniqueId}
205

206
// ❌ Poor - unstable key
207
itemKey={(item) => Math.random()}
208
```
209

210
#### Performance Optimization
211
- Keep render functions simple and avoid heavy computations
212
- Use `React.memo` for complex item components
213
- Avoid creating new objects/functions inside render functions
214
- Cache expensive calculations outside the render function
215

216
```typescript
217
// ✅ Optimized render function
218
const ItemComponent = React.memo(({ item, style }) => (
219
  <div style={style}>
220
    <h3>{item.title}</h3>
221
    <p>{item.description}</p>
222
  </div>
223
));
224

225
<List data={data} height={300} itemHeight={80} itemKey="id">
226
  {(item, index, { style }) => (
227
    <ItemComponent item={item} style={style} />
228
  )}
229
</List>
230
```