Skip to main content

Settle animation

When a drag ends or the index changes, a spring carries the sheet to its detent. The same spring runs when the sheet animates in, when a scrim tap closes it, and when a 'content' detent changes height. settleDuration is how long, in milliseconds, that spring takes. Left unset, it takes 450 milliseconds on every platform. It must be a finite number greater than 0; the library throws an Error for values such as 0, -1 or NaN.

<BottomSheet
detents={[0, 'content']}
index={index}
onIndexChange={setIndex}
settleDuration={550}
surface={/* ... */}
>
{/* ... */}
</BottomSheet>

The spring is critically damped, so the duration is also its stiffness: a longer duration is a softer settle.

The spring starts at the release velocity, as native sheets do, so the sheet moves on at the speed the finger let go and never jumps or stalls. A release moving away from the detent is capped at five times the remaining distance per second, so the sheet turns back promptly. The sheet never passes its detent either: when a release is faster than the spring can stop in time, the spring stiffens just enough to land on the detent, so a fast fling finishes sooner than settleDuration. A settle that starts without velocity, such as an index change, always takes the full duration.