Collapsible
This API is in alpha. It can change in any release, including patch releases. Pin the exact version. Issue #31 lists the changes we plan.
Collapsible builds a collapsible header from presets. It uses the HeaderMotion provider, the measured header, and the animated styles for you. You compose the header from parts and select a preset for the animation.
Collapsible uses only the public low-level API, and it passes every low-level prop through. You can change to the low-level API at any time.
Parts
import { Collapsible } from 'react-native-header-motion';
import { Stack } from 'expo-router';
export default function Screen() {
return (
<Collapsible preset="parallax">
<Collapsible.NavigationHeader
render={(header) => <Stack.Screen options={{ header: () => header }} />}
>
<Collapsible.Pinned>
<TitleRow />
</Collapsible.Pinned>
<Collapsible.Dynamic>
<Hero />
</Collapsible.Dynamic>
<SearchBar />
</Collapsible.NavigationHeader>
<Collapsible.ScrollView>{content}</Collapsible.ScrollView>
</Collapsible>
);
}
Each part sets how its content moves when the header collapses:
Collapsibleis the root. It renders aHeaderMotionprovider and gives thepresetto the parts. It shows nothing on screen.Collapsible.Headeris the header frame. It measures the full header height, asHeaderMotion.Headerdoes. It moves up by the collapse distance when the user scrolls.Collapsible.Pinnedholds content that stays in the same screen position, for example a title row or action buttons. It moves down by the same distance that the frame moves up. Put it aboveCollapsible.Dynamic.Collapsible.Dynamicis the section that collapses. Its measured height sets the collapse distance, asHeaderMotion.Header.Dynamicdoes. The preset animates its content. Content below it, such as theSearchBarabove, moves up and stops under the pinned content.Collapsible.NavigationHeaderis aCollapsible.Headerthat a navigation library renders. It replaces theBridgeandNavigationBridgesteps. Put the header content in its children, and userenderto give the header to your navigator.Collapsible.ScrollViewandCollapsible.FlatListare the same components asHeaderMotion.ScrollViewandHeaderMotion.FlatList. Custom scrollables fromcreateHeaderMotionScrollable()also work.
Headers without a navigation library
If a navigation library does not render your header, use Collapsible.Header. It shows on top of the content, as HeaderMotion.Header does:
<Collapsible preset="fade">
<Collapsible.Header style={styles.header}>
<Collapsible.Pinned>
<TitleRow />
</Collapsible.Pinned>
<Collapsible.Dynamic>
<Hero />
</Collapsible.Dynamic>
</Collapsible.Header>
<Collapsible.ScrollView>{content}</Collapsible.ScrollView>
</Collapsible>
Props
Collapsible
Accepts all HeaderMotion props (progressThreshold, measureDynamic, measureDynamicMode, activeScrollId, progressExtrapolation), and these props:
| Prop | Type | Default | Description |
|---|---|---|---|
preset | CollapsiblePresetInput | 'collapse' | How the collapsing content moves. See Presets. |
onStateChange | (state: 'expanded' | 'collapsed') => void | — | Called when the header becomes fully expanded or fully collapsed. |
Collapsible.Header and Collapsible.NavigationHeader
Accept all HeaderMotion.Header props except asChild: overlay, pannable, panDecayConfig, withGestureHandlerRootView, and all Animated.View props. Collapsible.NavigationHeader also needs this prop:
| Prop | Type | Description |
|---|---|---|
render | (header: ReactElement) => ReactNode | Puts the header into your navigator. The header already has all the contexts it needs. |
Collapsible.Dynamic
Accepts all HeaderMotion.Header.Dynamic props except asChild, and this prop:
| Prop | Type | Description |
|---|---|---|
contentStyle | Animated.View style | Style for the inner view that the preset animates. Put layout styles for the measured wrapper on style. |
The wrapper clips its content (overflow: 'hidden'). To change this, set overflow in style.
Collapsible.Pinned
Accepts all Animated.View props.
Collapse and expand from code
useCollapsibleHeader() gives the motion values and two functions, collapse() and expand(). You can use it anywhere in the tree, also in a plain HeaderMotion tree:
import { useCollapsibleHeader } from 'react-native-header-motion';
const { progress, progressThreshold, collapse, expand } =
useCollapsibleHeader();
collapse(); // scrolls the active scrollable until the header is fully collapsed
expand({ animated: false });
Pull to refresh
The scrollables accept refreshing, onRefresh, and refreshControl, as their low-level versions do. For a custom refresh indicator, use HeaderMotion.RefreshControl and read its state with useRefreshControl() in the header. See Pull to refresh.