Animation Presets, Metrics, and Gestures

This guide documents the recommended animation presets in @digiwedge/gluestack-ui, where to use them, and how to monitor and extend animations safely.

Preset Selection (Use Case Map)

Use case	Recommended transition	Notes
Modal	transitions.modal	Balanced fade + slide for dialogs/sheets
Bottom sheet	transitions.sheet	Slide up/down from bottom
Dropdown/menu	transitions.dropdown	Subtle fade down/up
Tooltip/Popover	transitions.overlay	Simple fade for overlays
Toast/snackbar	transitions.toast	Slide in from right by default
Dialog/Alert	transitions.dialog or transitions.alert	Zoom for dialogs, bounce for alerts
List item entry	transitions.listItem	Use with useStagger for lists
Drawer	transitions.drawerLeft / transitions.drawerRight	Side panels
Notifications	transitions.notification	Slide down/up
FAB emphasis	transitions.fab	Bounce + zoom
Card reveal	transitions.card	Zoom in, fade out
Success state	transitions.success	Bouncy entry
Flip reveal	transitions.flip	Y-axis flip
Page navigation	transitions.pageForward / transitions.pageBack	Forward/back navigation

Hooks vs Presets

• Prefer hooks (useFade, useScale, useSlide, usePressAnimation) for components that need imperative control or state-driven animation.
• Use presets for quick mount/unmount transitions, and always gate them with useMotionPresets() to respect reduced motion.
• The repo includes a guardrail (pnpm run verify:reanimated-presets) to keep raw Reanimated presets out of app code.

Reduced Motion Gating

Use the shared helper so reduced motion disables transitions automatically:

import { useMotionPresets } from '@digiwedge/gluestack-ui';

const { entering, exiting } = useMotionPresets();

return (
  <Animated.View entering={entering?.fadeUp} exiting={exiting?.fadeDown}>
    ...
  </Animated.View>
);

Performance Monitoring (FPS)

Use the JS-frame monitor for diagnostics when animation smoothness is in question. Keep this dev-only.

import { useAnimationFrameRate } from '@digiwedge/gluestack-ui';

const { fps } = useAnimationFrameRate({ enabled: __DEV__ });

return <Text>FPS: {fps ?? '-'} </Text>;

Notes:

• This measures JS frame rate, not the UI thread.
• For UI-thread metrics, use RN/Expo performance overlays or native profiling.

Gesture-Driven Animations

Use SwipeableRow or wire useSwipe directly:

import { SwipeableRow } from '@digiwedge/gluestack-ui';

<SwipeableRow onSwipeLeft={() => dismiss()} onSwipeRight={() => archive()}>
  <Card>Swipe me</Card>
</SwipeableRow>

If you need custom gesture control, call useSwipe and feed it PanResponder or gesture-handler events.