Add customContent prop to ComboboxOption to render a custom react component (#3505)

Author: gargantia-prime

.changeset/dark-boxes-behave.md

@@ -0,0 +1,5 @@
+---
+'@leafygreen-ui/combobox': minor
+---
+
+Added a customContent prop to render a custom component in combobox option

packages/combobox/README.md

@@ -87,14 +87,15 @@ import { Combobox, ComboboxOption } from '@leafygreen-ui/combobox';
 
 ## Props
 
-| Prop          | Type                                                                         | Description                                                                                                                                                                   | Default |
-| ------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
-| `value`       | `string`                                                                     | The internal value of the option. Used as the identifier in Combobox `initialValue`, `value` and `filteredOptions`. When undefined, this is set to `_.kebabCase(displayName)` |         |
-| `displayName` | `string`                                                                     | The display value of the option. Used as the rendered string within the menu and chips. When undefined, this is set to `value`                                                |         |
-| `glyph`       | `<Icon/>`                                                                    | The icon to display to the left of the option in the menu.                                                                                                                    |         |
-| `className`   | `string`                                                                     | The className passed to the root element of the component.                                                                                                                    |         |
-| `description` | `string`                                                                     | Optional descriptive text under the displayName.                                                                                                                              |         |
-| `onClick`     | `(event: React.SyntheticEvent<HTMLLIElement, Event>, value: string) => void` | Callback fired when an option is clicked. Returns the event and the option value.                                                                                             |         |
+| Prop            | Type                                                                         | Description                                                                                                                                                                   | Default |
+| --------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
+| `value`         | `string`                                                                     | The internal value of the option. Used as the identifier in Combobox `initialValue`, `value` and `filteredOptions`. When undefined, this is set to `_.kebabCase(displayName)` |         |
+| `displayName`   | `string`                                                                     | The display value of the option. Used as the rendered string within the menu and chips. When undefined, this is set to `value`                                                |         |
+| `customContent` | `ReactNode`                                                                  | Optional custom content to render for the option. When provided, this ReactNode will be rendered in the option menu                                                           |         |
+| `glyph`         | `<Icon/>`                                                                    | The icon to display to the left of the option in the menu.                                                                                                                    |         |
+| `className`     | `string`                                                                     | The className passed to the root element of the component.                                                                                                                    |         |
+| `description`   | `string`                                                                     | Optional descriptive text under the displayName.                                                                                                                              |         |
+| `onClick`       | `(event: React.SyntheticEvent<HTMLLIElement, Event>, value: string) => void` | Callback fired when an option is clicked. Returns the event and the option value.                                                                                             |         |
 
 # ComboboxGroup
 

packages/combobox/src/Combobox.stories.tsx

@@ -8,6 +8,7 @@ import {
 import { StoryContext, StoryFn } from '@storybook/react';
 import { userEvent, within } from '@storybook/test';
 
+import { Badge } from '@leafygreen-ui/badge';
 import { Button } from '@leafygreen-ui/button';
 import { css } from '@leafygreen-ui/emotion';
 
@@ -237,6 +238,57 @@ ExternalFilter.parameters = {
   chromatic: { disableSnapshot: true },
 };
 
+/**
+ * Example showing the `customContent` prop for rendering custom components in dropdown options.
+ * The `customContent` prop accepts any ReactNode, allowing you to add badges, icons, or other
+ * custom components to your options. The `displayName` is still used for filtering and chips.
+ */
+export const WithCustomContent = () => {
+  return (
+    <Combobox
+      label="Choose a feature"
+      description="Some features are new!"
+      placeholder="Select a feature"
+      multiselect={false}
+    >
+      <ComboboxOption
+        value="feature-a"
+        displayName="Feature A"
+        customContent={
+          <>
+            <span>Feature A</span>
+            <Badge variant="blue">New</Badge>
+          </>
+        }
+      />
+      <ComboboxOption
+        value="feature-b"
+        displayName="Feature B"
+        customContent={
+          <>
+            <span>Feature B</span>
+            <Badge variant="green">Beta</Badge>
+          </>
+        }
+      />
+      <ComboboxOption value="feature-c" displayName="Feature C" />
+      <ComboboxOption
+        value="feature-d"
+        displayName="Feature D"
+        customContent={
+          <>
+            <span>Feature D</span>
+            <Badge variant="red">Deprecated</Badge>
+          </>
+        }
+      />
+    </Combobox>
+  );
+};
+WithCustomContent.parameters = {
+  chromatic: { disableSnapshot: true },
+};
+
 export const SingleSelect: StoryType<typeof Combobox> = () => <></>;
 SingleSelect.args = {
   multiselect: false,

packages/combobox/src/Combobox/Combobox.spec.tsx

@@ -13,6 +13,7 @@ import { axe } from 'jest-axe';
 import flatten from 'lodash/flatten';
 import isUndefined from 'lodash/isUndefined';
 
+import { Badge } from '@leafygreen-ui/badge';
 import { RenderMode } from '@leafygreen-ui/popover';
 import { eventContainingTargetValue } from '@leafygreen-ui/testing-lib';
 
@@ -279,15 +280,11 @@ describe('packages/combobox', () => {
         expect(optionEl).toHaveTextContent('abc-def');
       });
 
-      test('Option aria-label falls back to displayName text content', () => {
+      test('Option aria-label falls back to displayName', () => {
         const options: Array<OptionObject> = [
           {
             value: 'react-node-option',
-            displayName: (
-              <span>
-                <strong>Bold</strong> and <em>italic</em> text
-              </span>
-            ),
+            displayName: 'Bold and italic text',
             isDisabled: false,
           },
         ];
@@ -297,6 +294,100 @@ describe('packages/combobox', () => {
         expect(optionEl).toHaveAttribute('aria-label', 'Bold and italic text');
       });
 
+      test('displayName renders correctly', () => {
+        const options: Array<OptionObject> = [
+          {
+            value: 'legacy-option',
+            displayName: 'Legacy String Display Name',
+            isDisabled: false,
+          },
+        ];
+        const { openMenu } = renderCombobox(select, { options });
+        const { optionElements } = openMenu();
+        const [optionEl] = Array.from(optionElements!);
+
+        // Should render the string displayName
+        expect(optionEl).toHaveTextContent('Legacy String Display Name');
+        expect(optionEl).toHaveAttribute(
+          'aria-label',
+          'Legacy String Display Name',
+        );
+      });
+
+      test('customContent with Badge component renders correctly', () => {
+        const { openMenu } = renderCombobox(select, {
+          children: (
+            <ComboboxOption
+              value="new-feature"
+              displayName="New Feature"
+              customContent={
+                <>
+                  Custom Content Component
+                  <Badge variant="blue" data-testid="custom-badge">
+                    New
+                  </Badge>
+                </>
+              }
+            />
+          ),
+        });
+        const { optionElements } = openMenu();
+        const [optionEl] = Array.from(optionElements!) as Array<Element>;
+
+        // Should render the custom content with Badge (not the displayName)
+        expect(optionEl).toHaveTextContent('Custom Content Component');
+        expect(optionEl).not.toHaveTextContent('New Feature');
+
+        // Should render the Badge component
+        const badgeEl = optionEl.querySelector('[data-testid="custom-badge"]');
+        expect(badgeEl).toBeInTheDocument();
+
+        // aria-label should still use the string displayName
+        expect(optionEl).toHaveAttribute('aria-label', 'New Feature');
+      });
+
+      test('option with customContent can be selected', async () => {
+        const onChange = jest.fn();
+        const { openMenu, inputEl, queryByTestId } = renderCombobox(select, {
+          onChange,
+          children: (
+            <ComboboxOption
+              value="new-feature"
+              displayName="New Feature"
+              customContent={
+                <>
+                  Custom Content
+                  <Badge variant="blue">New</Badge>
+                </>
+              }
+            />
+          ),
+        });
+        const { optionElements } = openMenu();
+        const [optionEl] = Array.from(optionElements!) as Array<Element>;
+
+        userEvent.click(optionEl as Element);
+
+        if (select === 'single') {
+          expect(onChange).toHaveBeenCalledWith('new-feature');
+          // Only displayName should be rendered in the input, not customContent
+          expect(inputEl).toHaveValue('New Feature');
+          expect(inputEl).not.toHaveValue('Custom Content');
+        } else {
+          expect(onChange).toHaveBeenCalledWith(
+            ['new-feature'],
+            expect.anything(),
+          );
+          // Only displayName should be rendered in the chip, not customContent
+          await waitFor(() => {
+            const chip = queryByTestId('lg-combobox-chip');
+            expect(chip).toBeInTheDocument();
+            expect(chip).toHaveTextContent('New Feature');
+            expect(chip).not.toHaveTextContent('Custom Content');
+          });
+        }
+      });
+
       test('Option aria-label falls back to value when displayName is not provided', () => {
         const options = [{ value: 'fallback-value' }];
         /// @ts-expect-error `options` will not match the expected type

packages/combobox/src/ComboboxOption/ComboboxOption.stories.tsx

@@ -81,7 +81,8 @@ export const WithIconsAndCustomDisplayName: StoryType<
 WithIconsAndCustomDisplayName.parameters = {
   generate: {
     args: {
-      displayName: (
+      displayName: 'Option',
+      customContent: (
         <div
           className={css`
             display: flex;

packages/combobox/src/ComboboxOption/ComboboxOption.tsx

@@ -30,6 +30,7 @@ export const InternalComboboxOption = React.forwardRef<
       glyph,
       isSelected,
       displayName,
+      customContent,
       isFocused,
       setSelected,
       className,
@@ -94,14 +95,17 @@ export const InternalComboboxOption = React.forwardRef<
     // When multiselect and withoutIcons the Checkbox is aligned to the top instead of centered.
     const multiSelectWithoutIcons = multiselect && !withIcons;
 
+    // Convert displayName ReactNode to string for aria-label and wrapJSX
+    const displayNameStr = getNodeTextContent(displayName);
+
     return (
       <InputOption
         {...rest}
         as="li"
         ref={optionRef}
         highlighted={isFocused}
         disabled={disabled}
-        aria-label={ariaLabel || getNodeTextContent(displayName) || value}
+        aria-label={ariaLabel || displayNameStr || value}
         darkMode={darkMode}
         className={getInputOptionStyles({
           size,
@@ -117,12 +121,12 @@ export const InternalComboboxOption = React.forwardRef<
           rightGlyph={rightGlyph}
           description={description}
         >
-          {typeof displayName === 'string' ? (
+          {customContent ? (
+            customContent
+          ) : (
             <span id={optionTextId}>
-              {wrapJSX(displayName, inputValue, 'strong')}
+              {wrapJSX(displayNameStr, inputValue, 'strong')}
             </span>
-          ) : (
-            displayName
           )}
         </InputOptionContent>
       </InputOption>

packages/combobox/src/ComboboxOption/ComboboxOption.types.ts

@@ -21,6 +21,12 @@ interface SharedComboboxOptionProps {
    */
   displayName?: ReactNode;
 
+  /**
+   * Optional custom content to render for the option.
+   * When provided, this ReactNode will be rendered in the option menu
+   */
+  customContent?: ReactNode;
+
   /**
    * The icon to display to the left of the option in the menu.
    */

packages/combobox/src/utils/ComboboxTestUtils.tsx

@@ -121,6 +121,7 @@ export const getComboboxJSX = (props?: renderComboboxProps) => {
 
   const label = props?.label ?? 'Some label';
   const options = props?.options ?? defaultOptions;
+  const children = props?.children;
   return (
     <LeafyGreenProvider>
       <Combobox
@@ -129,7 +130,7 @@ export const getComboboxJSX = (props?: renderComboboxProps) => {
         multiselect={props?.multiselect ?? false}
         {...props}
       >
-        {options.map(renderOption)}
+        {children ?? options.map(renderOption)}
       </Combobox>
     </LeafyGreenProvider>
   );

packages/combobox/src/utils/ComboboxUtils.spec.tsx

@@ -202,21 +202,16 @@ describe('packages/combobox/utils', () => {
       expect(result).toBe('test');
     });
 
-    test('Returns React node displayName when option has node displayName', () => {
-      const nodeDisplayName = (
-        <span>
-          <strong>Bold</strong> text
-        </span>
-      );
-      const optionsWithNode = [
+    test('Returns string displayName when option has string displayName', () => {
+      const optionsWithString = [
         {
-          value: 'node-option',
-          displayName: nodeDisplayName,
+          value: 'string-option',
+          displayName: 'Bold text',
           isDisabled: false,
         },
       ];
-      const result = getDisplayNameForValue('node-option', optionsWithNode);
-      expect(result).toBe(nodeDisplayName);
+      const result = getDisplayNameForValue('string-option', optionsWithString);
+      expect(result).toBe('Bold text');
     });
   });
 
@@ -280,12 +275,13 @@ describe('packages/combobox/utils', () => {
       ]);
     });
 
-    test('flattens options with node displayName', () => {
+    test('flattens options with customContent', () => {
       const children = [
         <ComboboxOption
           key="test"
           value="test"
-          displayName={
+          displayName="Testing New"
+          customContent={
             <div>
               <span>Testing</span>
               <span>New</span>