Skip to content

Commit ac8a5f4

Browse files
authored
Allow custom list wrappers to use ul elements
Custom list wrappers can now opt into an HTMLUListElement ref without casts. Existing div list wrappers remain the default, and item types and runtime behavior are unchanged.
1 parent 4d73666 commit ac8a5f4

5 files changed

Lines changed: 84 additions & 10 deletions

File tree

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'react-virtuoso': patch
3+
---
4+
5+
Allow a custom `List` wrapper to render a `ul` instead of a `div`, keeping its forwarded `ref` typed to the chosen element. `Item` is unchanged.

‎packages/react-virtuoso/src/component-interfaces/Virtuoso.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -188,7 +188,7 @@ export interface VirtuosoProps<Data, Context> extends ListRootProps {
188188
/**
189189
* Use the `components` property for advanced customization of the elements rendered by the list.
190190
*/
191-
components?: Components<Data, Context>
191+
components?: Components<Data, Context, any>
192192

193193
/**
194194
* If specified, the component will use the function to generate the `key` property for each list item.

‎packages/react-virtuoso/src/component-interfaces/VirtuosoGrid.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -103,7 +103,7 @@ export interface VirtuosoGridProps<Data, Context = unknown> extends GridRootProp
103103
/**
104104
* Use the `components` property for advanced customization of the elements rendered by the list.
105105
*/
106-
components?: GridComponents<Context>
106+
components?: GridComponents<Context, any>
107107

108108
/**
109109
* If specified, the component will use the function to generate the `key` property for each list item.

‎packages/react-virtuoso/src/interfaces.ts‎

Lines changed: 14 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ export interface ContextProp<Context> {
5151
* @see {@link VirtuosoProps.components} for usage in Virtuoso
5252
* @group Virtuoso
5353
*/
54-
export interface Components<Data = unknown, Context = unknown> {
54+
export interface Components<Data = unknown, Context = unknown, ListEl extends HTMLDivElement | HTMLUListElement = HTMLDivElement> {
5555
/**
5656
* Set to render a custom UI when the list is empty.
5757
*/
@@ -79,7 +79,7 @@ export interface Components<Data = unknown, Context = unknown> {
7979
/**
8080
* Set to customize the items wrapper. Use only if you would like to render list from elements different than a `div`.
8181
*/
82-
List?: React.ComponentType<ListProps & ContextProp<Context>>
82+
List?: React.ComponentType<ListProps<ListEl> & ContextProp<Context>>
8383

8484
/**
8585
* Set to customize the outermost scrollable element. This should not be necessary in general,
@@ -203,7 +203,7 @@ export type FollowOutputScalarType = 'auto' | 'smooth' | boolean
203203
* @see {@link VirtuosoGridProps.components} for usage in VirtuosoGrid
204204
* @group VirtuosoGrid
205205
*/
206-
export interface GridComponents<Context = any> {
206+
export interface GridComponents<Context = any, ListEl extends HTMLDivElement | HTMLUListElement = HTMLDivElement> {
207207
/**
208208
* Set to render a component at the bottom of the list.
209209
*/
@@ -224,7 +224,7 @@ export interface GridComponents<Context = any> {
224224
/**
225225
* Set to customize the items wrapper. Use only if you would like to render list from elements different than a `div`.
226226
*/
227-
List?: React.ComponentType<GridListProps & ContextProp<Context>>
227+
List?: React.ComponentType<GridListProps<ListEl> & ContextProp<Context>>
228228

229229
/**
230230
* Set to customize the outermost scrollable element. This should not be necessary in general,
@@ -297,8 +297,11 @@ export type GridItemProps = Pick<React.ComponentProps<'div'>, 'children' | 'clas
297297
* Passed to the GridComponents.List custom component
298298
* @group VirtuosoGrid
299299
*/
300-
export type GridListProps = Pick<React.ComponentProps<'div'>, 'children' | 'className' | 'style'> &
301-
React.RefAttributes<HTMLDivElement> & {
300+
export type GridListProps<El extends HTMLDivElement | HTMLUListElement = HTMLDivElement> = Pick<
301+
React.ComponentProps<'div'>,
302+
'children' | 'className' | 'style'
303+
> &
304+
React.RefAttributes<El> & {
302305
'data-testid': string
303306
}
304307

@@ -467,8 +470,11 @@ export type ListItem<Data> = GroupItem<Data> | RecordItem<Data>
467470
* Passed to the Components.List custom component
468471
* @group Virtuoso
469472
*/
470-
export type ListProps = Pick<React.ComponentProps<'div'>, 'children' | 'style'> &
471-
React.RefAttributes<HTMLDivElement> & {
473+
export type ListProps<El extends HTMLDivElement | HTMLUListElement = HTMLDivElement> = Pick<
474+
React.ComponentProps<'div'>,
475+
'children' | 'style'
476+
> &
477+
React.RefAttributes<El> & {
472478
'data-testid': string
473479
}
474480

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
import * as React from 'react'
2+
3+
import { Virtuoso, VirtuosoGrid } from '../src'
4+
5+
import type { Components, GridComponents } from '../src'
6+
7+
interface Row {
8+
id: number
9+
}
10+
11+
/**
12+
* Issue #864: a custom `List` wrapper may render a `ul` instead of a `div`.
13+
* The host element is a type parameter on `Components`/`GridComponents`, so
14+
* an explicitly typed `ul` list stays fully typed, while an untyped inline
15+
* `forwardRef` list (the common case) still compiles without annotation.
16+
* Checked by `pnpm typecheck` (this file is not a runtime vitest case).
17+
*/
18+
const DivList: Components['List'] = React.forwardRef(function DivList({ style, children }, ref) {
19+
return (
20+
<div ref={ref} style={style}>
21+
{children}
22+
</div>
23+
)
24+
})
25+
26+
export const inlineForwardRefList = (
27+
<Virtuoso data={[{ id: 1 }]} components={{ List: React.forwardRef((props, ref) => <div {...props} ref={ref} />) }} />
28+
)
29+
30+
export const explicitTypeArgsUsage = <Virtuoso<Row, unknown> data={[{ id: 1 }]} itemContent={(_, row) => row.id} />
31+
32+
const LiItem: Components<Row>['Item'] = ({ children, context: _context, item: _item, ...props }) => <li {...props}>{children}</li>
33+
34+
const UlList: Components<unknown, unknown, HTMLUListElement>['List'] = React.forwardRef(function UlList({ style, children }, ref) {
35+
return (
36+
<ul ref={ref} style={style}>
37+
{children}
38+
</ul>
39+
)
40+
})
41+
42+
const GridUlList: GridComponents<unknown, HTMLUListElement>['List'] = React.forwardRef(function GridUlList(
43+
{ style, children, ...props },
44+
ref
45+
) {
46+
return (
47+
<ul ref={ref} style={style} {...props}>
48+
{children}
49+
</ul>
50+
)
51+
})
52+
53+
type UlListRef = React.ComponentProps<NonNullable<Components<unknown, unknown, HTMLUListElement>['List']>>['ref']
54+
55+
// The forwarded ref stays narrowed to the chosen host element. If it widened back to `any`, a
56+
// `div` ref would become assignable here and this would resolve to `never`.
57+
export const ulListRefStaysChecked: React.Ref<HTMLDivElement> extends UlListRef ? never : true = true
58+
59+
export const typedUlListUsage = <Virtuoso data={[{ id: 1 }]} components={{ List: UlList }} />
60+
61+
export const typedGridUlListUsage = <VirtuosoGrid data={[{ id: 1 }]} components={{ List: GridUlList }} />
62+
63+
export { DivList, GridUlList, LiItem, UlList }

0 commit comments

Comments
 (0)