tessl/npm-react-native-screens

Native navigation primitives for React Native apps with native screen management and transitions.

—

Pending

Overview

Eval results

Files

Screen Components

Name: tessl/npm-react-native-screens
Author: tessl

Core components for creating and managing native screen hierarchies. These components provide the foundation for native screen management, transitions, and lifecycle handling.

Core Imports

import {
  Screen,
  ScreenContainer,
  ScreenStack,
  ScreenStackItem,
  FullWindowOverlay,
  ScreenFooter,
  ScreenContentWrapper
} from "react-native-screens";

Capabilities

Screen

The main screen component that wraps screen content and provides native screen functionality. Each Screen represents a single native screen with its own lifecycle and navigation properties.

/**
 * Main screen component providing native screen functionality
 */
function Screen(props: ScreenProps): JSX.Element;

interface ScreenProps {
  /** Screen active state (0 = inactive, 1 = active, or animated value) */
  active?: 0 | 1 | Animated.AnimatedInterpolation<number>;
  
  /** How the screen should be presented in the stack */
  stackPresentation?: StackPresentationTypes;
  
  /** Transition animation type */
  stackAnimation?: StackAnimationTypes;
  
  /** Whether dismiss gestures are enabled */
  gestureEnabled?: boolean;
  
  /** Status bar style for this screen */
  statusBarStyle?: 'inverted' | 'auto' | 'light' | 'dark';
  
  /** Whether the status bar is hidden */
  statusBarHidden?: boolean;
  
  /** Status bar animation when hidden/shown */
  statusBarAnimation?: 'none' | 'fade' | 'slide';
  
  /** Screen orientation preferences */
  screenOrientation?: ScreenOrientationTypes;
  
  /** Navigation bar color (Android) */
  navigationBarColor?: ColorValue;
  
  /** Whether navigation bar is hidden (Android) */
  navigationBarHidden?: boolean;
  
  /** Navigation bar style (Android) */
  navigationBarStyle?: 'light' | 'dark';
  
  /** Native stack presentation style */
  nativeBackButtonDismissalEnabled?: boolean;
  
  /** Whether swipe-to-dismiss is enabled */
  swipeDirection?: 'horizontal' | 'vertical';
  
  /** Full screen swipe area */
  fullScreenSwipeEnabled?: boolean;
  
  /** Custom gesture response distances */
  gestureResponseDistance?: GestureResponseDistanceType;
  
  /** Whether screen prevents auto-dismiss */
  preventNativeDismiss?: boolean;
  
  /** Callback when screen appears */
  onAppear?: (event: NativeSyntheticEvent<TargetedEvent>) => void;
  
  /** Callback when screen disappears */
  onDisappear?: (event: NativeSyntheticEvent<TargetedEvent>) => void;
  
  /** Callback when screen will appear */
  onWillAppear?: (event: NativeSyntheticEvent<TargetedEvent>) => void;
  
  /** Callback when screen will disappear */
  onWillDisappear?: (event: NativeSyntheticEvent<TargetedEvent>) => void;
  
  /** Callback when dismiss gesture starts */
  onDismissed?: (event: NativeSyntheticEvent<TargetedEvent>) => void;
  
  /** Callback for header height changes */
  onHeaderHeightChange?: (event: NativeSyntheticEvent<HeaderHeightChangeEventType>) => void;
  
  /** Callback for transition progress updates */
  onTransitionProgress?: (event: NativeSyntheticEvent<TransitionProgressEventType>) => void;
  
  /** Sheet presentation detents (iOS) */
  sheetAllowedDetents?: (number | 'medium' | 'large' | 'all')[] | number[];
  
  /** Sheet corner radius (iOS) */
  sheetCornerRadius?: number;
  
  /** Whether sheet grabs are visible (iOS) */
  sheetGrabberVisible?: boolean;
  
  /** Sheet largest undimmed detent identifier (iOS) */
  sheetLargestUndimmedDetentIdentifier?: number | 'medium' | 'large';
  
  /** Whether sheet expands on scroll (iOS) */
  sheetExpandsWhenScrolledToEdge?: boolean;
  
  /** Auto keyboard dismiss mode */
  autoKeyboardInsets?: boolean;
  
  /** Keyboard handling mode */
  keyboardHandlingEnabled?: boolean;
  
  /** Home indicator auto-hidden */
  homeIndicatorHidden?: boolean;
}

Usage Example:

import React from 'react';
import { Screen } from 'react-native-screens';
import { View, Text } from 'react-native';

function MyScreen() {
  return (
    <Screen
      active={1}
      stackPresentation="push"
      stackAnimation="slide_from_right"
      gestureEnabled={true}
      statusBarStyle="dark"
      onAppear={() => console.log('Screen appeared')}
      onWillDisappear={() => console.log('Screen will disappear')}
    >
      <View>
        <Text>Screen Content</Text>
      </View>
    </Screen>
  );
}

InnerScreen

Internal screen component that provides the core native screen functionality. This is primarily used by other screen components and navigation libraries internally, but can be accessed directly for advanced use cases.

/**
 * Internal screen component providing core native screen functionality
 */
const InnerScreen: React.ForwardRefExoticComponent<ScreenProps & React.RefAttributes<View>>;

Usage Example:

import React from 'react';
import { InnerScreen } from 'react-native-screens';
import { View, Text } from 'react-native';

function CustomScreenWrapper({ children, ...screenProps }) {
  return (
    <InnerScreen {...screenProps}>
      <View style={{ flex: 1 }}>
        {children}
      </View>
    </InnerScreen>
  );
}

Note: InnerScreen is typically used internally by other components and navigation libraries. For most use cases, use the Screen component instead.

ScreenContainer

Container component that manages multiple screen instances. Provides optimization for single-screen navigators and controls the overall screen management behavior.

/**
 * Container component for managing multiple screen instances
 */
function ScreenContainer(props: ScreenContainerProps): JSX.Element;

interface ScreenContainerProps extends ViewProps {
  /** Whether to use screens functionality */
  enabled?: boolean;
  
  /** Optimization for single-screen navigators */
  hasTwoStates?: boolean;
}

Usage Example:

import React from 'react';
import { ScreenContainer, Screen } from 'react-native-screens';

function NavigationContainer({ children }) {
  return (
    <ScreenContainer enabled={true} hasTwoStates={false}>
      {children}
    </ScreenContainer>
  );
}

ScreenStack

Stack container for managing screen transitions with native stack behavior. Provides platform-appropriate navigation stack functionality.

/**
 * Stack container for managing screen transitions
 */
function ScreenStack(props: ScreenStackProps): JSX.Element;

interface ScreenStackProps extends ViewProps, GestureProps {
  /** Custom gesture handling */
  children?: React.ReactNode;
}

interface GestureProps {
  /** Go back gesture types */
  goBackGesture?: GoBackGesture;
  
  /** Custom animated screen transitions */
  customAnimationOnSwipe?: boolean;
  
  /** Full screen swipe enabled */
  fullScreenSwipeEnabled?: boolean;
  
  /** Animated screen transition configuration */
  screenTransition?: AnimatedScreenTransition;
}

Usage Example:

import React from 'react';
import { ScreenStack, Screen } from 'react-native-screens';

function NavigationStack({ routes, activeRoute }) {
  return (
    <ScreenStack>
      {routes.map((route, index) => (
        <Screen
          key={route.key}
          active={index === activeRoute ? 1 : 0}
          stackPresentation="push"
        >
          {route.component}
        </Screen>
      ))}
    </ScreenStack>
  );
}

ScreenStackItem

Individual item within a screen stack that wraps screen content with stack-specific behavior and header configuration.

/**
 * Individual item within a screen stack with header configuration
 */
function ScreenStackItem(props: ScreenStackItemProps): JSX.Element;

interface ScreenStackItemProps extends Omit<ScreenProps, 'enabled' | 'isNativeStack' | 'hasLargeHeader'> {
  /** Unique identifier for the screen */
  screenId: string;
  
  /** Header configuration for this screen */
  headerConfig?: ScreenStackHeaderConfigProps;
  
  /** Custom content styling */
  contentStyle?: StyleProp<ViewStyle>;
  
  /** Footer component for form sheet presentations */
  unstable_sheetFooter?: () => React.ReactNode;
}

Usage Example:

import React from 'react';
import { ScreenStack, ScreenStackItem } from 'react-native-screens';

function StackNavigator() {
  return (
    <ScreenStack>
      <ScreenStackItem
        screenId="home"
        headerConfig={{
          title: "Home Screen",
          backgroundColor: "#007AFF",
          color: "white"
        }}
        contentStyle={{ backgroundColor: "#f5f5f5" }}
        stackPresentation="push"
        activityState={1}
      >
        {/* Screen content */}
      </ScreenStackItem>
    </ScreenStack>
  );
}

FullWindowOverlay

Component for creating full-window overlay screens that render above all other content, including system UI elements.

/**
 * Component for creating full-window overlay screens
 */
function FullWindowOverlay(props: ViewProps): JSX.Element;

Usage Example:

import React from 'react';
import { FullWindowOverlay } from 'react-native-screens';
import { View, Text } from 'react-native';

function OverlayScreen({ visible, children }) {
  if (!visible) return null;
  
  return (
    <FullWindowOverlay>
      <View style={{ flex: 1, backgroundColor: 'rgba(0,0,0,0.5)' }}>
        {children}
      </View>
    </FullWindowOverlay>
  );
}

ScreenFooter

Footer component specifically designed for use with formSheet presentation style on iOS.

/**
 * Footer component for use with formSheet presentation style
 */
function ScreenFooter(props: ViewProps): JSX.Element;

Usage Example:

import React from 'react';
import { Screen, ScreenFooter } from 'react-native-screens';
import { View, Text, Button } from 'react-native';

function FormSheetScreen() {
  return (
    <Screen stackPresentation="formSheet">
      <View style={{ flex: 1 }}>
        <Text>Form content</Text>
      </View>
      <ScreenFooter>
        <Button title="Save" onPress={() => {}} />
      </ScreenFooter>
    </Screen>
  );
}

ScreenContentWrapper

Wrapper component for screen content that provides additional layout and behavior management.

/**
 * Wrapper component for screen content
 */
function ScreenContentWrapper(props: ViewProps): JSX.Element;

Usage Example:

import React from 'react';
import { Screen, ScreenContentWrapper } from 'react-native-screens';
import { ScrollView } from 'react-native';

function ScrollableScreen({ children }) {
  return (
    <Screen>
      <ScreenContentWrapper>
        <ScrollView>
          {children}
        </ScrollView>
      </ScreenContentWrapper>
    </Screen>
  );
}

SearchBar

Native search bar component for iOS and Android that integrates with the navigation header or can be used standalone.

/**
 * Native search bar component with platform-specific styling
 */
function SearchBar(props: SearchBarProps): JSX.Element;

interface SearchBarProps {
  /** Reference for imperative control */
  ref?: React.RefObject<SearchBarCommands>;
  
  /** Auto-capitalization behavior */
  autoCapitalize?: 'none' | 'words' | 'sentences' | 'characters';
  
  /** Automatically focus on mount (Android) */
  autoFocus?: boolean;
  
  /** Search field background color */
  barTintColor?: ColorValue;
  
  /** Cursor and cancel button color (iOS) */
  tintColor?: ColorValue;
  
  /** Custom cancel button text (iOS, deprecated) */
  cancelButtonText?: string;
  
  /** Whether back button closes search (Android) */
  disableBackButtonOverride?: boolean;
  
  /** Hide navigation bar during search (iOS) */
  hideNavigationBar?: boolean;
  
  /** Hide search bar when scrolling (iOS) */
  hideWhenScrolling?: boolean;
  
  /** Input type for keyboard (Android) */
  inputType?: 'text' | 'phone' | 'number' | 'email';
  
  /** Whether to obscure background content */
  obscureBackground?: boolean;
  
  /** Search bar placement position (iOS) */
  placement?: SearchBarPlacement;
  
  /** Allow toolbar integration (iOS) */
  allowToolbarIntegration?: boolean;
  
  /** Placeholder text */
  placeholder?: string;
  
  /** Search field text color */
  textColor?: ColorValue;
  
  /** Search hint text color (Android) */
  hintTextColor?: ColorValue;
  
  /** Header icon color (Android) */
  headerIconColor?: ColorValue;
  
  /** Show search hint icon when focused (Android) */
  shouldShowHintSearchIcon?: boolean;
  
  /** Callback when search loses focus */
  onBlur?: (event: NativeSyntheticEvent<TargetedEvent>) => void;
  
  /** Callback when cancel button pressed (iOS) */
  onCancelButtonPress?: (event: NativeSyntheticEvent<TargetedEvent>) => void;
  
  /** Callback when text changes */
  onChangeText?: (event: NativeSyntheticEvent<TextInputFocusEventData>) => void;
  
  /** Callback when search closes (Android) */
  onClose?: () => void;
  
  /** Callback when search gains focus */
  onFocus?: (event: NativeSyntheticEvent<TargetedEvent>) => void;
  
  /** Callback when search opens (Android) */
  onOpen?: () => void;
  
  /** Callback when search button pressed */
  onSearchButtonPress?: (event: NativeSyntheticEvent<TextInputFocusEventData>) => void;
}

interface SearchBarCommands {
  /** Focus the search bar */
  focus(): void;
  
  /** Remove focus from search bar */
  blur(): void;
  
  /** Clear search text */
  clearText(): void;
  
  /** Toggle cancel button visibility (iOS) */
  toggleCancelButton(show: boolean): void;
  
  /** Set search text programmatically */
  setText(text: string): void;
  
  /** Cancel search operation */
  cancelSearch(): void;
}

type SearchBarPlacement = 
  | 'automatic'        // Automatic placement
  | 'inline'          // Inline (deprecated, use integrated)
  | 'stacked'         // Below other content
  | 'integrated'      // Trailing edge (iOS 16+)
  | 'integratedButton' // Always button form (iOS 16+)
  | 'integratedCentered'; // Centered on iPad (iOS 16+)

Usage Example:

import React, { useRef } from 'react';
import { SearchBar, SearchBarCommands } from 'react-native-screens';

function SearchScreen() {
  const searchRef = useRef<SearchBarCommands>(null);
  
  const handleSearchPress = () => {
    searchRef.current?.focus();
  };
  
  const handleClearPress = () => {
    searchRef.current?.clearText();
  };
  
  return (
    <SearchBar
      ref={searchRef}
      placeholder="Search items..."
      placement="stacked"
      hideWhenScrolling={false}
      autoCapitalize="none"
      onChangeText={(event) => {
        console.log('Search text:', event.nativeEvent.text);
      }}
      onSearchButtonPress={(event) => {
        console.log('Search submitted:', event.nativeEvent.text);
      }}
      onFocus={() => console.log('Search focused')}
      onBlur={() => console.log('Search blurred')}
    />
  );
}

Platform-Specific Usage:

import { Platform } from 'react-native';
import { SearchBar, isSearchBarAvailableForCurrentPlatform } from 'react-native-screens';

function ConditionalSearchBar() {
  if (!isSearchBarAvailableForCurrentPlatform) {
    return <TextInput placeholder="Search..." />; // Fallback
  }
  
  return (
    <SearchBar
      placeholder="Search..."
      // iOS-specific props
      placement={Platform.OS === 'ios' ? 'integrated' : undefined}
      hideNavigationBar={Platform.OS === 'ios'}
      tintColor={Platform.OS === 'ios' ? '#007AFF' : undefined}
      
      // Android-specific props
      inputType={Platform.OS === 'android' ? 'text' : undefined}
      disableBackButtonOverride={Platform.OS === 'android' ? false : undefined}
      headerIconColor={Platform.OS === 'android' ? '#666' : undefined}
    />
  );
}

Types

Stack Presentation Types

type StackPresentationTypes = 
  | 'push'                      // Standard push navigation
  | 'modal'                     // Modal presentation 
  | 'transparentModal'          // Transparent modal
  | 'containedModal'           // Contained modal (iOS)
  | 'containedTransparentModal' // Contained transparent modal (iOS)
  | 'fullScreenModal'          // Full screen modal
  | 'formSheet'                // Form sheet (iOS)
  | 'pageSheet';               // Page sheet (iOS)

Stack Animation Types

type StackAnimationTypes = 
  | 'default'           // Platform default animation
  | 'fade'              // Fade in/out
  | 'fade_from_bottom'  // Fade from bottom
  | 'flip'              // Flip animation
  | 'none'              // No animation
  | 'simple_push'       // Simple push
  | 'slide_from_bottom' // Slide from bottom
  | 'slide_from_right'  // Slide from right
  | 'slide_from_left'   // Slide from left
  | 'ios_from_right'    // iOS-style from right
  | 'ios_from_left';    // iOS-style from left

Screen Orientation Types

type ScreenOrientationTypes = 
  | 'default'       // Use app default
  | 'all'           // All orientations
  | 'portrait'      // Portrait orientations
  | 'portrait_up'   // Portrait up only
  | 'portrait_down' // Portrait down only  
  | 'landscape'     // Landscape orientations
  | 'landscape_left' // Landscape left
  | 'landscape_right'; // Landscape right

Event Types

interface HeaderHeightChangeEventType {
  headerHeight: number;
}

interface TransitionProgressEventType {
  progress: number;
  closing: number;
  goingForward: number;
}

interface GestureResponseDistanceType {
  start?: number;
  end?: number;
  top?: number;
  bottom?: number;
}

Gesture Types

type GoBackGesture = 
  | 'swipeRight'
  | 'swipeLeft' 
  | 'swipeUp'
  | 'swipeDown'
  | 'verticalSwipe'
  | 'horizontalSwipe'
  | 'twoDimensionalSwipe';

interface AnimatedScreenTransition {
  topScreenFrame?: {
    x: number;
    y: number;
    width: number;
    height: number;
  };
  belowTopScreenFrame?: {
    x: number;
    y: number;
    width: number;
    height: number;
  };
}

Platform Considerations

iOS Specific Features

Form sheet and page sheet presentations
Large title support
Sheet detents and corner radius
Home indicator control
Visual effect backgrounds

Android Specific Features

Navigation bar styling
Edge-to-edge support
Hardware back button integration
Fragment lifecycle management
Material design transitions

Performance Optimization

Use hasTwoStates={true} for simple navigators
Enable gestureEnabled={false} for non-dismissible screens
Implement onTransitionProgress for custom animations
Use appropriate stackAnimation for smooth transitions

Install with Tessl CLI

npx tessl i tessl/npm-react-native-screens

docs

core-functions.md

experimental-features.md

tessl/npm-react-native-screens