Skip to content

Commit 63e2b81

Browse files
bvaughnbvaughn
committed
Update README.md docs with component prop types
1 parent 2d844ea commit 63e2b81

File tree

4 files changed

+532
-62
lines changed

4 files changed

+532
-62
lines changed

‎README.md‎

Lines changed: 377 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,3 +33,380 @@ Documentation for this project is available at [react-window.vercel.app](https:/
3333
## TypeScript types
3434

3535
TypeScript definitions are included within the published `dist` folder
36+
37+
## Components
38+
39+
### List
40+
41+
<!-- List:begin -->
42+
43+
<table>
44+
<thead>
45+
<tr>
46+
<th>Name</th>
47+
<th>Required?</th>
48+
<th>Type</th>
49+
<th>Description</th>
50+
</tr>
51+
</thead>
52+
<tbody>
53+
<tr>
54+
<td>className</td>
55+
<td></td>
56+
<td>
57+
<code>string | undefined</code>
58+
</td>
59+
<td>
60+
CSS class name.
61+
</td>
62+
</tr>
63+
<tr>
64+
<td>style</td>
65+
<td></td>
66+
<td>
67+
<code>CSSProperties | undefined</code>
68+
</td>
69+
<td>
70+
Optional CSS properties. The list of rows will fill the height defined by this style.
71+
</td>
72+
</tr>
73+
<tr>
74+
<td>children</td>
75+
<td></td>
76+
<td>
77+
<code>ReactNode</code>
78+
</td>
79+
<td>
80+
Additional content to be rendered within the list (above cells). This property can be used to render things like overlays or tooltips.
81+
</td>
82+
</tr>
83+
<tr>
84+
<td>defaultHeight</td>
85+
<td></td>
86+
<td>
87+
<code>number | undefined</code>
88+
</td>
89+
<td>
90+
Default height of list for initial render. This value is important for server rendering.
91+
</td>
92+
</tr>
93+
<tr>
94+
<td>listRef</td>
95+
<td></td>
96+
<td>
97+
<code>Ref<{ readonly element: HTMLDivElement | null; scrollToRow(config: { align?: "auto" | "center" | "end" | "smart" | "start" | undefined; behavior?: "auto" | "instant" | "smooth" | undefined; index: number; }): void; }> | undefined</code>
98+
</td>
99+
<td>
100+
Ref used to interact with this component's imperative API.
101+
102+
This API has imperative methods for scrolling and a getter for the outermost DOM element.
103+
ℹ️ The `useListRef` and `useListCallbackRef` hooks are exported for convenience use in TypeScript projects.
104+
</td>
105+
</tr>
106+
<tr>
107+
<td>onResize</td>
108+
<td></td>
109+
<td>
110+
<code>((size: { height: number; width: number; }, prevSize: { height: number; width: number; }) => void) | undefined</code>
111+
</td>
112+
<td>
113+
Callback notified when the List's outermost HTMLElement resizes. This may be used to (re)scroll a row into view.
114+
</td>
115+
</tr>
116+
<tr>
117+
<td>onRowsRendered</td>
118+
<td></td>
119+
<td>
120+
<code>((visibleRows: { startIndex: number; stopIndex: number; }, allRows: { startIndex: number; stopIndex: number; }) => void) | undefined</code>
121+
</td>
122+
<td>
123+
Callback notified when the range of visible rows changes.
124+
</td>
125+
</tr>
126+
<tr>
127+
<td>overscanCount</td>
128+
<td></td>
129+
<td>
130+
<code>number | undefined</code>
131+
</td>
132+
<td>
133+
How many additional rows to render outside of the visible area. This can reduce visual flickering near the edges of a list when scrolling.
134+
</td>
135+
</tr>
136+
<tr>
137+
<td>rowComponent</td>
138+
<td>✓</td>
139+
<td>
140+
<code>(props: { ariaAttributes: { "aria-posinset": number; "aria-setsize": number; role: "listitem"; }; index: number; style: CSSProperties; } & RowProps) => ReactNode</code>
141+
</td>
142+
<td>
143+
React component responsible for rendering a row.
144+
145+
This component will receive an `index` and `style` prop by default. Additionally it will receive prop values passed to `rowProps`.
146+
147+
ℹ️ The prop types for this component are exported as `RowComponentProps`
148+
</td>
149+
</tr>
150+
<tr>
151+
<td>rowCount</td>
152+
<td>✓</td>
153+
<td>
154+
<code>number</code>
155+
</td>
156+
<td>
157+
Number of items to be rendered in the list.
158+
</td>
159+
</tr>
160+
<tr>
161+
<td>rowHeight</td>
162+
<td>✓</td>
163+
<td>
164+
<code>string | number | DynamicRowHeight | ((index: number, cellProps: RowProps) => number)</code>
165+
</td>
166+
<td>
167+
Row height; the following formats are supported: - number of pixels (number)
168+
169+
- percentage of the grid's current height (string)
170+
- function that returns the row height (in pixels) given an index and `cellProps`
171+
- dynamic row height cache returned by the `useDynamicRowHeight` hook
172+
173+
⚠️ Dynamic row heights are not as efficient as predetermined sizes.
174+
It's recommended to provide your own height values if they can be determined ahead of time.
175+
</td>
176+
</tr>
177+
<tr>
178+
<td>rowProps</td>
179+
<td>✓</td>
180+
<td>
181+
<code>RowProps</code>
182+
</td>
183+
<td>
184+
Additional props to be passed to the row-rendering component. List will automatically re-render rows when values in this object change.
185+
186+
⚠️ This object must not contain `ariaAttributes`, `index`, or `style` props.
187+
</td>
188+
</tr>
189+
<tr>
190+
<td>tagName</td>
191+
<td></td>
192+
<td>
193+
<code>keyof IntrinsicElements | undefined</code>
194+
</td>
195+
<td>
196+
Can be used to override the root HTML element rendered by the List component. The default value is "div", meaning that List renders an HTMLDivElement as its root.
197+
198+
⚠️ In most use cases the default ARIA roles are sufficient and this prop is not needed.
199+
</td>
200+
</tr>
201+
202+
</tbody>
203+
</table>
204+
205+
<!-- List:end -->
206+
207+
### Grid
208+
209+
<!-- Grid:begin -->
210+
211+
<table>
212+
<thead>
213+
<tr>
214+
<th>Name</th>
215+
<th>Required?</th>
216+
<th>Type</th>
217+
<th>Description</th>
218+
</tr>
219+
</thead>
220+
<tbody>
221+
<tr>
222+
<td>className</td>
223+
<td></td>
224+
<td>
225+
<code>string | undefined</code>
226+
</td>
227+
<td>
228+
CSS class name.
229+
</td>
230+
</tr>
231+
<tr>
232+
<td>dir</td>
233+
<td></td>
234+
<td>
235+
<code>string | undefined</code>
236+
</td>
237+
<td>
238+
Corresponds to the HTML dir attribute: https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/dir
239+
</td>
240+
</tr>
241+
<tr>
242+
<td>style</td>
243+
<td></td>
244+
<td>
245+
<code>CSSProperties | undefined</code>
246+
</td>
247+
<td>
248+
Optional CSS properties. The grid of cells will fill the height and width defined by this style.
249+
</td>
250+
</tr>
251+
<tr>
252+
<td>children</td>
253+
<td></td>
254+
<td>
255+
<code>ReactNode</code>
256+
</td>
257+
<td>
258+
Additional content to be rendered within the grid (above cells). This property can be used to render things like overlays or tooltips.
259+
</td>
260+
</tr>
261+
<tr>
262+
<td>cellComponent</td>
263+
<td>✓</td>
264+
<td>
265+
<code>(props: { ariaAttributes: { "aria-colindex": number; role: "gridcell"; }; columnIndex: number; rowIndex: number; style: CSSProperties; } & CellProps) => ReactNode</code>
266+
</td>
267+
<td>
268+
React component responsible for rendering a cell.
269+
270+
This component will receive an `index` and `style` prop by default. Additionally it will receive prop values passed to `cellProps`.
271+
272+
ℹ️ The prop types for this component are exported as `CellComponentProps`
273+
</td>
274+
</tr>
275+
<tr>
276+
<td>cellProps</td>
277+
<td>✓</td>
278+
<td>
279+
<code>CellProps</code>
280+
</td>
281+
<td>
282+
Additional props to be passed to the cell-rendering component. Grid will automatically re-render cells when values in this object change.
283+
284+
⚠️ This object must not contain `ariaAttributes`, `columnIndex`, `rowIndex`, or `style` props.
285+
</td>
286+
</tr>
287+
<tr>
288+
<td>columnCount</td>
289+
<td>✓</td>
290+
<td>
291+
<code>number</code>
292+
</td>
293+
<td>
294+
Number of columns to be rendered in the grid.
295+
</td>
296+
</tr>
297+
<tr>
298+
<td>columnWidth</td>
299+
<td>✓</td>
300+
<td>
301+
<code>string | number | ((index: number, cellProps: CellProps) => number)</code>
302+
</td>
303+
<td>
304+
Column width; the following formats are supported: - number of pixels (number)
305+
306+
- percentage of the grid's current width (string)
307+
- function that returns the row width (in pixels) given an index and `cellProps`
308+
</td>
309+
</tr>
310+
<tr>
311+
<td>defaultHeight</td>
312+
<td></td>
313+
<td>
314+
<code>number | undefined</code>
315+
</td>
316+
<td>
317+
Default height of grid for initial render. This value is important for server rendering.
318+
</td>
319+
</tr>
320+
<tr>
321+
<td>defaultWidth</td>
322+
<td></td>
323+
<td>
324+
<code>number | undefined</code>
325+
</td>
326+
<td>
327+
Default width of grid for initial render. This value is important for server rendering.
328+
</td>
329+
</tr>
330+
<tr>
331+
<td>gridRef</td>
332+
<td></td>
333+
<td>
334+
<code>Ref<{ readonly element: HTMLDivElement | null; scrollToCell(config: { behavior?: "auto" | "instant" | "smooth" | undefined; columnAlign?: "auto" | "center" | "end" | "smart" | "start" | undefined; columnIndex: number; rowAlign?: "auto" | ... 4 more ... | undefined; rowIndex: number; }): void; scrollToColumn(config: ...</code>
335+
</td>
336+
<td>
337+
Ref used to interact with this component's imperative API.
338+
339+
This API has imperative methods for scrolling and a getter for the outermost DOM element.
340+
ℹ️ The `useGridRef` and `useGridCallbackRef` hooks are exported for convenience use in TypeScript projects.
341+
</td>
342+
</tr>
343+
<tr>
344+
<td>onCellsRendered</td>
345+
<td></td>
346+
<td>
347+
<code>((visibleCells: { columnStartIndex: number; columnStopIndex: number; rowStartIndex: number; rowStopIndex: number; }, allCells: { columnStartIndex: number; columnStopIndex: number; rowStartIndex: number; rowStopIndex: number; }) => void) | undefined</code>
348+
</td>
349+
<td>
350+
Callback notified when the range of rendered cells changes.
351+
</td>
352+
</tr>
353+
<tr>
354+
<td>onResize</td>
355+
<td></td>
356+
<td>
357+
<code>((size: { height: number; width: number; }, prevSize: { height: number; width: number; }) => void) | undefined</code>
358+
</td>
359+
<td>
360+
Callback notified when the Grid's outermost HTMLElement resizes. This may be used to (re)scroll a cell into view.
361+
</td>
362+
</tr>
363+
<tr>
364+
<td>overscanCount</td>
365+
<td></td>
366+
<td>
367+
<code>number | undefined</code>
368+
</td>
369+
<td>
370+
How many additional rows/columns to render outside of the visible area. This can reduce visual flickering near the edges of a grid when scrolling.
371+
</td>
372+
</tr>
373+
<tr>
374+
<td>rowCount</td>
375+
<td>✓</td>
376+
<td>
377+
<code>number</code>
378+
</td>
379+
<td>
380+
Number of rows to be rendered in the grid.
381+
</td>
382+
</tr>
383+
<tr>
384+
<td>rowHeight</td>
385+
<td>✓</td>
386+
<td>
387+
<code>string | number | ((index: number, cellProps: CellProps) => number)</code>
388+
</td>
389+
<td>
390+
Row height; the following formats are supported: - number of pixels (number)
391+
392+
- percentage of the grid's current height (string)
393+
- function that returns the row height (in pixels) given an index and `cellProps`
394+
</td>
395+
</tr>
396+
<tr>
397+
<td>tagName</td>
398+
<td></td>
399+
<td>
400+
<code>keyof IntrinsicElements | undefined</code>
401+
</td>
402+
<td>
403+
Can be used to override the root HTML element rendered by the List component. The default value is "div", meaning that List renders an HTMLDivElement as its root.
404+
405+
⚠️ In most use cases the default ARIA roles are sufficient and this prop is not needed.
406+
</td>
407+
</tr>
408+
409+
</tbody>
410+
</table>
411+
412+
<!-- Grid:end -->

0 commit comments

Comments
 (0)