useOverlayItems

useOverlayItems() returns the current ReadonlyArray<OverlayItem>. It uses useSyncExternalStore with the provider store's subscribe, getSnapshot, and getInitialSnapshot, so React receives consistent snapshots during rendering.

function OverlayDebugPanel() {
  const items = useOverlayItems();

  return <pre>{JSON.stringify(items, null, 2)}</pre>;
}

useOverlayItem(id) subscribes to one item and returns OverlayItem | undefined, with an Object.is bailout when that item reference is unchanged. Use it when a component needs one lifecycle state without rerendering for unrelated overlays.

Most apps do not need the full-list hook directly because OverlayHost already uses it. It becomes useful for diagnostics, custom host experiments, analytics panels, or test-only components. Do not mutate the returned items. Treat them as a read-only snapshot and use useOverlay commands to change lifecycle state.

Practical note

The reference pages describe the runtime contract exactly. Guides may wrap these APIs into product-specific helpers, but those helpers should keep the same lifecycle language: open creates an item, close starts a closing state, remove settles and deletes an item, and clear ends every pending overlay in the provider scope.