feat: add Avatar support for ComboBoxItem and PickerItem (#8931)

dkario · Dylan Kario · LFDanLu · web-flow · commit 8a49fc909b83 · 2025-09-30T20:41:11.000Z
* feat: add Avatar support for ComboBoxItem and PickerItem

For the new `avatar` style macro, I copied a subset of ComboBox's `image` style macro.

Avatar controls size via its `size` prop, so I didn't include that in the style macro.

* feat: avatar support for Picker button, render for AvatarContextValue

* Add center baseline to Avatar by default

* Simplify s2-docs for ComboBox and Picker with Avatars

* Add defaultValue and placeholder to new ComboBox/Picker docs

---------

Co-authored-by: Dylan Kario &lt;kario@adobe.com&gt;
Co-authored-by: Daniel Lu &lt;dl1644@gmail.com&gt;
Co-authored-by: Devon Govett &lt;devongovett@gmail.com&gt;
Co-authored-by: Yihui Liao &lt;44729383+yihuiliao@users.noreply.github.com&gt;
diff --git a/packages/@react-spectrum/s2/chromatic/Combobox.stories.tsx b/packages/@react-spectrum/s2/chromatic/Combobox.stories.tsx
@@ -10,7 +10,7 @@
  * governing permissions and limitations under the License.
  */
 
-import {AsyncComboBoxStory, AsyncComboBoxStoryType, ContextualHelpExample, CustomWidth, Dynamic, EmptyCombobox, Example, Sections, WithIcons} from '../stories/ComboBox.stories';
+import {AsyncComboBoxStory, AsyncComboBoxStoryType, ContextualHelpExample, CustomWidth, Dynamic, EmptyCombobox, Example, Sections, WithAvatars, WithIcons} from '../stories/ComboBox.stories';
 import {ComboBox} from '../src';
 import {expect} from '@storybook/jest';
 import type {Meta, StoryObj} from '@storybook/react';
@@ -58,6 +58,12 @@ export const Icons: Story = {
   play: Static.play
 };
 
+export const Avatars: Story = {
+  ...WithAvatars,
+  name: 'With Avatars',
+  play: Static.play
+};
+
 export const ContextualHelp: Story = {
   ...ContextualHelpExample,
   play: async ({canvasElement}) => {
diff --git a/packages/@react-spectrum/s2/chromatic/ComboboxRTL.stories.tsx b/packages/@react-spectrum/s2/chromatic/ComboboxRTL.stories.tsx
@@ -23,4 +23,4 @@ const meta: Meta<typeof ComboBox<any>> = {
 };
 
 export default meta;
-export {Static, WithSections, WithDynamic, Icons, ContextualHelp, WithCustomWidth} from './Combobox.stories';
+export {Static, WithSections, WithDynamic, Icons, Avatars, ContextualHelp, WithCustomWidth} from './Combobox.stories';
diff --git a/packages/@react-spectrum/s2/chromatic/Picker.stories.tsx b/packages/@react-spectrum/s2/chromatic/Picker.stories.tsx
@@ -10,7 +10,7 @@
  * governing permissions and limitations under the License.
  */
 
-import {AsyncPickerStory, AsyncPickerStoryType, ContextualHelpExample, CustomWidth, Dynamic, Example, Sections, WithIcons} from '../stories/Picker.stories';
+import {AsyncPickerStory, AsyncPickerStoryType, ContextualHelpExample, CustomWidth, Dynamic, Example, Sections, WithAvatars, WithIcons} from '../stories/Picker.stories';
 import {expect} from '@storybook/jest';
 import type {Meta, StoryObj} from '@storybook/react';
 import {Picker} from '../src';
@@ -56,6 +56,12 @@ export const Icons: Story = {
   play: Default.play
 };
 
+export const Avatars: Story = {
+  ...WithAvatars,
+  name: 'With Avatars',
+  play: Default.play
+};
+
 export const WithCustomWidth: Story = {
   ...CustomWidth,
   play: Default.play
diff --git a/packages/@react-spectrum/s2/chromatic/PickerRTL.stories.tsx b/packages/@react-spectrum/s2/chromatic/PickerRTL.stories.tsx
@@ -22,4 +22,4 @@ const meta: Meta<typeof Picker<any>> = {
 };
 
 export default meta;
-export {Default, WithSections, DynamicExample, Icons, WithCustomWidth, ContextualHelp} from './Picker.stories';
+export {Default, WithSections, DynamicExample, Icons, Avatars, WithCustomWidth, ContextualHelp} from './Picker.stories';
diff --git a/packages/@react-spectrum/s2/src/Avatar.tsx b/packages/@react-spectrum/s2/src/Avatar.tsx
@@ -10,6 +10,7 @@
  * governing permissions and limitations under the License.
  */
 
+import {centerBaselineBefore} from './CenterBaseline';
 import {ContextValue, SlotProps} from 'react-aria-components';
 import {createContext, forwardRef} from 'react';
 import {DOMProps, DOMRef, DOMRefValue} from '@react-types/shared';
@@ -37,6 +38,8 @@ export interface AvatarProps extends UnsafeStyles, DOMProps, SlotProps {
 }
 
 const imageStyles = style({
+  display: 'flex',
+  alignItems: 'center',
   borderRadius: 'full',
   size: 20,
   flexShrink: 0,
@@ -86,7 +89,7 @@ export const Avatar = forwardRef(function Avatar(props: AvatarProps, ref: DOMRef
         width: remSize,
         height: remSize
       }}
-      UNSAFE_className={UNSAFE_className}
+      UNSAFE_className={UNSAFE_className + ' ' +  centerBaselineBefore}
       styles={imageStyles({isOverBackground, isLarge}, props.styles)}
       src={src} />
   );
diff --git a/packages/@react-spectrum/s2/src/ComboBox.tsx b/packages/@react-spectrum/s2/src/ComboBox.tsx
@@ -34,6 +34,7 @@ import {
   Virtualizer
 } from 'react-aria-components';
 import {AsyncLoadable, GlobalDOMAttributes, HelpTextProps, LoadingState, SpectrumLabelableProps} from '@react-types/shared';
+import {AvatarContext} from './Avatar';
 import {BaseCollection, CollectionNode, createLeafComponent} from '@react-aria/collections';
 import {baseColor, edgeToText, focusRing, space, style} from '../style' with {type: 'macro'};
 import {centerBaseline} from './CenterBaseline';
@@ -306,6 +307,11 @@ const dividerStyle = style({
   width: 'full'
 });
 
+const avatar = style({
+  gridArea: 'icon',
+  marginEnd: 'text-to-visual'
+});
+
 // Not from any design, just following the sizing of the existing rows
 export const LOADER_ROW_HEIGHTS = {
   S: {
@@ -365,6 +371,13 @@ export interface ComboBoxItemProps extends Omit<ListBoxItemProps, 'children' | '
   children: ReactNode
 }
 
+const avatarSize = {
+  S: 16,
+  M: 20,
+  L: 22,
+  XL: 26
+} as const;
+
 const checkmarkIconSize = {
   S: 'XS',
   M: 'M',
@@ -394,6 +407,11 @@ export function ComboBoxItem(props: ComboBoxItemProps): ReactNode {
                     icon: {render: centerBaseline({slot: 'icon', styles: iconCenterWrapper}), styles: icon}
                   }
                 }],
+                [AvatarContext, {
+                  slots: {
+                    avatar: {size: avatarSize[size], styles: avatar}
+                  }
+                }],
                 [TextContext, {
                   slots: {
                     label: {styles: label({size})},
diff --git a/packages/@react-spectrum/s2/src/Picker.tsx b/packages/@react-spectrum/s2/src/Picker.tsx
@@ -33,6 +33,7 @@ import {
   Virtualizer
 } from 'react-aria-components';
 import {AsyncLoadable, FocusableRef, FocusableRefValue, GlobalDOMAttributes, HelpTextProps, LoadingState, PressEvent, RefObject, SpectrumLabelableProps} from '@react-types/shared';
+import {AvatarContext} from './Avatar';
 import {baseColor, edgeToText, focusRing, style} from '../style' with {type: 'macro'};
 import {box, iconStyles as checkboxIconStyles} from './Checkbox';
 import {centerBaseline} from './CenterBaseline';
@@ -241,6 +242,11 @@ const iconStyles = style({
   }
 });
 
+const avatar = style({
+  gridArea: 'icon',
+  marginEnd: 'text-to-visual'
+});
+
 const loadingWrapperStyles = style({
   gridColumnStart: '1',
   gridColumnEnd: '-1',
@@ -468,6 +474,13 @@ function PickerProgressCircle(props) {
   );
 }
 
+const avatarSize = {
+  S: 16,
+  M: 20,
+  L: 22,
+  XL: 26
+} as const;
+
 interface PickerButtonInnerProps<T extends object> extends PickerStyleProps, Omit<AriaSelectRenderProps, 'isRequired' | 'isFocused'>, Pick<PickerProps<T>, 'loadingState'> {
   loadingCircle: ReactNode,
   buttonRef: RefObject<HTMLButtonElement | null>
@@ -519,7 +532,7 @@ const PickerButton = createHideableComponent(function PickerButton<T extends obj
         })}>
         {(renderProps) => (
           <>
-            <SelectValue className={valueStyles({isQuiet}) + ' ' + raw('&> * {display: none;}')}>
+            <SelectValue className={valueStyles({isQuiet}) + ' ' + raw('&> :not([slot=icon], [slot=avatar], [slot=label]) {display: none;}')}>
               {({selectedItems, defaultChildren}) => {
                 return (
                   <Provider
@@ -532,6 +545,14 @@ const PickerButton = createHideableComponent(function PickerButton<T extends obj
                           }
                         }
                       }],
+                      [AvatarContext, {
+                        slots: {
+                          avatar: {
+                            size: avatarSize[size ?? 'M'],
+                            styles: avatar
+                          }
+                        }
+                      }],
                       [TextContext, {
                         slots: {
                           description: {},
@@ -606,21 +627,27 @@ export function PickerItem(props: PickerItemProps): ReactNode {
               icon: {render: centerBaseline({slot: 'icon', styles: iconCenterWrapper}), styles: icon}
             }}}>
             <DefaultProvider
-              context={TextContext}
-              value={{
-                slots: {
-                  [DEFAULT_SLOT]: {styles: label({size})},
-                  label: {styles: label({size})},
-                  description: {styles: description({...renderProps, size})}
-                }
-              }}>
-              {renderProps.selectionMode === 'single' && !isLink && <CheckmarkIcon size={checkmarkIconSize[size]} className={checkmark({...renderProps, size})} />}
-              {renderProps.selectionMode === 'multiple' && !isLink && (
-                <div className={mergeStyles(checkbox, box(checkboxRenderProps))}>
-                  <CheckmarkIcon size={size} className={checkboxIconStyles} />
-                </div>
+              context={AvatarContext}
+              value={{slots: {
+                avatar: {size: avatarSize[size], styles: avatar}
+              }}}>
+              <DefaultProvider
+                context={TextContext}
+                value={{
+                  slots: {
+                    [DEFAULT_SLOT]: {styles: label({size})},
+                    label: {styles: label({size})},
+                    description: {styles: description({...renderProps, size})}
+                  }
+                }}>
+                {renderProps.selectionMode === 'single' && !isLink && <CheckmarkIcon size={checkmarkIconSize[size]} className={checkmark({...renderProps, size})} />}
+                {renderProps.selectionMode === 'multiple' && !isLink && (
+                  <div className={mergeStyles(checkbox, box(checkboxRenderProps))}>
+                    <CheckmarkIcon size={size} className={checkboxIconStyles} />
+                  </div>
               )}
-              {typeof children === 'string' ? <Text slot="label">{children}</Text> : children}
+                {typeof children === 'string' ? <Text slot="label">{children}</Text> : children}
+              </DefaultProvider>
             </DefaultProvider>
           </DefaultProvider>
         );
diff --git a/packages/@react-spectrum/s2/stories/ComboBox.stories.tsx b/packages/@react-spectrum/s2/stories/ComboBox.stories.tsx
@@ -10,7 +10,7 @@
  * governing permissions and limitations under the License.
  */
 
-import {Button, ComboBox, ComboBoxItem, ComboBoxSection, Content, ContextualHelp, Footer, Form, Header, Heading, Link, Text} from '../src';
+import {Avatar, Button, ComboBox, ComboBoxItem, ComboBoxSection, Content, ContextualHelp, Footer, Form, Header, Heading, Link, Text} from '../src';
 import {categorizeArgTypes, getActionArgs} from './utils';
 import {ComboBoxProps} from 'react-aria-components';
 import DeviceDesktopIcon from '../s2wf-icons/S2_Icon_DeviceDesktop_20_N.svg';
@@ -154,6 +154,33 @@ export const WithIcons: Story = {
   }
 };
 
+const SRC_URL_1 = 'https://i.imgur.com/xIe7Wlb.png';
+const SRC_URL_2 = 'https://mir-s3-cdn-cf.behance.net/project_modules/disp/690bc6105945313.5f84bfc9de488.png';
+
+export const WithAvatars: Story = {
+  render: (args) => (
+    <ComboBox {...args}>
+      <ComboBoxItem textValue="User One">
+        <Avatar slot="avatar" src={SRC_URL_1} />
+        <Text slot="label">User One</Text>
+        <Text slot="description">user.one@example.com</Text>
+      </ComboBoxItem>
+      <ComboBoxItem textValue="User Two">
+        <Avatar slot="avatar" src={SRC_URL_2} />
+        <Text slot="label">User Two</Text>
+        <Text slot="description">user.two@example.com<br />123-456-7890</Text>
+      </ComboBoxItem>
+      <ComboBoxItem textValue="User Three">
+        <Avatar slot="avatar" src={SRC_URL_2} />
+        <Text slot="label">User Three</Text>
+      </ComboBoxItem>
+    </ComboBox>
+  ),
+  args: {
+    label: 'Share'
+  }
+};
+
 export const Validation: Story = {
   render: (args) => (
     <Form>
diff --git a/packages/@react-spectrum/s2/stories/Picker.stories.tsx b/packages/@react-spectrum/s2/stories/Picker.stories.tsx
@@ -11,6 +11,7 @@
  */
 
 import {
+  Avatar,
   Button,
   Content,
   ContextualHelp,
@@ -144,6 +145,33 @@ export const WithIcons: Story = {
   }
 };
 
+const SRC_URL_1 = 'https://i.imgur.com/xIe7Wlb.png';
+const SRC_URL_2 = 'https://mir-s3-cdn-cf.behance.net/project_modules/disp/690bc6105945313.5f84bfc9de488.png';
+
+export const WithAvatars: Story = {
+  render: (args) => (
+    <Picker {...args}>
+      <PickerItem textValue="User One">
+        <Avatar slot="avatar" src={SRC_URL_1} />
+        <Text slot="label">User One</Text>
+        <Text slot="description">user.one@example.com</Text>
+      </PickerItem>
+      <PickerItem textValue="User Two">
+        <Avatar slot="avatar" src={SRC_URL_2} />
+        <Text slot="label">User Two</Text>
+        <Text slot="description">user.two@example.com<br />123-456-7890</Text>
+      </PickerItem>
+      <PickerItem textValue="User Three">
+        <Avatar slot="avatar" src={SRC_URL_2} />
+        <Text slot="label">User Three</Text>
+      </PickerItem>
+    </Picker>
+  ),
+  args: {
+    label: 'Share'
+  }
+};
+
 function VirtualizedPicker(props) {
   let items: IExampleItem[] = [];
   for (let i = 0; i < 10000; i++) {
diff --git a/packages/dev/s2-docs/pages/s2/ComboBox.mdx b/packages/dev/s2-docs/pages/s2/ComboBox.mdx
@@ -53,34 +53,56 @@ function Example() {
 
 ### Slots
 
-`ComboBoxItem` supports icons, and `label` and `description` text slots.
+`ComboBoxItem` supports icons, avatars, and `label` and `description` text slots.
 
 ```tsx render
 "use client";
-import {ComboBox, ComboBoxItem, Text} from '@react-spectrum/s2';
+import {Avatar, ComboBox, ComboBoxItem, Text} from '@react-spectrum/s2';
+import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
 import Comment from '@react-spectrum/s2/icons/Comment';
 import Edit from '@react-spectrum/s2/icons/Edit';
 import UserSettings from '@react-spectrum/s2/icons/UserSettings';
 
-<ComboBox label="Permissions" defaultSelectedKey="read" placeholder="Select a permission level">
-  <ComboBoxItem id="read" textValue="Read">
-    {/*- begin highlight -*/}
-    <Comment />
-    <Text slot="label">Read</Text>
-    <Text slot="description">Comment only</Text>
-    {/*- end highlight -*/}
-  </ComboBoxItem>
-  <ComboBoxItem id="write" textValue="Write">
-    <Edit />
-    <Text slot="label">Write</Text>
-    <Text slot="description">Read and write only</Text>
-  </ComboBoxItem>
-  <ComboBoxItem id="admin" textValue="Admin">
-    <UserSettings />
-    <Text slot="label">Admin</Text>
-    <Text slot="description">Full access</Text>
-  </ComboBoxItem>
-</ComboBox>
+const users = Array.from({length: 5}, (_, i) => ({
+  id: `user${i + 1}`,
+  name: `User ${i + 1}`,
+  email: `user${i + 1}@example.com`,
+  avatar: 'https://i.imgur.com/kJOwAdv.png'
+}));
+
+<div className={style({display: 'flex', gap: 12, flexWrap: 'wrap'})}>
+  <ComboBox label="Permissions" defaultSelectedKey="read" placeholder="Select a permission level">
+    <ComboBoxItem id="read" textValue="Read">
+      {/*- begin highlight -*/}
+      <Comment />
+      <Text slot="label">Read</Text>
+      <Text slot="description">Comment only</Text>
+      {/*- end highlight -*/}
+    </ComboBoxItem>
+    <ComboBoxItem id="write" textValue="Write">
+      <Edit />
+      <Text slot="label">Write</Text>
+      <Text slot="description">Read and write only</Text>
+    </ComboBoxItem>
+    <ComboBoxItem id="admin" textValue="Admin">
+      <UserSettings />
+      <Text slot="label">Admin</Text>
+      <Text slot="description">Full access</Text>
+    </ComboBoxItem>
+  </ComboBox>
+  <ComboBox label="Share" items={users} defaultSelectedKey="user1" placeholder="Select a user">
+    {(item) => (
+      <ComboBoxItem id={item.id} textValue={item.name}>
+        {/*- begin highlight -*/}
+        <Avatar slot="avatar" src={item.avatar} />
+        {/*- end highlight -*/}
+        <Text slot="label">{item.name}</Text>
+        <Text slot="description">{item.email}</Text>
+      </ComboBoxItem>
+    )}
+  </ComboBox>
+</div>
+
 ```
 
 <InlineAlert variant="notice">
diff --git a/packages/dev/s2-docs/pages/s2/Picker.mdx b/packages/dev/s2-docs/pages/s2/Picker.mdx
