Native Animation

Sign in Get all-access

Base Dialog animation preview

Base Dialog animation preview

This preview uses fictional demo content. See the props below for the customization options available in this component.

npx nativeanimation add base-dialog

Base Dialog

React Native Dialog Component

A centered dialog with a spring-driven flip and configurable copy, content, footer, and theme.

Native Animation Base · Free · MIT

Read and download source

Add to your project

Copy the component and its assets into your app with the Native Animation CLI, or paste the agent prompt into Claude Code, Codex or Cursor once the MCP server is connected.

About this component

Related guides

React Native Overlay Views: Anchored Popover

A centered dialog with a spring-driven flip and configurable copy, content, footer, and theme.

How it works

A transparent React Native Modal contains its own Gesture Handler root and inherits the shared theme. Width is limited to the screen minus 32 pt, up to 512 pt.
The overlay and panel fade in over 400 ms with the theme soft curve. A 150/25 spring with mass 1 moves the panel from rotateX -20 degrees and scale 0.8 to its resting pose, with perspective 500 first in the transform list.
Exit uses the same spring and a 200 ms fade. The modal stays mounted until the spring completes; a generation guard prevents a stale exit callback from unmounting a reopened dialog.
The body scrolls without a visible indicator on short screens and accommodates the keyboard. Footer actions are stacked in reverse order so the primary action goes first.

Install

npx nativeanimation add base-dialog

The CLI also copies base-theme. Dependencies, if you copy by hand:

npx expo install react-native-gesture-handler react-native-reanimated react-native-worklets lucide-react-native react-native-svg

Load the Geist regular and medium fonts used by the theme once in your app, or supply your own font names in a custom theme. Interactive pieces need a GestureHandlerRootView at the app root. The usage examples with buttons or switches assume those Base pieces are installed separately.

Usage

import { BaseDialog } from './base-dialog';
import { BaseButton } from './base-button';

<BaseDialog visible={open} onVisibleChange={setOpen}
  role="alertdialog" title="Delete project?"
  description="This permanently deletes the project and its deployment history."
  footer={<>
    <BaseButton variant="outline" onPress={() => setOpen(false)}>Cancel</BaseButton>
    <BaseButton variant="destructive" onPress={deleteProject}>Delete project</BaseButton>
  </>} />

Wrap your app in BaseThemeProvider (from base-theme) to choose light/dark and an accent; without it, pieces use the light neutral theme. Every piece also takes a theme prop that wins over the provider.

Props

Prop	Type	Default	Description
`visible`	`boolean`	`—`	Controlled open state.
`defaultVisible`	`boolean`	`false`	Initial uncontrolled open state.
`onVisibleChange`	`(visible: boolean) => void`	`—`	Close request; update visible when controlled.
`title / description`	`string`	`—`	Centered heading and supporting text.
`children`	`ReactNode`	`—`	Dialog body, such as form fields.
`footer`	`ReactNode`	`—`	Secondary actions first, primary last; rendered in a reversed column. Direct actions receive a full-width style, including inside fragments. Custom actions must forward style.
`dismissible`	`boolean`	`true`	Enables the close button, outside tap, Back, Escape, and accessibility escape.
`showCloseButton`	`boolean`	`true`	Shows the X when dismissible.
`closeLabel`	`string`	`'Close'`	Accessible name of the close button.
`role`	`'dialog' \| 'alertdialog'`	`'dialog'`	Alert dialogs ignore outside taps; explicit actions, X, and Back still work when dismissible.
`media`	`ReactNode`	`—`	Caller-supplied content centered in a 64 pt muted box.
`theme`	`BaseTheme`	`provider`	Theme override inherited by dialog content.
`testID`	`string`	`—`	Identifier on the panel.

Compatibility

Expo SDK 58 · React Native 0.88 · Reanimated 4.7 · react-native-worklets 0.13. Targets iOS, Android, and web, including Expo Go and development builds. Part of Native Animation Base, a free family sharing one theme; the CLI installs its family dependencies automatically.

Accessibility

The panel declares dialog or alertdialog semantics, an accessible heading and description, and modal isolation. The close button has a 44 × 44 pt target and a customizable accessible label. Outside taps do not dismiss alert dialogs. Back, Escape, and the accessibility escape gesture honor dismissible. Web focus containment and restoration are provided by React Native's Modal; verify the complete form with VoiceOver/TalkBack in the host app. Reduce Motion removes the flip and scale and changes opacity immediately.

Part of a shared foundation

Use it in a screen

Compose Base Dialog with other Base components and a single shared theme. Ask your agent to read each API, then connect real navigation, state, and callbacks.

Build a habit tracker Build with an agent CLI and manual installation Theme and dark mode Accessibility checklist Native Animation Base UI library

Go further.

Base covers the everyday. Choose a more expressive interaction when your app calls for it.

Another way to solve this task · $9

Stacked Category Cards ↗

A category stack whose tabs unfold into detail cards, with configurable categories, title, colors, and fonts.

Another way to solve this task · $9

Review Approval Card ↗

A moderation queue with swipe-to-approve or decline feedback, with configurable reviews, labels, colors, and fonts.

Source code

Loading public source…

Dependencies

Package	Version
lucide-react-native	^1.61.0
react-native-gesture-handler	~3.3.0
react-native-reanimated	4.7.1
react-native-svg	15.16.0
react-native-worklets	0.13.0

Compatibility

SDK	Status	Revision	Last revision	Platforms	Dependencies
Expo SDK 58	Tested	2	10/28/2026	iOS, Web, Android	lucide-react-native ^1.61.0, react-native-gesture-handler ~3.3.0, react-native-reanimated 4.7.1, react-native-svg 15.16.0, react-native-worklets 0.13.0
Expo SDK 57	Tested	1	10/27/2026	iOS, Web, Android	lucide-react-native ^1.61.0, react-native-gesture-handler ~2.32.0, react-native-reanimated 4.5.1, react-native-svg 15.15.4, react-native-worklets 0.10.1

Scroll the table horizontally to review every column ↔

More animations

BaseDialog.tsx

import {
  baseActivationProps,
  useBaseReducedMotion,
  BaseThemeProvider,
  spring,
  timing,
  useBaseTheme,
  type BaseTheme,
} from '../base-theme';
import Animated, {
  ReduceMotion,
  cancelAnimation,
  Easing,
  useAnimatedStyle,
  useSharedValue,
  withSpring,
  withTiming,
} from 'react-native-reanimated';
import React, { useCallback, useEffect, useId, useRef, useState } from 'react';
import {
  KeyboardAvoidingView,
  AccessibilityInfo,
  Modal,
  Platform,
  ScrollView,
  StyleSheet,
  Text,
  View,
  useWindowDimensions,
  type StyleProp,
  type ViewStyle,
} from 'react-native';
import {
  Gesture,
  GestureDetector,
  GestureHandlerRootView,
} from 'react-native-gesture-handler';
import { scheduleOnRN } from 'react-native-worklets';
import X from 'lucide-react-native/icons/x';

export type BaseDialogProps = {
  visible?: boolean;
  defaultVisible?: boolean;
  onVisibleChange?: (visible: boolean) => void;
  title?: string;
  description?: string;
  children?: React.ReactNode;
  /** Supply secondary actions first and the primary action last. */
  footer?: React.ReactNode;
  dismissible?: boolean;
  showCloseButton?: boolean;
  closeLabel?: string;
  role?: 'dialog' | 'alertdialog';
  media?: React.ReactNode;
  theme?: BaseTheme;
  testID?: string;
};

const DIALOG_SPRING = { stiffness: 150, damping: 25, mass: 1 };

function fullWidthActions(children: React.ReactNode): React.ReactNode {
  return React.Children.map(children, (child) => {
    if (
      !React.isValidElement<{
        children?: React.ReactNode;
        style?: StyleProp<ViewStyle>;
      }>(child)
    )
      return child;
    if (child.type === React.Fragment) {
      return React.cloneElement(
        child,
        {},
        fullWidthActions(child.props.children),
      );
    }
    return React.cloneElement(child, {
      style: [child.props.style, { alignSelf: 'stretch', width: '100%' }],
    });
  });
}

export function BaseDialog({
  visible: controlled,
  defaultVisible = false,
  onVisibleChange,
  title,
  description,
  children,
  footer,
  dismissible = true,
  showCloseButton = true,
  closeLabel = 'Close',
  role = 'dialog',
  media,
  theme: override,
  testID,
}: BaseDialogProps) {
  const theme = useBaseTheme(override);
  const { colors } = theme;
  const reduced = useBaseReducedMotion();
  const { width, height } = useWindowDimensions();
  const titleId = useId();
  const descriptionId = useId();
  const heading = useRef<React.ElementRef<typeof Text>>(null);
  const [internal, setInternal] = useState(defaultVisible);
  const visible = controlled ?? internal;
  const [mounted, setMounted] = useState(visible);
  if (visible && !mounted) setMounted(true);
  const transition = useRef(0);
  const pose = useSharedValue(0);
  const opacity = useSharedValue(0);
  const shade = useSharedValue(0);
  const pressScale = useSharedValue(1);
  const pressSpring = spring(theme, 'press');
  const buttonScale = theme.motion.scales.press;
  const finishExit = useCallback((version: number) => {
    if (transition.current === version) setMounted(false);
  }, []);

  useEffect(() => {
    const lifecycle = transition;
    const version = ++lifecycle.current;
    if (!mounted) return;
    if (visible) {
      pose.set(
        reduced
          ? 1
          : withSpring(1, {
              ...DIALOG_SPRING,
              reduceMotion: ReduceMotion.Never,
            }),
      );
      opacity.set(withTiming(1, timing(theme, 'overlay', reduced)));
      shade.set(withTiming(1, timing(theme, 'overlay', reduced)));
    } else {
      const exitTiming = {
        duration: reduced ? 0 : 200,
        easing: Easing.bezier(...theme.motion.curves.soft),
      };
      opacity.set(
        withTiming(0, { ...exitTiming, reduceMotion: ReduceMotion.Never }),
      );
      shade.set(
        withTiming(0, { ...exitTiming, reduceMotion: ReduceMotion.Never }),
      );
      // The modal remains mounted until the physical spring reaches its hidden pose.
      if (reduced) {
        pose.set(0);
        finishExit(version);
      } else {
        pose.set(
          withSpring(
            0,
            { ...DIALOG_SPRING, reduceMotion: ReduceMotion.Never },
            (finished) => {
              if (finished) scheduleOnRN(finishExit, version);
            },
          ),
        );
      }
    }
    return () => {
      // Invalidate callbacks already queued on RN before a reopen or an unmount.
      lifecycle.current++;
      cancelAnimation(pose);
      cancelAnimation(opacity);
      cancelAnimation(shade);
    };
  }, [visible, mounted, reduced, theme, pose, opacity, shade, finishExit]);

  const close = () => {
    if (!visible || !dismissible) return;
    if (controlled === undefined) setInternal(false);
    onVisibleChange?.(false);
  };
  const outside = Gesture.Tap()
    .enabled(dismissible && role !== 'alertdialog' && visible)
    .onEnd((_event, success) => {
      if (success) scheduleOnRN(close);
    });
  const closeTap = Gesture.Tap()
    .enabled(dismissible && visible)
    .onBegin(() => {
      pressScale.set(
        reduced
          ? 1
          : withSpring(buttonScale, {
              ...pressSpring,
              reduceMotion: ReduceMotion.Never,
            }),
      );
    })
    .onFinalize(() => {
      pressScale.set(
        reduced
          ? 1
          : withSpring(1, { ...pressSpring, reduceMotion: ReduceMotion.Never }),
      );
    })
    .onEnd((_event, success) => {
      if (success) scheduleOnRN(close);
    });
  const panelStyle = useAnimatedStyle(() => ({
    opacity: opacity.get(),
    transform: [
      { perspective: 500 },
      { rotateX: `${reduced ? 0 : -20 * (1 - pose.get())}deg` },
      { scale: reduced ? 1 : 0.8 + 0.2 * pose.get() },
    ],
  }));
  const shadeStyle = useAnimatedStyle(() => ({ opacity: shade.get() }));
  const closeStyle = useAnimatedStyle(() => ({
    transform: [{ scale: pressScale.get() }],
  }));
  if (!mounted) return null;
  return (
    <Modal
      transparent
      visible
      animationType="none"
      onRequestClose={close}
      statusBarTranslucent
      navigationBarTranslucent
      onShow={() => {
        if (Platform.OS !== 'web' && heading.current) {
          AccessibilityInfo.sendAccessibilityEvent(heading.current, 'focus');
        }
      }}
    >
      <GestureHandlerRootView style={{ flex: 1 }}>
        <BaseThemeProvider theme={theme}>
          <GestureDetector gesture={outside}>
            <Animated.View
              accessible={false}
              importantForAccessibility="no"
              style={[
                StyleSheet.absoluteFill,
                { backgroundColor: colors.overlay },
                shadeStyle,
              ]}
            />
          </GestureDetector>
          <KeyboardAvoidingView
            pointerEvents="box-none"
            behavior={Platform.OS === 'ios' ? 'padding' : 'height'}
            style={{
              flex: 1,
              alignItems: 'center',
              justifyContent: 'center',
              paddingVertical: 16,
            }}
          >
            <Animated.View
              testID={testID}
              role={role}
              accessibilityViewIsModal
              aria-modal
              accessibilityLabel={title}
              aria-labelledby={title ? titleId : undefined}
              aria-describedby={description ? descriptionId : undefined}
              onAccessibilityEscape={close}
              {
                /* RN Web forwards DOM events rather than native event objects. */
                ...((Platform.OS === 'web'
                  ? {
                      onKeyDown: (event: React.KeyboardEvent) => {
                        if (event.key === 'Escape') {
                          event.stopPropagation();
                          close();
                        }
                      },
                    }
                  : {}) as object)
              }
              style={[
                {
                  width: Math.max(0, Math.min(width - 32, 512)),
                  maxHeight: Math.max(44, height - 32),
                  flexShrink: 1,
                  borderRadius: theme.radius.lg,
                  borderWidth: 1,
                  borderColor: colors.border,
                  backgroundColor: colors.background,
                  boxShadow: theme.shadow.lg,
                },
                panelStyle,
              ]}
            >
              <ScrollView
                showsVerticalScrollIndicator={false}
                keyboardShouldPersistTaps="handled"
                contentContainerStyle={{ padding: 24, gap: 16 }}
              >
                {media ? (
                  <View
                    style={{
                      width: 64,
                      height: 64,
                      borderRadius: theme.radius.md,
                      backgroundColor: colors.muted,
                      alignSelf: 'center',
                      justifyContent: 'center',
                      alignItems: 'center',
                    }}
                  >
                    {media}
                  </View>
                ) : null}
                {title || description ? (
                  <View
                    style={{
                      alignItems: 'center',
                      gap: 8,
                      paddingHorizontal:
                        showCloseButton && dismissible ? 16 : 0,
                    }}
                  >
                    {title ? (
                      <Text
                        ref={heading}
                        accessible
                        nativeID={titleId}
                        accessibilityRole="header"
                        style={{
                          fontFamily: theme.fonts.semibold,
                          fontSize: 18,
                          lineHeight: 24,
                          textAlign: 'center',
                          color: colors.foreground,
                        }}
                      >
                        {title}
                      </Text>
                    ) : null}
                    {description ? (
                      <Text
                        nativeID={descriptionId}
                        style={{
                          fontFamily: theme.fonts.regular,
                          fontSize: 14,
                          lineHeight: 20,
                          textAlign: 'center',
                          color: colors.mutedForeground,
                        }}
                      >
                        {description}
                      </Text>
                    ) : null}
                  </View>
                ) : null}
                {children}
                {footer ? (
                  <View
                    style={{
                      flexDirection: 'column-reverse',
                      alignItems: 'stretch',
                      gap: 8,
                    }}
                  >
                    {fullWidthActions(footer)}
                  </View>
                ) : null}
              </ScrollView>
              {showCloseButton && dismissible ? (
                <GestureDetector gesture={closeTap}>
                  <Animated.View
                    accessible
                    accessibilityRole="button"
                    accessibilityLabel={closeLabel}

                    {
                      /* RN Web forwards DOM events rather than native event objects. */
                      ...((Platform.OS === 'web'
                        ? {
                            tabIndex: 0,
                            onKeyDown: (event: React.KeyboardEvent) => {
                              if (event.key === 'Enter' || event.key === ' ') {
                                event.preventDefault();
                                close();
                              }
                            },
                          }
                        : {}) as object)
                    }
                    {
                      /* RN Web forwards DOM events rather than native event objects. */
                      ...(baseActivationProps(close, false) as object)
                    }
                    style={[
                      {
                        position: 'absolute',
                        top: Platform.OS === 'android' ? 0 : 2,
                        right: Platform.OS === 'android' ? 0 : 2,
                        width: Platform.OS === 'android' ? 48 : 44,
                        height: Platform.OS === 'android' ? 48 : 44,
                        alignItems: 'center',
                        justifyContent: 'center',
                        opacity: 0.7,
                        borderRadius: theme.radius.md,
                      },
                      closeStyle,
                    ]}
                  >
                    <X size={16} color={colors.foreground} />
                  </Animated.View>
                </GestureDetector>
              ) : null}
            </Animated.View>
          </KeyboardAvoidingView>
        </BaseThemeProvider>
      </GestureHandlerRootView>
    </Modal>
  );
}

LICENSE

MIT License

Copyright (c) 2026 Native Animation

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

nativeanimation.manifest.json

{
  "schemaVersion": 1,
  "id": "base-dialog",
  "family": "base",
  "license": "MIT",
  "kind": "component",
  "registryDependencies": [
    "base-theme"
  ],
  "dependencies": {
    "lucide-react-native": "^1.61.0",
    "react-native-gesture-handler": "~3.3.0",
    "react-native-reanimated": "4.7.1",
    "react-native-svg": "15.16.0",
    "react-native-worklets": "0.13.0"
  }
}