feat: S2 unavailable menu item by LFDanLu · Pull Request #9657 · adobe/react-spectrum

LFDanLu · 2026-02-13T21:03:28Z

Closes

✅ Pull Request Checklist:

Included link to corresponding React Spectrum GitHub Issue.
Added/updated unit tests and storybook for this change (for new code or code which already has tests).
Filled out test instructions.
Updated documentation (if it already exists for this component).
Looked at the Accessibility Practices for this feature - Aria Practices

📝 Test Instructions:

Test both the S2 and RAC implementations in both storybook and docs.

🧢 Your Project:

RSP

rspbot · 2026-02-13T21:16:20Z

Build successful! 🎉

rspbot · 2026-02-17T23:23:48Z

Build successful! 🎉

LFDanLu · 2026-02-17T23:30:32Z

packages/dev/s2-docs/pages/react-aria/Menu.mdx


+### Unavailable menu items
+
+Wrap a `<MenuItem>` and a `<Popover>` with a `<UnavailableMenuItemTrigger>` and apply `isUnavailable` to disable the item's default action and show an informational popover instead.


I opted to have put the Popover directly into the example rather than create a UnavailableMenuItemTrigger wrapper in the starters since I felt it might be confusing to have Popover mentioned here but not show up in the example. Open to opinions though, not too bothered if we wanna go the same route as SubmenuTrigger and wrap the Popover in the starters

packages/@react-spectrum/s2/src/Menu.tsx

LFDanLu · 2026-02-17T23:33:11Z

packages/@react-spectrum/s2/src/Menu.tsx

+// TODO: consider if we should instead pull the RAC defined trigger here into S2. Feels useful for RAC users though, but
+// maybe shouldn't be specific to unavailable. It is very similar to SubmenuTrigger but it renders a dialog type behavior (see useSubmenuTrigger)
+// and has the concept of isUnavailable which will make the item render normally when false
+function UnavailableMenuItemTrigger(props: UnavailableMenuItemTriggerProps): JSX.Element {


UnavailableMenuItemTrigger seems a bit specific in RAC honestly, open to opinions if there should be a more generic naming/component

rspbot · 2026-02-17T23:43:38Z

Build successful! 🎉

… item description

LFDanLu · 2026-02-19T20:02:45Z

packages/@react-aria/menu/src/useMenuItem.ts

+  // TODO: this is quite specific, but description and keyboardShortcut above are also very specific
+  /** Props for the descriptive element in the end slot inside the menu item (e.g. info icon, chevron). */
+  endSlotProps: DOMAttributes,
+


I'm quite iffy about this, as stated above it is very specific. I think ideally we'd give the user a way to make arbitrary child elements in a MenuItem part of that MenuItem's aria-describedby. I could've opted to just allow the user to provide a generic aria-describedBy to the menu item and then apply ids to various other elements but we already have description and keyboard shortcut handled so figured we may be able to make end slot a thing too

Also note that due to how collection items work in RAC (aka UnavailableMenuItemTrigger in RAC is a collection branch that only renders the popover child as is), I believe that RAC level change is unavoidable since there isn't a good way to generate a id at the S2 UnavailableMenuItemTrigger level and propagate it down via context

What about allowing 'aria-describedby' as a prop and merging that with the ones we generate? Then this could be generated by S2 MenuItem and passed in. The only question would be in what order do we do the merge?

I can go this route instead, just felt potentially confusing to the end user that they'd be expected to pass aria-describedby for some things but that we'd handle doing this for such specific things like keyboard shortcut icon and description.

I think we'd should merge the user's provided value first. Is the concern here the announcement order or more so what would happen if the user provided their own ids to the keyboard icon/description and then used those in their aria-described?

rspbot · 2026-02-19T20:07:16Z

Build successful! 🎉

rspbot · 2026-02-20T01:00:41Z

Build successful! 🎉

reidbarber

LGTM

packages/react-aria-components/src/Menu.tsx

…lable_menu_item

… modality this was for accessibility, ideally users should be moved into submenu/submenu dialogs unless it is hover

rspbot · 2026-02-26T23:15:04Z

Build successful! 🎉

LFDanLu · 2026-02-26T23:45:03Z

https://www.chromatic.com/build?appId=5f0dd5ad2b5fc10022a2e320&number=1131

LFDanLu · 2026-02-26T23:26:03Z

packages/@react-aria/menu/src/useSubmenuTrigger.ts

 }

-interface SubmenuTriggerProps extends Omit<AriaMenuItemProps, 'key'> {
+interface SubmenuTriggerProps extends Omit<AriaMenuItemProps, 'key' | 'onAction'> {


technically no longer needed since this only was a problem surfaced with the RAC UnavailableItem implementation but kept it for correctness. We may want to actually support firing onAction in a non-submenu case (aka if the overlay opened is more informational/tooltip like), but then we'd need to be able to tell between that case an the standard submenu case

LFDanLu · 2026-02-26T23:27:49Z

packages/@react-spectrum/s2/src/ContextualHelp.tsx

+                  // needed so combobox/picker does not need to provide slot="title" to their provided
+                  // ContextualHelp (they get the aria-labelled by from the button)
+                  // otherwise, use the heading if available aka unavaiable menu item
+                  [DEFAULT_SLOT]: {styles: headingStyles},
+                  title: {id: titleId, styles: headingStyles}


This was a bit interesting, would it be more correct for users to provide the title slot in their ContextualHelp's? It falls back to associating with the trigger button at the moment

LFDanLu · 2026-02-26T23:28:19Z

packages/@react-spectrum/s2/src/ContextualHelp.tsx

+  marginBottom: space(8) // This only makes it 10px on mobile and should be 12px
+});
+
+// TODO: docs to come after release, for now this is just mentioned in unavaiable menu docs


We will need to discuss how we'd want to document this as well as what use cases we'd like to officially support

LFDanLu · 2026-02-26T23:34:39Z

packages/dev/s2-docs/src/OptimisticToc.tsx

UnavailableMenuItemTrigger is pretty long of a name lol, opted for wrapping

LFDanLu · 2026-02-26T23:35:26Z

packages/react-aria-components/src/Popover.tsx

  // Skip this for submenus since hovering a submenutrigger should keep focus on the trigger
  useEffect(() => {
-    if (isDialog && props.trigger !== 'SubmenuTrigger' && ref.current && !isFocusWithin(ref.current)) {
+    if (isDialog && (props.trigger !== 'SubmenuTrigger' || getInteractionModality() !== 'pointer') && ref.current && !isFocusWithin(ref.current)) {


this seems to work from testing, will need to pay special attention to this in our next test session

rspbot · 2026-02-26T23:52:07Z

Build successful! 🎉

devongovett · 2026-02-27T01:13:03Z

packages/dev/s2-docs/pages/react-aria/Menu.mdx

-          <Text slot="label">Delete…</Text>
-          <Keyboard>⌘⌫</Keyboard>
-        </MenuItem>
+        <UnavailableMenuItemTrigger isUnavailable>


Do we want to add this pattern to RAC, even in the examples? I thought it was pretty Spectrum-specific.

I figured it would serve as a good common use example since otherwise I would just have a generic informational popover which felt too much like a tooltip

devongovett · 2026-02-27T01:18:29Z

packages/dev/s2-docs/pages/s2/Menu.mdx

+Wrap a `<MenuItem>` and a `<ContextualHelpPopover>` with a `<UnavailableMenuItemTrigger>` and apply `isUnavailable` to disable the item's default action and show an informational popover instead.
+The `<ContextualHelpPopover>` supports `<Heading slot="title">`, `<Content>`, and `<Footer>` slots.


This is a bit verbose IMO. I think we can let the example code speak for itself.

Suggested change

Wrap a `<MenuItem>` and a `<ContextualHelpPopover>` with a `<UnavailableMenuItemTrigger>` and apply `isUnavailable` to disable the item's default action and show an informational popover instead.

The `<ContextualHelpPopover>` supports `<Heading slot="title">`, `<Content>`, and `<Footer>` slots.

Wrap a `<MenuItem>` with an `<UnavailableMenuItemTrigger>` to disable the item's default action and show a [contextual help](ContextualHelp) popover instead.

devongovett · 2026-02-27T01:18:51Z

packages/dev/s2-docs/pages/s2/Menu.mdx

    </SubmenuTrigger>
+    <UnavailableMenuItemTrigger>
+      <MenuItem />
+      <Popover />


Should be ContextualHelpPopover now.

whoops good catch. I've decided to also omit ContextualHelpPopover from the API at the bottom until the API settles too.

rspbot · 2026-02-27T01:47:19Z

Build successful! 🎉

snowystinger · 2026-02-27T06:04:39Z

packages/@react-spectrum/s2/intl/zh-TW.json

  "label.(optional)": "(選填)",
  "label.(required)": "(必填)",
  "menu.moreActions": "更多動作",
+  "menu.unavailable": "無法使用，展開以取得詳細資料",


add this to the migrate intl script so that it isn't removed accidentally in the future if someone uses that to migrate more strings

rspbot · 2026-02-27T18:16:21Z

Build successful! 🎉

rspbot · 2026-02-27T18:16:23Z

## API Changes

@react-aria/menu

/@react-aria/menu:AriaMenuItemProps

 AriaMenuItemProps {
   aria-controls?: string
+  aria-describedby?: string
   aria-expanded?: boolean | 'true' | 'false'
   aria-haspopup?: 'menu' | 'dialog'
   aria-label?: string
   id?: string
   key: Key
   onBlur?: (FocusEvent<Target>) => void
   onClick?: (MouseEvent<FocusableElement>) => void
   onFocus?: (FocusEvent<Target>) => void
   onFocusChange?: (boolean) => void
   onHoverChange?: (boolean) => void
   onHoverEnd?: (HoverEvent) => void
   onHoverStart?: (HoverEvent) => void
   onKeyDown?: (KeyboardEvent) => void
   onKeyUp?: (KeyboardEvent) => void
   onPress?: (PressEvent) => void
   onPressChange?: (boolean) => void
   onPressEnd?: (PressEvent) => void
   onPressStart?: (PressEvent) => void
   onPressUp?: (PressEvent) => void
   selectionManager?: SelectionManager
   shouldCloseOnSelect?: boolean
 }

@react-spectrum/s2

/@react-spectrum/s2:TreeView

 TreeView <T extends {}> {
   UNSAFE_className?: UnsafeClassName
   UNSAFE_style?: CSSProperties
   aria-describedby?: string
   aria-details?: string
   aria-label?: string
   aria-labelledby?: string
   autoFocus?: boolean | FocusStrategy
   children?: ReactNode | (T) => ReactNode
   defaultExpandedKeys?: Iterable<Key>
   defaultSelectedKeys?: 'all' | Iterable<Key>
   dependencies?: ReadonlyArray<any>
   disabledBehavior?: DisabledBehavior = 'all'
   disabledKeys?: Iterable<Key>
   disallowEmptySelection?: boolean
   escapeKeyBehavior?: 'clearSelection' | 'none' = 'clearSelection'
   expandedKeys?: Iterable<Key>
   id?: string
   items?: Iterable<T>
   onAction?: (Key) => void
   onExpandedChange?: (Set<Key>) => any
   onSelectionChange?: (Selection) => void
-  renderActionBar?: ('all' | Set<Key>) => ReactElement
   renderEmptyState?: (TreeEmptyStateRenderProps) => ReactNode
   selectedKeys?: 'all' | Iterable<Key>
   selectionMode?: SelectionMode
   shouldSelectOnPressUp?: boolean
   styles?: StylesPropWithHeight
 }

/@react-spectrum/s2:TreeViewProps

 TreeViewProps <T> {
   UNSAFE_className?: UnsafeClassName
   UNSAFE_style?: CSSProperties
   aria-describedby?: string
   aria-details?: string
   aria-label?: string
   aria-labelledby?: string
   autoFocus?: boolean | FocusStrategy
   children?: ReactNode | (T) => ReactNode
   defaultExpandedKeys?: Iterable<Key>
   defaultSelectedKeys?: 'all' | Iterable<Key>
   dependencies?: ReadonlyArray<any>
   disabledBehavior?: DisabledBehavior = 'all'
   disabledKeys?: Iterable<Key>
   disallowEmptySelection?: boolean
   escapeKeyBehavior?: 'clearSelection' | 'none' = 'clearSelection'
   expandedKeys?: Iterable<Key>
   id?: string
   items?: Iterable<T>
   onAction?: (Key) => void
   onExpandedChange?: (Set<Key>) => any
   onSelectionChange?: (Selection) => void
-  renderActionBar?: ('all' | Set<Key>) => ReactElement
   renderEmptyState?: (TreeEmptyStateRenderProps) => ReactNode
   selectedKeys?: 'all' | Iterable<Key>
   selectionMode?: SelectionMode
   shouldSelectOnPressUp?: boolean
   styles?: StylesPropWithHeight
 }

/@react-spectrum/s2:ContextualHelpPopover

+ContextualHelpPopover {
+  UNSAFE_className?: UnsafeClassName
+  UNSAFE_style?: CSSProperties
+  aria-describedby?: string
+  aria-details?: string
+  aria-label?: string
+  aria-labelledby?: string
+  children: ReactNode
+  containerPadding?: number = 12
+  crossOffset?: number = 0
+  hideArrow?: boolean = false
+  id?: string
+  isOpen?: boolean
+  offset?: number = 8
+  onOpenChange?: (boolean) => void
+  padding?: 'default' | 'none' = 'default'
+  placement?: Placement = 'bottom'
+  role?: 'dialog' | 'alertdialog' = 'dialog'
+  shouldFlip?: boolean = true
+  size?: 'S' | 'M' | 'L'
+  slot?: string | null
+  styles?: PopoverStylesProp
+  triggerRef?: RefObject<Element | null>
+}

/@react-spectrum/s2:UnavailableMenuItemTrigger

+UnavailableMenuItemTrigger {
+  children: Array<ReactElement>
+  isUnavailable?: boolean = false
+}

/@react-spectrum/s2:ContextualHelpProps

+ContextualHelpProps {
+  UNSAFE_className?: UnsafeClassName
+  UNSAFE_style?: CSSProperties
+  aria-describedby?: string
+  aria-details?: string
+  aria-label?: string
+  aria-labelledby?: string
+  children: ReactNode
+  containerPadding?: number = 12
+  crossOffset?: number = 0
+  defaultOpen?: boolean
+  id?: string
+  isOpen?: boolean
+  offset?: number = 8
+  onOpenChange?: (boolean) => void
+  placement?: Placement = 'bottom start'
+  shouldFlip?: boolean = true
+  size?: 'XS' | 'S' = 'XS'
+  styles?: StylesProp
+  variant?: 'info' | 'help' = 'help'
+}

/@react-spectrum/s2:ContextualHelpStyleProps

+ContextualHelpStyleProps {
+  variant?: 'info' | 'help' = 'help'
+}

/@react-spectrum/s2:ContextualHelpPopoverProps

+ContextualHelpPopoverProps {
+  UNSAFE_className?: UnsafeClassName
+  UNSAFE_style?: CSSProperties
+  aria-describedby?: string
+  aria-details?: string
+  aria-label?: string
+  aria-labelledby?: string
+  children: ReactNode
+  containerPadding?: number = 12
+  crossOffset?: number = 0
+  hideArrow?: boolean = false
+  id?: string
+  isOpen?: boolean
+  offset?: number = 8
+  onOpenChange?: (boolean) => void
+  padding?: 'default' | 'none' = 'default'
+  placement?: Placement = 'bottom'
+  role?: 'dialog' | 'alertdialog' = 'dialog'
+  shouldFlip?: boolean = true
+  size?: 'S' | 'M' | 'L'
+  slot?: string | null
+  styles?: PopoverStylesProp
+  triggerRef?: RefObject<Element | null>
+}

/@react-spectrum/s2:UnavailableMenuItemTriggerProps

+UnavailableMenuItemTriggerProps {
+  children: Array<ReactElement>
+  isUnavailable?: boolean = false
+}

packages/react-aria-components/example/index.css

…aseline-tracker * origin/main: feat(S2): S2 ListView (adobe#8878) refactor: Centralize expandedKeys logic in TreeCollection (adobe#9711) chore: Warn if user has interactive elements in their custom Picker value (adobe#9710) feat: S2 unavailable menu item (adobe#9657) fix: Ensure that opening a submenu via enter/space moves focus to first item in submenu (adobe#9691) fix: prevent docs crash by making template elements always append children into .content (adobe#9703) docs(RAC): Add TreeSection docs (adobe#9699) docs(S2): add Typography search view (adobe#9524) docs(S2): fix clipping in Picker custom value AvatarGroup example (adobe#9702) fix: patch additional methods so React doesnt break with template elements (adobe#9385) tentative fix (adobe#9635) docs(S2): fix icon import clipboard content to add underscore for icons starting with number (adobe#9698) feat(S2): add ActionBar support to TreeView (adobe#9695) fix: combobox interactoutside (adobe#9646) fix: skip native Date fast path when local timezone is overridden via setLocalTimeZone (adobe#9678) chore: update storybook to 9 (adobe#8634) docs: improve custom render value S2 Picker example (adobe#9682) # Conflicts: # yarn.lock

LFDanLu added 4 commits February 12, 2026 16:56

add unavailable menu item to RAC and S2

7d8cb6f

add translations

60eacd3

add tests and stories

4f1062b

dont propagate submenutrigger props if non unavailable

6f63c72

github-actions bot added needs translations RAC S2 labels Feb 13, 2026

fix test

8d51d50

add docs for unavailable menu item

ba3bbbb

LFDanLu commented Feb 17, 2026

View reviewed changes

packages/@react-spectrum/s2/src/Menu.tsx Outdated Show resolved Hide resolved

LFDanLu commented Feb 17, 2026

View reviewed changes

LFDanLu changed the title ~~feat: (WIP) S2 unavailable menu item~~ feat: S2 unavailable menu item Feb 17, 2026

fix docs lint

84f4ac7

LFDanLu marked this pull request as ready for review February 18, 2026 18:49

LFDanLu added ready for review and removed needs translations labels Feb 19, 2026

LFDanLu added 2 commits February 19, 2026 10:40

fix styling and copy

83b14b3

add endSlotProps so we can associate arbitrary elements with the menu…

a205895

… item description

github-actions bot added the needs translations label Feb 19, 2026

LFDanLu commented Feb 19, 2026

View reviewed changes

shift icon down 1px

92f67d9

reidbarber previously approved these changes Feb 20, 2026

View reviewed changes

packages/react-aria-components/src/Menu.tsx Outdated Show resolved Hide resolved

LFDanLu added 2 commits February 20, 2026 09:56

Merge branch 'main' of github.com:adobe/react-spectrum into s2_unavai…

b9cfd3e

…lable_menu_item

adding alpha badge to RAC unavailable menu

bf8d6f6

LFDanLu dismissed reidbarber’s stale review via 777f1a6 February 25, 2026 20:35

github-actions bot added the needs translations label Feb 25, 2026

LFDanLu added 3 commits February 26, 2026 10:17

fix styling and slot of contextual help

5b1cc3a

update examples, not sure why docs wont run

8a1fa18

fix docs and automatically move focus into the Popover if not pointer…

b49e068

… modality this was for accessibility, ideally users should be moved into submenu/submenu dialogs unless it is hover

LFDanLu removed the needs translations label Feb 26, 2026

forgot one todo

6f9c5f4

github-actions bot added the needs translations label Feb 26, 2026

LFDanLu commented Feb 26, 2026

View reviewed changes

LFDanLu removed the needs translations label Feb 26, 2026

devongovett reviewed Feb 27, 2026

View reviewed changes

review comments

87effbe

github-actions bot added the needs translations label Feb 27, 2026

snowystinger reviewed Feb 27, 2026

View reviewed changes

LFDanLu added 2 commits February 27, 2026 09:06

add menu strings to intl script

49260b7

remove RAC example

fb4fd85

reidbarber reviewed Feb 27, 2026

View reviewed changes

packages/react-aria-components/example/index.css Show resolved Hide resolved

packages/react-aria-components/example/index.css Show resolved Hide resolved

reidbarber approved these changes Feb 27, 2026

View reviewed changes

devongovett approved these changes Feb 27, 2026

View reviewed changes

LFDanLu added this pull request to the merge queue Feb 27, 2026

Merged via the queue into main with commit 32c96fc Feb 27, 2026
29 checks passed

LFDanLu deleted the s2_unavailable_menu_item branch February 27, 2026 23:49


		### Unavailable menu items

		Wrap a `<MenuItem>` and a `<Popover>` with a `<UnavailableMenuItemTrigger>` and apply `isUnavailable` to disable the item's default action and show an informational popover instead.

		Wrap a `<MenuItem>` and a `<ContextualHelpPopover>` with a `<UnavailableMenuItemTrigger>` and apply `isUnavailable` to disable the item's default action and show an informational popover instead.
		The `<ContextualHelpPopover>` supports `<Heading slot="title">`, `<Content>`, and `<Footer>` slots.

	Wrap a `<MenuItem>` and a `<ContextualHelpPopover>` with a `<UnavailableMenuItemTrigger>` and apply `isUnavailable` to disable the item's default action and show an informational popover instead.
	The `<ContextualHelpPopover>` supports `<Heading slot="title">`, `<Content>`, and `<Footer>` slots.
	Wrap a `<MenuItem>` with an `<UnavailableMenuItemTrigger>` to disable the item's default action and show a [contextual help](ContextualHelp) popover instead.

Conversation

LFDanLu commented Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Pull Request Checklist:

📝 Test Instructions:

🧢 Your Project:

Uh oh!

rspbot commented Feb 13, 2026

Uh oh!

rspbot commented Feb 17, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rspbot commented Feb 17, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LFDanLu Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rspbot commented Feb 19, 2026

Uh oh!

rspbot commented Feb 20, 2026

Uh oh!

reidbarber left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rspbot commented Feb 26, 2026

Uh oh!

LFDanLu commented Feb 26, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rspbot commented Feb 26, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LFDanLu Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rspbot commented Feb 27, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rspbot commented Feb 27, 2026

Uh oh!

rspbot commented Feb 27, 2026

@react-aria/menu

/@react-aria/menu:AriaMenuItemProps

@react-spectrum/s2

/@react-spectrum/s2:TreeView

/@react-spectrum/s2:TreeViewProps

/@react-spectrum/s2:ContextualHelpPopover

/@react-spectrum/s2:UnavailableMenuItemTrigger

/@react-spectrum/s2:ContextualHelpProps

/@react-spectrum/s2:ContextualHelpStyleProps

LFDanLu commented Feb 13, 2026 •

edited

Loading

LFDanLu Feb 24, 2026 •

edited

Loading

LFDanLu Feb 27, 2026 •

edited

Loading