Skip to content

Commit b3bbc6e

Browse files
Eliav2Eliav2
committed
Rename renderHiddenItem to renderItemVisibility for clarity and consistency across documentation and components; update related examples and changelog.
1 parent 04b86dd commit b3bbc6e

File tree

5 files changed

+28
-31
lines changed

5 files changed

+28
-31
lines changed

‎CHANGELOG.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
## 0.3.0
66

7-
- Added a new `renderHiddenItem` prop so apps can decide how overflowed children stay mounted (supports React 19
7+
- Added a new `renderItemVisibility` prop so apps can decide how overflowed children stay mounted (supports React 19
88
`Activity` by default and makes it easier to integrate custom skeletons/widgets).
99
- Default hidden-item handling keeps elements connected via either `Activity` (when available) or if not available, simply return null.
1010
- Demo now includes **DynamicSizeExample**, which simulates children that grow from 20px to 50px after load and

‎README.md‎

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -112,19 +112,19 @@ See the **Flush Immediately** example in the live demo.
112112

113113
## API (most used)
114114

115-
| Prop | Type | Default | Notes |
116-
| --------------------- | --------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------- |
117-
| `items` | `T[]` | — | Use with `renderItem`. Omit when using children. |
118-
| `renderItem` | `(item: T, index: number) => ReactNode` | — | How to render each item. |
119-
| `children` | `ReactNode` | — | Alternative to `items + renderItem`. |
120-
| `as` | `React.ElementType` | `"div"` | Polymorphic root element. |
121-
| `maxRows` | `number` | `1` | Visible rows before overflow. |
122-
| `maxVisibleItems` | `number` | `100` | Hard cap on visible items. |
123-
| `renderOverflow` | `(hidden: T[]) => ReactNode` | default chip | Custom overflow UI. |
124-
| `renderOverflowItem` | `(item: T, i: number) => ReactNode` | `renderItem` | For expanded lists/menus. |
125-
| `renderOverflowProps` | `Partial<OverflowElementProps<T>>` | — | Props for default overflow. |
126-
| `flushImmediately` | `boolean` | `true` | `true` (flushSync, no flicker) vs `false` (rAF, faster under resize). |
127-
| `renderHiddenItem` | `(node: ReactNode, meta) => ReactNode` | internal | Control visibility of hidden items (defaults to `React.Activity` if available, otherwise simply return null). |
115+
| Prop | Type | Default | Notes |
116+
| ---------------------- | --------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------- |
117+
| `items` | `T[]` | — | Use with `renderItem`. Omit when using children. |
118+
| `renderItem` | `(item: T, index: number) => ReactNode` | — | How to render each item. |
119+
| `children` | `ReactNode` | — | Alternative to `items + renderItem`. |
120+
| `as` | `React.ElementType` | `"div"` | Polymorphic root element. |
121+
| `maxRows` | `number` | `1` | Visible rows before overflow. |
122+
| `maxVisibleItems` | `number` | `100` | Hard cap on visible items. |
123+
| `renderOverflow` | `(hidden: T[]) => ReactNode` | default chip | Custom overflow UI. |
124+
| `renderOverflowItem` | `(item: T, i: number) => ReactNode` | `renderItem` | For expanded lists/menus. |
125+
| `renderOverflowProps` | `Partial<OverflowElementProps<T>>` | — | Props for default overflow. |
126+
| `flushImmediately` | `boolean` | `true` | `true` (flushSync, no flicker) vs `false` (rAF, faster under resize). |
127+
| `renderItemVisibility` | `(node: ReactNode, meta) => ReactNode` | internal | Control visibility of hidden items (defaults to `React.Activity` if available, otherwise simply return null). |
128128

129129
**Styles:** Root uses `display:flex; flex-wrap:wrap; align-items:center;`. Override via `style`/`className`.
130130

@@ -163,7 +163,7 @@ It’s **expected** you’ll wrap `OverflowList` for product needs (design syste
163163
### Hidden items & React versions
164164

165165
- In React 19.2+, hidden items use `React.Activity` so overflowed children stay mounted while toggling visibility.
166-
- In React 16–18, overflowed nodes unmount during measurement; pass `renderHiddenItem` if you need to keep custom
166+
- In React 16–18, overflowed nodes unmount during measurement; pass `renderItemVisibility` if you need to keep custom
167167
elements or skeletons mounted and control visibility yourself.
168168

169169
---

‎demo/src/examples/DynamicSizeExample.tsx‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ export function DynamicSizeExample() {
4545
<GrowingItem label={item} delay={800 + index * 150} />
4646
)}
4747
style={{ gap: "8px" }}
48-
renderHiddenItem={(node, meta) => (
48+
renderItemVisibility={(node, meta) => (
4949
<span
5050
key={meta.index}
5151
aria-hidden={!meta.visible}
@@ -87,8 +87,8 @@ export function DynamicSizeExample() {
8787
<p>
8888
By default the list temporarily unmounts overflowed children while it measures, so elements that change size
8989
(e.g. skeletons growing from 20px to 50px) can flicker as they re-enter the DOM. React 19.2+ solves this via
90-
<code>React.Activity</code>; in older versions you can pass <code>renderHiddenItem</code> to keep every child
91-
mounted and simply hide the overflowed ones yourself.
90+
<code>React.Activity</code>; in older versions you can pass <code>renderItemVisibility</code> to keep every
91+
child mounted and simply hide the overflowed ones yourself.
9292
</p>
9393

9494
<div className="code-preview">
@@ -102,7 +102,7 @@ export function DynamicSizeExample() {
102102
items={placeholderItems}
103103
renderItem={(item, { index }) => <GrowingItem label={item} delay={800 + index * 150} />}
104104
style={{ gap: "8px" }}
105-
renderHiddenItem={(node, meta) => {
105+
renderItemVisibility={(node, meta) => {
106106
return (
107107
<span key={meta.index} aria-hidden={!meta.visible} style={!meta.visible ? HIDDEN_ITEM_STYLES : undefined}>
108108
{node}
@@ -111,7 +111,7 @@ export function DynamicSizeExample() {
111111
}}
112112
/>
113113
<div className="demo-note" style={{ marginTop: "12px" }}>
114-
<strong>Tip:</strong> In React &lt; 19.2, pass a <code>renderHiddenItem</code> callback like above to keep
114+
<strong>Tip:</strong> In React &lt; 19.2, pass a <code>renderItemVisibility</code> callback like above to keep
115115
custom elements mounted. React 19.2+ users can rely on the built-in <code>React.Activity</code> that the
116116
component uses internally.
117117
</div>

‎demo/src/issues/4/src/App.tsx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ export default function App() {
5555
{item.name}
5656
</WaTag>
5757
)}
58-
renderHiddenItem={(node, meta) => {
58+
renderItemVisibility={(node, meta) => {
5959
return (
6060
<span key={meta.index} aria-hidden={!meta.visible} style={!meta.visible ? HIDDEN_ITEM_STYLES : undefined}>
6161
{node}

‎src/components/OverflowList.tsx‎

Lines changed: 7 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import React, { useRef, useState, Activity } from "react";
1+
import React, { useRef, useState } from "react";
22
import { useForkRef, useIsoLayoutEffect, useResizeObserver } from "../hooks";
33
import { getRowPositionsData } from "../utils";
44
import { DefaultOverflowElement } from "./DefaultOverflowMenu";
@@ -32,11 +32,8 @@ type BaseOverflowListProps<T> = BaseComponentProps & {
3232
// if false, using requestAnimationFrame to update the state - this avoid forced reflow and improve performance
3333
flushImmediately?: boolean;
3434

35-
// use this if you want to override how hidden items are kept in the DOM while not affecting layout
36-
// this function is called for item item in the list(even visible ones), you can control the visibility of the item by returning a different node or null
37-
// default: about react 19.2 new Activity component to control the visibility of the item while don't forcing mount/unmount of the item
38-
// below react 19.2 is simply null (causing rapid re-mount/unmount of the item)
39-
renderHiddenItem?: (node: React.ReactNode, meta: RenderItemMeta) => React.ReactNode;
35+
// customize how each item is shown/hidden during measurement so you can keep custom elements mounted
36+
renderItemVisibility?: (node: React.ReactNode, meta: RenderItemMeta) => React.ReactNode;
4037
};
4138

4239
type OverflowListWithItems<T> = BaseOverflowListProps<T> & {
@@ -86,7 +83,7 @@ const OverflowListComponent = React.memo(
8683
renderItem = (item) => item as React.ReactNode,
8784
renderOverflowItem,
8885
renderOverflowProps,
89-
renderHiddenItem,
86+
renderItemVisibility,
9087
maxRows = 1,
9188
maxVisibleItems = 100,
9289
flushImmediately = true,
@@ -224,8 +221,8 @@ const OverflowListComponent = React.memo(
224221
...containerProps.style,
225222
};
226223

227-
const finalRenderHiddenItem =
228-
renderHiddenItem ??
224+
const finalRenderItemVisibility =
225+
renderItemVisibility ??
229226
((node, meta) => {
230227
// prefer react 19.2 new activity component to control the visibility of the item while don't forcing mount/unmount of the item
231228
const Activity = React?.Activity;
@@ -254,7 +251,7 @@ const OverflowListComponent = React.memo(
254251

255252
const itemComponent = renderItem(item as T, { index, visible: isVisible });
256253

257-
return finalRenderHiddenItem(itemComponent, { index, visible: isVisible });
254+
return finalRenderItemVisibility(itemComponent, { index, visible: isVisible });
258255
})}
259256

260257
{clonedOverflowElement}

0 commit comments

Comments
 (0)