fix: combobox performance issue

HichamELBSI · HichamELBSI · commit 8228a8e5db72 · 2025-10-13T09:28:11.000+02:00
diff --git a/.changeset/famous-trees-jog.md b/.changeset/famous-trees-jog.md
@@ -0,0 +1,6 @@
+---
+'@strapi/design-system': major
+'@strapi/ui-primitives': major
+---
+
+Add virtualization as an option to combobox list
diff --git a/packages/design-system/src/components/Combobox/Combobox.tsx b/packages/design-system/src/components/Combobox/Combobox.tsx
@@ -19,6 +19,8 @@ import { Field, useField } from '../Field';
 import { IconButton } from '../IconButton';
 import { Loader } from '../Loader';
 
+import { VirtualizedList } from './VirtualizedList';
+
 /* -------------------------------------------------------------------------------------------------
  * ComboboxInput
  * -----------------------------------------------------------------------------------------------*/
@@ -64,6 +66,29 @@ interface ComboboxProps
    */
   size?: 'S' | 'M';
   startIcon?: React.ReactNode;
+  /**
+   * Enable virtualization for large lists
+   * @default false
+   */
+  virtualized?: boolean;
+  /**
+   * Estimated size of each item for virtualization
+   * @default 40
+   */
+  estimatedItemSize?: number;
+  /**
+   * Number of items to render outside visible area
+   * @default 5
+   */
+  overscan?: number;
+  /**
+   * For lazy virtualization: total item count
+   */
+  virtualItemCount?: number;
+  /**
+   * For lazy virtualization: function to render item by index
+   */
+  renderVirtualItem?: (index: number) => React.ReactNode;
 }
 
 type ComboboxInputElement = HTMLInputElement;
@@ -98,6 +123,11 @@ const Combobox = React.forwardRef<ComboboxInputElement, ComboboxProps>(
       onChange,
       onClear,
       onCreateOption,
+      virtualized = false,
+      estimatedItemSize = 40,
+      overscan = 5,
+      virtualItemCount,
+      renderVirtualItem,
       onFilterValueChange,
       onInputChange,
       onTextValueChange,
@@ -271,7 +301,18 @@ const Combobox = React.forwardRef<ComboboxInputElement, ComboboxProps>(
           <Content sideOffset={4}>
             <ComboboxPrimitive.Viewport ref={viewportRef}>
               <ScrollAreaCombobox>
-                {children}
+                {virtualized ? (
+                  <VirtualizedList
+                    estimatedItemSize={estimatedItemSize}
+                    overscan={overscan}
+                    itemCount={virtualItemCount}
+                    renderItem={renderVirtualItem}
+                  >
+                    {children}
+                  </VirtualizedList>
+                ) : (
+                  children
+                )}
                 {creatable !== true && !loading ? (
                   <ComboboxPrimitive.NoValueFound asChild>
                     <OptionBox $hasHover={false}>
diff --git a/packages/design-system/src/components/Combobox/VirtualizedList.tsx b/packages/design-system/src/components/Combobox/VirtualizedList.tsx
@@ -0,0 +1,115 @@
+import { ReactNode, FC, useRef, useState, useEffect, startTransition, useMemo, Children, useCallback } from 'react';
+
+import { useVirtualizer } from '@tanstack/react-virtual';
+
+import { Box } from '../../primitives';
+
+interface VirtualizedListProps {
+  children?: ReactNode;
+  estimatedItemSize?: number;
+  overscan?: number;
+  // Optional: lazy rendering support
+  itemCount?: number;
+  renderItem?: (index: number) => ReactNode;
+}
+
+/**
+ * VirtualizedList - Wraps Combobox children in a virtualizer for performance
+ * This component should be used inside ScrollArea to virtualize the list
+ *
+ * Two modes:
+ * 1. Children mode (default): Pass children directly
+ * 2. Lazy mode: Pass itemCount + renderItem for maximum performance
+ */
+export const VirtualizedList: FC<VirtualizedListProps> = ({
+  children,
+  estimatedItemSize = 40,
+  overscan = 10,
+  itemCount,
+  renderItem,
+}) => {
+  const parentRef = useRef<HTMLDivElement>(null);
+  const [isReady, setIsReady] = useState(false);
+  const isMountedRef = useRef(true);
+
+  useEffect(() => {
+    isMountedRef.current = true;
+
+    if (typeof startTransition === 'function') {
+      startTransition(() => {
+        if (isMountedRef.current) {
+          setIsReady(true);
+        }
+      });
+    }
+
+    return () => {
+      isMountedRef.current = false;
+    };
+  }, []);
+
+  // Convert children to array only once and cache it (for children mode)
+  const childArray = useMemo(() => {
+    if (renderItem && itemCount !== undefined) {
+      // Lazy mode: no children array needed
+      return [];
+    }
+    return Children.toArray(children);
+  }, [children, renderItem, itemCount]);
+
+  const count = itemCount ?? childArray.length;
+
+  const virtualizer = useVirtualizer({
+    count,
+    getScrollElement: () => parentRef.current?.parentElement ?? null,
+    estimateSize: useCallback(() => estimatedItemSize, [estimatedItemSize]),
+    overscan,
+    // Optimize scroll performance
+    scrollMargin: 0,
+    // Don't measure elements dynamically - use fixed size
+    measureElement: undefined,
+    // Use lanes for better performance with large lists
+    lanes: 1,
+  });
+
+  // Get virtual items - this updates as you scroll
+  const virtualItems = isReady && isMountedRef.current ? virtualizer.getVirtualItems() : [];
+
+  // Show minimal content until ready to prevent blocking
+  if (!isReady) {
+    return <Box ref={parentRef} height="200px" width="100%" position="relative" />;
+  }
+
+  return (
+    <Box
+      ref={parentRef}
+      height={`${virtualizer.getTotalSize()}px`}
+      width="100%"
+      position="relative"
+      style={{
+        willChange: 'transform',
+      }}
+    >
+      {virtualItems.map((virtualItem) => {
+        // Lazy mode: render on-demand
+        const child = renderItem ? renderItem(virtualItem.index) : childArray[virtualItem.index];
+
+        return (
+          <Box
+            key={virtualItem.key}
+            data-index={virtualItem.index}
+            style={{
+              position: 'absolute',
+              top: 0,
+              left: 0,
+              width: '100%',
+              transform: `translate3d(0, ${virtualItem.start}px, 0)`,
+            }}
+          >
+            {child}
+          </Box>
+        );
+      })}
+    </Box>
+  );
+};
diff --git a/packages/design-system/src/components/TimePicker/TimePicker.tsx b/packages/design-system/src/components/TimePicker/TimePicker.tsx
@@ -1,7 +1,7 @@
 import * as React from 'react';
 
 import { Clock } from '@strapi/icons';
-import styled from 'styled-components';
+import { styled } from 'styled-components';
 
 import { useControllableState } from '../../hooks/useControllableState';
 import { useDateFormatter } from '../../hooks/useDateFormatter';
@@ -74,13 +74,43 @@ export const TimePicker = React.forwardRef<ComboboxInputElement, TimePickerProps
       return separator;
     }, [formatter]);
 
+    // Enable virtualization for small steps that generate many options
+    // step=1 -> 1440 options, step=5 -> 288 options
+    const shouldVirtualize = step <= 5;
+
+    // Increase overscan for smoother scrolling with many items
+    const overscanCount = step === 1 ? 15 : 10;
+
+    // For virtualized lists, generate options lazily to avoid creating 1440 React elements upfront
+    // For non-virtualized lists, generate all options as before
     const timeOptions = React.useMemo(() => {
-      const stepCount = 60 / step;
+      if (!shouldVirtualize) {
+        // Non-virtualized: generate all options as before
+        const stepCount = 60 / step;
+        return [...Array(24).keys()].flatMap((hour) =>
+          [...Array(stepCount).keys()].map((minuteStep) =>
+            formatter.format(new Date(0, 0, 0, hour, minuteStep * step)),
+          ),
+        );
+      }
 
-      return [...Array(24).keys()].flatMap((hour) =>
-        [...Array(stepCount).keys()].map((minuteStep) => formatter.format(new Date(0, 0, 0, hour, minuteStep * step))),
-      );
-    }, [step, formatter]);
+      // Virtualized: return empty array and generate on-demand
+      return [];
+    }, [step, formatter, shouldVirtualize]);
+
+    // Generate time option on demand for virtualized lists
+    const getTimeOption = React.useCallback(
+      (index: number) => {
+        const stepCount = 60 / step;
+        const hour = Math.floor(index / stepCount);
+        const minuteStep = index % stepCount;
+        return formatter.format(new Date(0, 0, 0, hour, minuteStep * step));
+      },
+      [step, formatter],
+    );
+
+    // Calculate total count for virtualized lists
+    const totalTimeCount = (60 / step) * 24;
 
     const handleTextValueChange = (string?: string) => {
       if (!string || isNotAlphabeticalCharacter(string)) {
@@ -137,6 +167,19 @@ export const TimePicker = React.forwardRef<ComboboxInputElement, TimePickerProps
     const escapedSeparator = escapeForRegex(separator);
     const pattern = `\\d{2}${escapedSeparator}\\d{2}`;
 
+    // Render function for lazy virtualization
+    const renderTimeOption = React.useCallback(
+      (index: number) => {
+        const time = getTimeOption(index);
+        return (
+          <ComboboxOption key={time} value={time}>
+            {time}
+          </ComboboxOption>
+        );
+      },
+      [getTimeOption],
+    );
+
     return (
       <TimePickerCombobox
         {...restProps}
@@ -153,12 +196,17 @@ export const TimePicker = React.forwardRef<ComboboxInputElement, TimePickerProps
         textValue={textValue}
         onTextValueChange={handleTextValueChange}
         onBlur={handleBlur}
+        virtualized={shouldVirtualize}
+        overscan={overscanCount}
+        virtualItemCount={shouldVirtualize ? totalTimeCount : undefined}
+        renderVirtualItem={shouldVirtualize ? renderTimeOption : undefined}
       >
-        {timeOptions.map((time) => (
-          <ComboboxOption key={time} value={time}>
-            {time}
-          </ComboboxOption>
-        ))}
+        {!shouldVirtualize &&
+          timeOptions.map((time) => (
+            <ComboboxOption key={time} value={time}>
+              {time}
+            </ComboboxOption>
+          ))}
       </TimePickerCombobox>
     );
   },
diff --git a/packages/primitives/package.json b/packages/primitives/package.json
@@ -38,6 +38,7 @@
     "@radix-ui/react-use-layout-effect": "1.0.1",
     "@radix-ui/react-use-previous": "1.0.1",
     "@radix-ui/react-visually-hidden": "1.0.3",
+    "@tanstack/react-virtual": "^3.10.8",
     "aria-hidden": "1.2.4",
     "react-remove-scroll": "2.5.10"
   },
diff --git a/packages/primitives/src/components/Combobox/Combobox.tsx b/packages/primitives/src/components/Combobox/Combobox.tsx
@@ -20,6 +20,8 @@ import { useFilter } from '../../hooks/useFilter';
 import { usePrev } from '../../hooks/usePrev';
 import { createCollection } from '../Collection';
 
+import { VirtualizedViewport } from './VirtualizedViewport';
+
 import type { ComponentPropsWithoutRef } from '@radix-ui/react-primitive';
 
 const OPEN_KEYS = [' ', 'Enter', 'ArrowUp', 'ArrowDown'];
@@ -88,6 +90,9 @@ type ComboboxContextValue = {
   onVisuallyFocussedItemChange: (item: HTMLDivElement | null) => void;
   isPrintableCharacter: (str: string) => boolean;
   visible?: boolean;
+  virtualized?: boolean | 'auto';
+  estimatedItemSize?: number;
+  overscan?: number;
 };
 
 const [ComboboxProvider, useComboboxContext] = createContext<ComboboxContextValue>(COMBOBOX_NAME);
@@ -113,6 +118,24 @@ interface RootProps {
   onFilterValueChange?(value: string): void;
   isPrintableCharacter?: (str: string) => boolean;
   visible?: boolean;
+  /**
+   * Enable virtualization for large lists
+   * - true: always virtualize
+   * - false: never virtualize
+   * - 'auto': virtualize when item count > 100 (default)
+   * @default 'auto'
+   */
+  virtualized?: boolean | 'auto';
+  /**
+   * Estimated size of each virtualized item in pixels
+   * @default 40
+   */
+  estimatedItemSize?: number;
+  /**
+   * Number of items to render outside visible area for smooth scrolling
+   * @default 5
+   */
+  overscan?: number;
 }
 
 /**
@@ -162,6 +185,9 @@ const Combobox = (props: RootProps) => {
     onFilterValueChange,
     isPrintableCharacter = defaultIsPrintableCharacter,
     visible = false,
+    virtualized = 'auto',
+    estimatedItemSize = 40,
+    overscan = 5,
   } = props;
 
   const [trigger, setTrigger] = React.useState<ComboboxInputElement | null>(null);
@@ -269,6 +295,9 @@ const Combobox = (props: RootProps) => {
         onVisuallyFocussedItemChange={setVisuallyFocussedItem}
         isPrintableCharacter={isPrintableCharacter}
         visible={visible}
+        virtualized={virtualized}
+        estimatedItemSize={estimatedItemSize}
+        overscan={overscan}
       >
         {children}
       </ComboboxProvider>
@@ -921,6 +950,31 @@ const ComboboxViewport = React.forwardRef<ComboboxViewportElement, ViewportProps
   const comboboxContext = useComboboxContext(VIEWPORT_NAME);
   const composedRefs = useComposedRefs(forwardedRef, comboboxContext.onViewportChange);
 
+  // Count children to determine if virtualization should be enabled
+  // Use React.Children.count to avoid calling getItems() which causes infinite loops
+  const childArray = React.useMemo(() => React.Children.toArray(props.children), [props.children]);
+  const itemCount = childArray.length;
+
+  const shouldVirtualize =
+    comboboxContext.virtualized === true || (comboboxContext.virtualized === 'auto' && itemCount > 100);
+
+  // If virtualization is enabled, use VirtualizedViewport
+  if (shouldVirtualize) {
+    return (
+      <Collection.Slot scope={undefined}>
+        <VirtualizedViewport
+          {...props}
+          ref={composedRefs}
+          getItemCount={() => itemCount}
+          estimatedItemSize={comboboxContext.estimatedItemSize}
+          overscan={comboboxContext.overscan}
+          onViewportChange={comboboxContext.onViewportChange}
+        />
+      </Collection.Slot>
+    );
+  }
+
+  // Standard non-virtualized viewport
   return (
     <>
       {/* Hide scrollbars cross-browser and enable momentum scroll for touch devices */}
diff --git a/packages/primitives/src/components/Combobox/VirtualizedViewport.tsx b/packages/primitives/src/components/Combobox/VirtualizedViewport.tsx
diff --git a/yarn.lock b/yarn.lock
