SCC-5375: Multiselect lazy loading

CHANGELOG.md

@@ -8,6 +8,10 @@ Currently, this repo is in Prerelease. When it is released, this project will ad
 
 ## Prerelease
 
+### Adds
+
+- Adds the `lazy-load` option to the `listOverflow` prop of the `MultiSelect` component.
+
 ## 4.4.0 (July 8, 2026)
 
 ### Adds

src/components/MultiSelect/MultiSelect.mdx

@@ -39,6 +39,7 @@ import { changelogData } from "./multiSelectChangelogData";
 - [Width](#width)
 - [Default Open State](#default-open-state)
 - [Close on Blur State](#close-on-blur-state)
+- [Lazy Loading Items](#lazy-loading-items)
 - [MultiSelect in a Group](#multiselect-in-a-group)
 - [Controlling state using selectedItems and onChange props](#controlling-state-using-selecteditems-and-onchange-props)
 - [MultiSelect NextJS routing implementation](#multiselect-nextjs-routing-implementation)
@@ -211,7 +212,8 @@ counting the items to display.
   content={
     <>
       <strong>IMPORTANT:</strong> This prop can only be used with{" "}
-      <code>listOverflow="expand"</code>.
+      <code>listOverflow</code> is set to <code>"expand"</code> or{" "}
+      <code>"lazy-load"</code>.
     </>
   }
   variant="informative"
@@ -751,6 +753,15 @@ focus leaves the component (the user clicks outside or uses the keyboard to tab
   language="tsx"
 />
 
+## Lazy loading items
+
+If a large number of items is hindering performance, `listOverflow` can be set
+to `lazy-load`. The component renders the first `defaultItemsVisible` items on load.
+Scrolling down in the panel triggers more items to be rendered. The number of
+items loaded scales with how far has been already scrolled.
+
+<Canvas of={MultiSelectStories.lazyLoadingItems} />
+
 ## MultiSelect in a Group
 
 When using the `MultiSelect` component in a group, it is recommended to use the

src/components/MultiSelect/MultiSelect.stories.tsx

@@ -13,6 +13,7 @@ import MultiSelect, {
 import Text from "../Text/Text";
 import useMultiSelect from "../../hooks/useMultiSelect";
 import Button from "../Button/Button";
+import { withLazyLoadItems } from "./MultiSelectStoriesData";
 
 const withItems = [
   {
@@ -617,6 +618,20 @@ export const closeOnBlurState: Story = {
   ),
 };
 
+export const lazyLoadingItems: Story = {
+  render: () => (
+    <MultiSelectStory
+      id="multi-select-id-18"
+      isBlockElement
+      isDefaultOpen={false}
+      isSearchable={true}
+      items={withLazyLoadItems}
+      listOverflow="lazy-load"
+      defaultItemsVisible={5}
+    />
+  ),
+};
+
 export const InAGroup: Story = {
   render: () => <MultiSelectGroupStory items={withItems} />,
 };

src/components/MultiSelect/MultiSelect.test.tsx

@@ -1,5 +1,5 @@
 import { axe } from "jest-axe";
-import { render, screen, waitFor } from "@testing-library/react";
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
 import renderer from "react-test-renderer";
 import userEvent from "@testing-library/user-event";
 import { useEffect } from "react";
@@ -11,6 +11,14 @@ jest.mock("../../hooks/useSafeId", () => ({
   useSafeId: jest.fn((id) => id || "test-id"),
 }));
 
+const intersectionObserverMock = () => ({
+  observe: () => null,
+  disconnect: () => null,
+});
+window.IntersectionObserver = jest
+  .fn()
+  .mockImplementation(intersectionObserverMock);
+
 const items = [
   { id: "dogs", name: "Dogs", isDisabled: false },
   { id: "cats", name: "Cats", isDisabled: false },
@@ -65,6 +73,22 @@ const itemsWithCount = [
 
 const defaultItemsVisible = 5;
 
+const lazyLoadItems = [
+  { id: "item-1", name: "Item 1" },
+  { id: "item-2", name: "Item 2" },
+  { id: "item-3", name: "Item 3" },
+  { id: "item-4", name: "Item 4" },
+  { id: "item-5", name: "Item 5" },
+  { id: "item-6", name: "Item 6" },
+  { id: "item-7", name: "Item 7" },
+  { id: "item-8", name: "Item 8" },
+  { id: "item-9", name: "Item 9" },
+  { id: "item-10", name: "Item 10" },
+  { id: "item-11", name: "Item 11" },
+  { id: "item-12", name: "Item 12" },
+  { id: "item-13", name: "Item 13" },
+];
+
 const MultiSelectTestComponent = ({
   multiSelectId,
   initialSelectedItems = {},
@@ -470,6 +494,58 @@ describe("MultiSelect", () => {
     );
   });
 
+  it("should lazily load more list items while scrolling in lazy load mode", async () => {
+    render(
+      <MultiSelect
+        id="multiselect-lazy-load-id"
+        buttonText="Multiselect button text"
+        defaultItemsVisible={3}
+        items={lazyLoadItems}
+        isDefaultOpen={true}
+        isSearchable={false}
+        isBlockElement={false}
+        listOverflow="lazy-load"
+        selectedItems={selectedTestItems}
+        onChange={() => null}
+        onClear={() => null}
+      />
+    );
+
+    expect(screen.queryAllByRole("checkbox")).toHaveLength(3);
+
+    const listContainer = screen.getByTestId(
+      "multiselect-lazy-load-id-items-list"
+    );
+    Object.defineProperty(listContainer, "clientHeight", {
+      configurable: true,
+      value: 500,
+    });
+    Object.defineProperty(listContainer, "scrollHeight", {
+      configurable: true,
+      value: 1000,
+    });
+    Object.defineProperty(listContainer, "scrollTop", {
+      configurable: true,
+      value: 500,
+      writable: true,
+    });
+
+    fireEvent.scroll(listContainer);
+    await waitFor(() =>
+      expect(screen.queryAllByRole("checkbox")).toHaveLength(7)
+    );
+
+    fireEvent.scroll(listContainer);
+    await waitFor(() =>
+      expect(screen.queryAllByRole("checkbox")).toHaveLength(12)
+    );
+
+    fireEvent.scroll(listContainer);
+    await waitFor(() =>
+      expect(screen.queryAllByRole("checkbox")).toHaveLength(13)
+    );
+  });
+
   it("should call onChange when an item without child items or a child item is selected/unselected", () => {
     const onChangeMock = jest.fn();
     const onMixedStateChangeMock = jest.fn();

src/components/MultiSelect/MultiSelect.tsx

@@ -5,7 +5,13 @@ import {
   ChakraComponent,
   useMultiStyleConfig,
 } from "@chakra-ui/react";
-import React, { forwardRef, useEffect, useRef, useState } from "react";
+import React, {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+} from "react";
 
 import Accordion from "./../Accordion/Accordion";
 import Button from "./../Button/Button";
@@ -24,7 +30,11 @@ export interface MultiSelectItem {
 }
 export const multiSelectWidthsArray = ["fitContent", "full"] as const;
 export type MultiSelectWidths = typeof multiSelectWidthsArray[number];
-export const multiSelectListOverflowArray = ["scroll", "expand"] as const;
+export const multiSelectListOverflowArray = [
+  "scroll",
+  "expand",
+  "lazy-load",
+] as const;
 export type MultiSelectListOverflowTypes =
   typeof multiSelectListOverflowArray[number];
 export interface SelectedItems {
@@ -51,7 +61,7 @@ export interface MultiSelectProps extends BoxProps {
   /** The items to be rendered in the Multiselect as checkbox options. */
   items: MultiSelectItem[];
   /** listOverflow is a property indicating how the list should handle overflow,
-   * with options limited to either "scroll" or "expand." */
+   * with options limited to "scroll", "expand", or "lazy-load". */
   listOverflow?: MultiSelectListOverflowTypes;
   /** The action to perform for the clear/reset button of individual MultiSelects. */
   onClear?: () => void;
@@ -111,6 +121,13 @@ export const MultiSelect: ChakraComponent<
       const expandToggleButtonRef: React.RefObject<HTMLButtonElement> =
         useRef<HTMLButtonElement>();
 
+      // Used for Intersection Observer for lazy loading
+      const itemsListRef: React.RefObject<HTMLDivElement> =
+        useRef<HTMLDivElement>();
+      // Observation target for Intersection Observer
+      const lazyLoadTargetRef: React.RefObject<HTMLDivElement> =
+        useRef<HTMLDivElement>();
+
       // Tells `Accordion` to close if open when user clicks outside of the container
       const handleClickOutside = (e) => {
         if (e.type === "mousedown") {
@@ -153,21 +170,31 @@ export const MultiSelect: ChakraComponent<
 
       const MINIMUM_ITEMS_LIST_HEIGHT = "215px";
       const MAXIMUM_ITEMS_LIST_HEIGHT = "270px";
-      const listHeight =
-        listOverflow === "expand"
-          ? "unset"
-          : isSearchable
-          ? MAXIMUM_ITEMS_LIST_HEIGHT
-          : MINIMUM_ITEMS_LIST_HEIGHT;
-
       const isOverflowExpand =
         items.length > defaultItemsVisible && listOverflow === "expand";
+      const isOverflowLazy =
+        items.length > defaultItemsVisible && listOverflow === "lazy-load";
       const defaultItemsList = React.useMemo(
         () => (isOverflowExpand ? items.slice(0, defaultItemsVisible) : items),
         [isOverflowExpand, items, defaultItemsVisible]
       );
       const [itemsList, setItemsList] = useState(defaultItemsList);
       const [isExpandable, setIsExpandable] = useState(true);
+      const [lazyItemsVisible, setLazyItemsVisible] =
+        useState(defaultItemsVisible);
+
+      const hasScrollablePanel = listOverflow === "scroll" || isOverflowLazy;
+
+      const listHeight =
+        listOverflow === "expand"
+          ? "unset"
+          : isSearchable
+          ? MAXIMUM_ITEMS_LIST_HEIGHT
+          : MINIMUM_ITEMS_LIST_HEIGHT;
+
+      const visibleItemsList = isOverflowLazy
+        ? itemsList.slice(0, lazyItemsVisible)
+        : itemsList;
 
       const selectedItemsCount: number =
         selectedItems[mainId]?.items.length || 0;
@@ -245,6 +272,21 @@ export const MultiSelect: ChakraComponent<
         return <Box>No options found</Box>;
       };
 
+      const loadMoreLazyItems = useCallback(() => {
+        if (!isOverflowLazy) {
+          return;
+        }
+
+        setLazyItemsVisible((previousVisibleItems) =>
+          Math.min(
+            previousVisibleItems +
+              defaultItemsVisible +
+              previousVisibleItems / defaultItemsVisible, // Scales with further scrolling
+            itemsList.length
+          )
+        );
+      }, [defaultItemsVisible, isOverflowLazy, itemsList]);
+
       const onChangeSearch = (event) => {
         const value = event.target.value.trim().toLowerCase();
         if (!value) {
@@ -287,10 +329,53 @@ export const MultiSelect: ChakraComponent<
         }, 1); // Ensure focus logic runs after state update
       };
 
+      const onItemsListScroll = () => {
+        if (!isOverflowLazy || !itemsListRef.current) {
+          return;
+        }
+
+        const { scrollTop, clientHeight, scrollHeight } = itemsListRef.current;
+        const scrollThreshold = scrollHeight / 2; // Scales with further scrolling
+        const isAtBottom =
+          scrollTop + clientHeight >= scrollHeight - scrollThreshold;
+
+        if (!isAtBottom) {
+          return;
+        }
+
+        loadMoreLazyItems();
+      };
+
       React.useEffect(() => {
         setItemsList(isExpandable ? defaultItemsList : items);
       }, [isExpandable, defaultItemsList, items]);
 
+      React.useEffect(() => {
+        if (
+          !isOverflowLazy ||
+          !itemsListRef.current ||
+          !lazyLoadTargetRef.current
+        ) {
+          return;
+        }
+
+        const observer = new IntersectionObserver(
+          (entries) => {
+            if (entries.some((entry) => entry.isIntersecting)) {
+              loadMoreLazyItems();
+            }
+          },
+          {
+            root: itemsListRef.current,
+            threshold: 0,
+          }
+        );
+
+        observer.observe(lazyLoadTargetRef.current);
+
+        return () => observer.disconnect();
+      }, [isOverflowLazy, loadMoreLazyItems]);
+
       const ExpandToggleButton = (): JSX.Element => {
         return (
           <Button
@@ -402,22 +487,25 @@ export const MultiSelect: ChakraComponent<
 
       const accordionPanel = (
         <Box position="relative">
-          {isSearchable && !isOverflowExpand ? (
+          {isSearchable && hasScrollablePanel ? (
             <Box position="sticky" top="0" marginBottom="12px" zIndex="1">
               {searchInput}
             </Box>
-          ) : isSearchable && isOverflowExpand ? (
+          ) : isSearchable && (isOverflowExpand || isOverflowLazy) ? (
             searchInput
           ) : null}
 
           <Box
+            data-testid={isOverflowLazy ? `${mainId}-items-list` : undefined}
+            ref={itemsListRef}
+            onScroll={isOverflowLazy ? onItemsListScroll : undefined}
             maxHeight={listHeight}
             overflowY="auto"
             paddingTop="xxs"
             paddingLeft="xs"
             paddingBottom="xxs"
           >
-            {itemsList.length === 0 ? (
+            {visibleItemsList.length === 0 ? (
               <NoSearchResults />
             ) : (
               <>
@@ -430,13 +518,17 @@ export const MultiSelect: ChakraComponent<
                   showLabel={false}
                   name="multi-select-checkbox-group"
                 >
-                  {itemsList.map((item: MultiSelectItem) => (
+                  {visibleItemsList.map((item: MultiSelectItem) => (
                     <React.Fragment key={item.id}>
                       {getMultiSelectCheckboxItem(item)}
                     </React.Fragment>
                   ))}
                 </CheckboxGroup>
                 {isOverflowExpand && <ExpandToggleButton />}
+                {isOverflowLazy &&
+                  visibleItemsList.length < itemsList.length && (
+                    <Box ref={lazyLoadTargetRef} height="1px" />
+                  )}
               </>
             )}
           </Box>