0
# List Reference
1

2
Programmatic control interface for the List component, providing access to scroll functions and current state information.
3

4
## Capabilities
5

6
### List Reference Interface
7

8
The ref interface provides programmatic control over the list component.
9

10
```typescript { .api }
11
/**
12
 * Reference interface for programmatic List control
13
 */
14
interface ListRef {
15
  /** Direct access to the native DOM element */
16
  nativeElement: HTMLDivElement;
17
  /** Function to programmatically scroll the list */
18
  scrollTo: (arg?: number | ScrollConfig | null) => void;
19
  /** Get current scroll position information */
20
  getScrollInfo: () => ScrollInfo;
21
}
22

23
// Supporting type definitions
24
interface ScrollInfo {
25
  x: number;
26
  y: number;
27
}
28

29
type ScrollConfig = ScrollTarget | ScrollPos;
30

31
type ScrollTarget = 
32
  | { index: number; align?: ScrollAlign; offset?: number; }
33
  | { key: React.Key; align?: ScrollAlign; offset?: number; };
34

35
interface ScrollPos {
36
  left?: number;
37
  top?: number;
38
}
39

40
type ScrollAlign = 'top' | 'bottom' | 'auto';
41
```
42

43
**Usage Example:**
44

45
```typescript
46
import React, { useRef } from "react";
47
import List, { type ListRef } from "rc-virtual-list";
48

49
const ControlledList = () => {
50
  const listRef = useRef<ListRef>(null);
51
  
52
  const scrollToTop = () => {
53
    listRef.current?.scrollTo(0);
54
  };
55
  
56
  const scrollToItem = () => {
57
    listRef.current?.scrollTo({ index: 50, align: 'top' });
58
  };
59
  
60
  const getScrollPosition = () => {
61
    const info = listRef.current?.getScrollInfo();
62
    console.log('Current position:', info?.x, info?.y);
63
  };
64
  
65
  return (
66
    <div>
67
      <button onClick={scrollToTop}>Scroll to Top</button>
68
      <button onClick={scrollToItem}>Scroll to Item 50</button>
69
      <button onClick={getScrollPosition}>Get Position</button>
70
      
71
      <List
72
        ref={listRef}
73
        data={data}
74
        height={300}
75
        itemHeight={40}
76
        itemKey="id"
77
      >
78
        {(item) => <div>{item.name}</div>}
79
      </List>
80
    </div>
81
  );
82
};
83
```
84

85
### Scroll Function
86

87
The `scrollTo` method accepts various argument types for different scrolling behaviors.
88

89
**Scroll by pixel position:**
90
```typescript
91
// Scroll to specific Y position
92
listRef.current.scrollTo(500);
93

94
// Scroll to top
95
listRef.current.scrollTo(0);
96
listRef.current.scrollTo(null);
97
```
98

99
### Scroll Information
100

101
The `getScrollInfo()` method returns the current scroll position with x and y coordinates.
102

103
### Scroll Position Configuration
104

105
```typescript { .api }
106
/**
107
 * Scroll to specific coordinates
108
 */
109
interface ScrollPos {
110
  /** Target horizontal position */
111
  left?: number;
112
  /** Target vertical position */
113
  top?: number;
114
}
115
```
116

117
**Usage Example:**
118
```typescript
119
// Scroll to specific coordinates
120
listRef.current.scrollTo({ left: 100, top: 200 });
121

122
// Scroll only vertically
123
listRef.current.scrollTo({ top: 300 });
124

125
// Scroll only horizontally (when scrollWidth is set)
126
listRef.current.scrollTo({ left: 150 });
127
```
128

129
### Scroll Target Configuration
130

131
```typescript { .api }
132
/**
133
 * Scroll to specific item by index or key
134
 */
135
type ScrollTarget = 
136
  | {
137
      /** Target item index */
138
      index: number;
139
      /** Alignment of the target item in viewport */
140
      align?: ScrollAlign;
141
      /** Additional pixel offset from aligned position */
142
      offset?: number;
143
    }
144
  | {
145
      /** Target item key */
146
      key: React.Key;
147
      /** Alignment of the target item in viewport */
148
      align?: ScrollAlign;
149
      /** Additional pixel offset from aligned position */
150
      offset?: number;
151
    };
152

153
type ScrollAlign = 'top' | 'bottom' | 'auto';
154
```
155

156
**Usage Examples:**
157

158
```typescript
159
// Scroll to item by index
160
listRef.current.scrollTo({ index: 100 });
161
listRef.current.scrollTo({ index: 100, align: 'top' });
162
listRef.current.scrollTo({ index: 100, align: 'bottom' });
163
listRef.current.scrollTo({ index: 100, align: 'auto' }); // Smart alignment
164

165
// Scroll to item by key
166
listRef.current.scrollTo({ key: 'item-42', align: 'top' });
167

168
// With offset
169
listRef.current.scrollTo({ index: 50, align: 'top', offset: 20 });
170
```
171

172
### Scroll Alignment Options
173

174
- **`'top'`**: Align the target item to the top of the viewport
175
- **`'bottom'`**: Align the target item to the bottom of the viewport  
176
- **`'auto'`**: Smart alignment - uses the shortest scroll distance
177

178
### Native Element Access
179

180
The `nativeElement` property provides direct access to the underlying DOM element:
181

182
```typescript
183
// Access DOM element
184
const element = listRef.current.nativeElement;
185

186
// Add event listeners
187
element.addEventListener('scroll', handleScroll);
188

189
// Get DOM measurements
190
const rect = element.getBoundingClientRect();
191
```