Skip to content

Commit b2fe9ed

Browse files
bvaughnbvaughn
authored
Update README.md docs with component prop types (#873)
1 parent 2d844ea commit b2fe9ed

File tree

7 files changed

+468
-67
lines changed

7 files changed

+468
-67
lines changed

‎README.md‎

Lines changed: 272 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -24,12 +24,280 @@ Begin by installing the library from NPM:
2424
npm install react-window
2525
```
2626

27+
## TypeScript types
28+
29+
TypeScript definitions are included within the published `dist` folder
30+
2731
## Documentation
2832

29-
Documentation for this project is available at [react-window.vercel.app](https://react-window.vercel.app/).
33+
Documentation for this project is available at [react-window.vercel.app](https://react-window.vercel.app/); version 1.x documentation can be found at [react-window-v1.vercel.app](https://react-window-v1.vercel.app/).
3034

31-
> **Note**: Older version 1.x documentation can be found at [react-window-v1.vercel.app](https://react-window-v1.vercel.app/) or on the NPM page for a specific version, e.g. [1.8.11](https://www.npmjs.com/package/react-window/v/1.8.11).)
35+
### List
3236

33-
## TypeScript types
37+
#### Required props
3438

35-
TypeScript definitions are included within the published `dist` folder
39+
<!-- List:required:begin -->
40+
41+
<table>
42+
<thead>
43+
<tr>
44+
<th>Name</th>
45+
<th>Description</th>
46+
</tr>
47+
</thead>
48+
<tbody>
49+
<tr>
50+
<td>rowComponent</td>
51+
<td><p>React component responsible for rendering a row.</p>
52+
<p>This component will receive an <code>index</code> and <code>style</code> prop by default.
53+
Additionally it will receive prop values passed to <code>rowProps</code>.</p>
54+
<p>ℹ️ The prop types for this component are exported as <code>RowComponentProps</code></p>
55+
</td>
56+
</tr>
57+
<tr>
58+
<td>rowCount</td>
59+
<td><p>Number of items to be rendered in the list.</p>
60+
</td>
61+
</tr>
62+
<tr>
63+
<td>rowHeight</td>
64+
<td><p>Row height; the following formats are supported:</p>
65+
<ul>
66+
<li>number of pixels (number)</li>
67+
<li>percentage of the grid&#39;s current height (string)</li>
68+
<li>function that returns the row height (in pixels) given an index and <code>cellProps</code></li>
69+
<li>dynamic row height cache returned by the <code>useDynamicRowHeight</code> hook</li>
70+
</ul>
71+
<p>⚠️ Dynamic row heights are not as efficient as predetermined sizes.
72+
It&#39;s recommended to provide your own height values if they can be determined ahead of time.</p>
73+
</td>
74+
</tr>
75+
<tr>
76+
<td>rowProps</td>
77+
<td><p>Additional props to be passed to the row-rendering component.
78+
List will automatically re-render rows when values in this object change.</p>
79+
<p>⚠️ This object must not contain <code>ariaAttributes</code>, <code>index</code>, or <code>style</code> props.</p>
80+
</td>
81+
</tr>
82+
</tbody>
83+
</table>
84+
85+
<!-- List:required:end -->
86+
87+
#### Optional props
88+
89+
<!-- List:optional:begin -->
90+
91+
<table>
92+
<thead>
93+
<tr>
94+
<th>Name</th>
95+
<th>Description</th>
96+
</tr>
97+
</thead>
98+
<tbody>
99+
<tr>
100+
<td>className</td>
101+
<td><p>CSS class name.</p>
102+
</td>
103+
</tr>
104+
<tr>
105+
<td>style</td>
106+
<td><p>Optional CSS properties.
107+
The list of rows will fill the height defined by this style.</p>
108+
</td>
109+
</tr>
110+
<tr>
111+
<td>children</td>
112+
<td><p>Additional content to be rendered within the list (above cells).
113+
This property can be used to render things like overlays or tooltips.</p>
114+
</td>
115+
</tr>
116+
<tr>
117+
<td>defaultHeight</td>
118+
<td><p>Default height of list for initial render.
119+
This value is important for server rendering.</p>
120+
</td>
121+
</tr>
122+
<tr>
123+
<td>listRef</td>
124+
<td><p>Ref used to interact with this component&#39;s imperative API.</p>
125+
<p>This API has imperative methods for scrolling and a getter for the outermost DOM element.</p>
126+
<p>ℹ️ The <code>useListRef</code> and <code>useListCallbackRef</code> hooks are exported for convenience use in TypeScript projects.</p>
127+
</td>
128+
</tr>
129+
<tr>
130+
<td>onResize</td>
131+
<td><p>Callback notified when the List&#39;s outermost HTMLElement resizes.
132+
This may be used to (re)scroll a row into view.</p>
133+
</td>
134+
</tr>
135+
<tr>
136+
<td>onRowsRendered</td>
137+
<td><p>Callback notified when the range of visible rows changes.</p>
138+
</td>
139+
</tr>
140+
<tr>
141+
<td>overscanCount</td>
142+
<td><p>How many additional rows to render outside of the visible area.
143+
This can reduce visual flickering near the edges of a list when scrolling.</p>
144+
</td>
145+
</tr>
146+
<tr>
147+
<td>tagName</td>
148+
<td><p>Can be used to override the root HTML element rendered by the List component.
149+
The default value is &quot;div&quot;, meaning that List renders an HTMLDivElement as its root.</p>
150+
<p>⚠️ In most use cases the default ARIA roles are sufficient and this prop is not needed.</p>
151+
</td>
152+
</tr>
153+
</tbody>
154+
</table>
155+
156+
<!-- List:optional:end -->
157+
158+
### Grid
159+
160+
#### Required props
161+
162+
<!-- Grid:required:begin -->
163+
164+
<table>
165+
<thead>
166+
<tr>
167+
<th>Name</th>
168+
<th>Description</th>
169+
</tr>
170+
</thead>
171+
<tbody>
172+
<tr>
173+
<td>cellComponent</td>
174+
<td><p>React component responsible for rendering a cell.</p>
175+
<p>This component will receive an <code>index</code> and <code>style</code> prop by default.
176+
Additionally it will receive prop values passed to <code>cellProps</code>.</p>
177+
<p>ℹ️ The prop types for this component are exported as <code>CellComponentProps</code></p>
178+
</td>
179+
</tr>
180+
<tr>
181+
<td>cellProps</td>
182+
<td><p>Additional props to be passed to the cell-rendering component.
183+
Grid will automatically re-render cells when values in this object change.</p>
184+
<p>⚠️ This object must not contain <code>ariaAttributes</code>, <code>columnIndex</code>, <code>rowIndex</code>, or <code>style</code> props.</p>
185+
</td>
186+
</tr>
187+
<tr>
188+
<td>columnCount</td>
189+
<td><p>Number of columns to be rendered in the grid.</p>
190+
</td>
191+
</tr>
192+
<tr>
193+
<td>columnWidth</td>
194+
<td><p>Column width; the following formats are supported:</p>
195+
<ul>
196+
<li>number of pixels (number)</li>
197+
<li>percentage of the grid&#39;s current width (string)</li>
198+
<li>function that returns the row width (in pixels) given an index and <code>cellProps</code></li>
199+
</ul>
200+
</td>
201+
</tr>
202+
<tr>
203+
<td>rowCount</td>
204+
<td><p>Number of rows to be rendered in the grid.</p>
205+
</td>
206+
</tr>
207+
<tr>
208+
<td>rowHeight</td>
209+
<td><p>Row height; the following formats are supported:</p>
210+
<ul>
211+
<li>number of pixels (number)</li>
212+
<li>percentage of the grid&#39;s current height (string)</li>
213+
<li>function that returns the row height (in pixels) given an index and <code>cellProps</code></li>
214+
</ul>
215+
</td>
216+
</tr>
217+
</tbody>
218+
</table>
219+
220+
<!-- Grid:required:end -->
221+
222+
#### Optional props
223+
224+
<!-- Grid:optional:begin -->
225+
226+
<table>
227+
<thead>
228+
<tr>
229+
<th>Name</th>
230+
<th>Description</th>
231+
</tr>
232+
</thead>
233+
<tbody>
234+
<tr>
235+
<td>className</td>
236+
<td><p>CSS class name.</p>
237+
</td>
238+
</tr>
239+
<tr>
240+
<td>dir</td>
241+
<td><p>Corresponds to the HTML dir attribute:
242+
<a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/dir">https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/dir</a></p>
243+
</td>
244+
</tr>
245+
<tr>
246+
<td>style</td>
247+
<td><p>Optional CSS properties.
248+
The grid of cells will fill the height and width defined by this style.</p>
249+
</td>
250+
</tr>
251+
<tr>
252+
<td>children</td>
253+
<td><p>Additional content to be rendered within the grid (above cells).
254+
This property can be used to render things like overlays or tooltips.</p>
255+
</td>
256+
</tr>
257+
<tr>
258+
<td>defaultHeight</td>
259+
<td><p>Default height of grid for initial render.
260+
This value is important for server rendering.</p>
261+
</td>
262+
</tr>
263+
<tr>
264+
<td>defaultWidth</td>
265+
<td><p>Default width of grid for initial render.
266+
This value is important for server rendering.</p>
267+
</td>
268+
</tr>
269+
<tr>
270+
<td>gridRef</td>
271+
<td><p>Ref used to interact with this component&#39;s imperative API.</p>
272+
<p>This API has imperative methods for scrolling and a getter for the outermost DOM element.</p>
273+
<p>ℹ️ The <code>useGridRef</code> and <code>useGridCallbackRef</code> hooks are exported for convenience use in TypeScript projects.</p>
274+
</td>
275+
</tr>
276+
<tr>
277+
<td>onCellsRendered</td>
278+
<td><p>Callback notified when the range of rendered cells changes.</p>
279+
</td>
280+
</tr>
281+
<tr>
282+
<td>onResize</td>
283+
<td><p>Callback notified when the Grid&#39;s outermost HTMLElement resizes.
284+
This may be used to (re)scroll a cell into view.</p>
285+
</td>
286+
</tr>
287+
<tr>
288+
<td>overscanCount</td>
289+
<td><p>How many additional rows/columns to render outside of the visible area.
290+
This can reduce visual flickering near the edges of a grid when scrolling.</p>
291+
</td>
292+
</tr>
293+
<tr>
294+
<td>tagName</td>
295+
<td><p>Can be used to override the root HTML element rendered by the List component.
296+
The default value is &quot;div&quot;, meaning that List renders an HTMLDivElement as its root.</p>
297+
<p>⚠️ In most use cases the default ARIA roles are sufficient and this prop is not needed.</p>
298+
</td>
299+
</tr>
300+
</tbody>
301+
</table>
302+
303+
<!-- Grid:optional:end -->

‎package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,7 @@
7474
"husky": "^9.1.7",
7575
"jsdom": "^26.1.0",
7676
"lint-staged": "^16.1.4",
77+
"marked": "^16.4.1",
7778
"postcss": "^8.5.6",
7879
"prettier": "3.6.2",
7980
"react": "^19.1.0",

‎pnpm-lock.yaml‎

Lines changed: 13 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)