Function: useSharedHero()

function useSharedHero(initial?): object;

State helper for in-place (non-navigation) shared-hero transitions within the same screen.

Render two <SharedHero id="x"> branches keyed on active (for example, a collapsed pill and an expanded card). Calling start(), end(), or toggle() swaps which branch is mounted, and the native coordinator matches the unmounting and mounting views within the same frame to run a flight.

Navigation-driven transitions (React Navigation, Expo Router, <Modal>) do not need this hook.

Parameters

Parameter	Type	Default value	Description
initial?	boolean	false	Initial value of active. Defaults to false.

Returns

An object with the current active boolean and stable start, end, and toggle callbacks.

Name	Type	Description
active	boolean	Whether the transition is currently in the active (expanded) state.
end()	() => void	Sets active to false.
start()	() => void	Sets active to true.
toggle()	() => void	Flips active between false and true.

Example

const { active, toggle } = useSharedHero();

return (
  <Pressable onPress={toggle}>
    {active ? (
      <SharedHero id="player" mode="morph" style={styles.expanded}>
        <ExpandedPlayer />
      </SharedHero>
    ) : (
      <SharedHero id="player" mode="morph" style={styles.mini}>
        <MiniPlayer />
      </SharedHero>
    )}
  </Pressable>
);