or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

header-components.mdhooks-contexts.mdindex.mdinteractive-components.mdlayout-components.mdutility-components.mdutility-functions.md
tile.json

tessl/npm-react-navigation--elements

UI Components for React Navigation providing headers, buttons, and layout components with cross-platform support

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@react-navigation/elements@2.6.x

To install, run

npx @tessl/cli install tessl/npm-react-navigation--elements@2.6.0

index.mddocs/

React Navigation Elements

React Navigation Elements provides a comprehensive collection of UI components specifically designed for React Navigation applications. It offers reusable components for navigation interfaces including headers, buttons, layout components, and utility functions, all with cross-platform support for iOS, Android, and Web.

Package Information

  • Package Name: @react-navigation/elements
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @react-navigation/elements

Core Imports

import {
  Header,
  Button,
  Screen,
  HeaderButton,
  HeaderBackButton,
  useHeaderHeight,
  useFrameSize,
  FrameSizeProvider,
} from "@react-navigation/elements";

For CommonJS:

const {
  Header,
  Button,
  Screen,
  HeaderButton,
  HeaderBackButton,
  useHeaderHeight,
  useFrameSize,
  FrameSizeProvider,
} = require("@react-navigation/elements");

Basic Usage

import React from "react";
import {
  Header,
  Screen,
  HeaderBackButton,
  HeaderTitle,
  Button,
  useHeaderHeight,
} from "@react-navigation/elements";

// Basic header setup
function MyScreen({ navigation, route }) {
  const headerHeight = useHeaderHeight();
  
  return (
    <Screen
      focused={true}
      navigation={navigation}
      route={route}
      header={
        <Header
          title="My Screen"
          back={{ title: "Back" }}
          headerLeft={(props) => (
            <HeaderBackButton
              {...props}
              onPress={() => navigation.goBack()}
            />
          )}
        />
      }
    >
      <Button
        variant="filled"
        onPress={() => console.log("Button pressed")}
      >
        Press me
      </Button>
    </Screen>
  );
}

Architecture

React Navigation Elements is built around several key architectural patterns:

  • Header System: Complete header component with customizable left/right actions, titles, and backgrounds
  • Screen Management: Screen wrapper component that provides navigation context and header integration
  • Cross-Platform Components: Platform-specific optimizations for iOS, Android, and Web
  • Context Providers: React contexts for sharing header state, dimensions, and navigation information
  • Theme Integration: Automatic theme color application across all components
  • Performance Optimization: Components like ResourceSavingView for efficient rendering

Capabilities

Header Components

Complete header system with customizable navigation bars, back buttons, titles, and action buttons. Includes platform-specific styling and behavior.

function Header(props: {
  title: string;
  back?: { title: string | undefined; href: string | undefined };
  modal?: boolean;
  layout?: Layout;
} & HeaderOptions): React.ReactElement;

function HeaderBackButton(props: HeaderBackButtonProps): React.ReactElement;

function HeaderButton(props: HeaderButtonProps): React.ReactElement;

function HeaderTitle(props: HeaderTitleProps): React.ReactElement;

Header Components

Layout Components

Core layout components for structuring navigation screens, managing safe areas, and providing themed backgrounds.

function Screen(props: {
  focused: boolean;
  modal?: boolean;
  navigation: NavigationProp<ParamListBase>;
  route: RouteProp<ParamListBase>;
  header: React.ReactNode;
  headerShown?: boolean;
  headerStatusBarHeight?: number;
  headerTransparent?: boolean;
  style?: Animated.WithAnimatedValue<StyleProp<ViewStyle>>;
  children: React.ReactNode;
}): React.ReactElement;

function Background(props: {
  style?: Animated.WithAnimatedValue<StyleProp<ViewStyle>>;
  children: React.ReactNode;
}): React.ReactElement;

function SafeAreaProviderCompat(props: {
  children: React.ReactNode;
  style?: StyleProp<ViewStyle>;
}): React.ReactElement;

Layout Components

Interactive Components

Button and pressable components with navigation integration, platform-specific press effects, and theme support.

// Basic button with onPress handler
function Button(props: ButtonBaseProps): React.ReactElement;

// Navigation button with screen/action routing
function Button<ParamList extends ReactNavigation.RootParamList>(
  props: ButtonLinkProps<ParamList>
): React.ReactElement;

const PlatformPressable: React.ForwardRefExoticComponent<{
  href?: string;
  pressColor?: string;
  pressOpacity?: number;
  hoverEffect?: HoverEffectProps;
  style?: Animated.WithAnimatedValue<StyleProp<ViewStyle>>;
  onPress?: (e: React.MouseEvent | GestureResponderEvent) => void;
  children: React.ReactNode;
} & Omit<PressableProps, 'style' | 'onPress'>>;

Interactive Components

Utility Components

Text, label, icon, and performance optimization components for common navigation UI patterns.

function Text(props: TextProps): React.ReactElement;

function Label(props: {
  tintColor?: string;
  children?: string;
  style?: StyleProp<TextStyle>;
} & Omit<TextProps, 'style'>): React.ReactElement;

function MissingIcon(props: {
  color?: string;
  size?: number;
  style?: StyleProp<TextStyle>;
}): React.ReactElement;

function ResourceSavingView(props: {
  visible: boolean;
  children: React.ReactNode;
  style?: StyleProp<ViewStyle>;
}): React.ReactElement;

Utility Components

Hooks and Contexts

React hooks and context providers for accessing navigation state, dimensions, and header information.

function useHeaderHeight(): number;

function useFrameSize<T>(
  selector: (frame: Frame) => T,
  throttle?: boolean
): T;

function FrameSizeProvider(props: {
  initialFrame: Frame;
  children: React.ReactNode;
  style?: StyleProp<ViewStyle>;
}): React.ReactElement;

const HeaderBackContext: React.Context<{ title: string | undefined; href: string | undefined } | undefined>;
const HeaderHeightContext: React.Context<number | undefined>;
const HeaderShownContext: React.Context<boolean>;

Hooks and Contexts

Utility Functions

Helper functions for calculating dimensions, resolving titles and labels, and other common navigation tasks.

function getDefaultHeaderHeight(
  layout: Layout,
  modalPresentation: boolean,
  topInset: number
): number;

function getDefaultSidebarWidth({ width }: { width: number }): number;

function getHeaderTitle(
  options: { title?: string; headerTitle?: HeaderOptions['headerTitle'] },
  fallback: string
): string;

function getLabel(
  options: { label?: string; title?: string },
  fallback: string
): string;

Utility Functions

Types

Core type definitions used throughout the library:

interface Layout {
  width: number;
  height: number;
}

type HeaderBackButtonDisplayMode = 'default' | 'generic' | 'minimal';

interface HeaderOptions {
  headerTitle?: string | ((props: HeaderTitleProps) => React.ReactNode);
  headerTitleAlign?: 'left' | 'center';
  headerTitleStyle?: Animated.WithAnimatedValue<StyleProp<TextStyle>>;
  headerTitleContainerStyle?: Animated.WithAnimatedValue<StyleProp<ViewStyle>>;
  headerTitleAllowFontScaling?: boolean;
  headerSearchBarOptions?: HeaderSearchBarOptions;
  headerLeft?: (props: HeaderBackButtonProps & { canGoBack?: boolean }) => React.ReactNode;
  headerBackButtonDisplayMode?: HeaderBackButtonDisplayMode;
  headerBackTitleStyle?: StyleProp<{ fontFamily?: string; fontSize?: number }>;
  headerLeftContainerStyle?: Animated.WithAnimatedValue<StyleProp<ViewStyle>>;
  headerRight?: (props: { tintColor?: string; pressColor?: string; pressOpacity?: number; canGoBack: boolean }) => React.ReactNode;
  headerRightContainerStyle?: Animated.WithAnimatedValue<StyleProp<ViewStyle>>;
  headerPressColor?: string;
  headerPressOpacity?: number;
  headerTintColor?: string;
  headerBackground?: (props: { style: Animated.WithAnimatedValue<StyleProp<ViewStyle>> }) => React.ReactNode;
  headerBackgroundContainerStyle?: Animated.WithAnimatedValue<StyleProp<ViewStyle>>;
  headerTransparent?: boolean;
  headerStyle?: Animated.WithAnimatedValue<StyleProp<ViewStyle>>;
  headerShadowVisible?: boolean;
  headerStatusBarHeight?: number;
}

interface HeaderTitleProps {
  children: string;
  allowFontScaling?: boolean;
  tintColor?: string;
  onLayout?: (e: LayoutChangeEvent) => void;
  style?: Animated.WithAnimatedValue<StyleProp<TextStyle>>;
}

interface HeaderButtonProps {
  onPress?: () => void;
  href?: string;
  disabled?: boolean;
  accessibilityLabel?: string;
  testID?: string;
  tintColor?: string;
  pressColor?: string;
  pressOpacity?: number;
  style?: StyleProp<ViewStyle>;
  children: React.ReactNode;
}

interface HeaderBackButtonProps extends Omit<HeaderButtonProps, 'children'> {
  backImage?: (props: { tintColor: string }) => React.ReactNode;
  label?: string;
  truncatedLabel?: string;
  displayMode?: HeaderBackButtonDisplayMode;
  labelStyle?: Animated.WithAnimatedValue<StyleProp<TextStyle>>;
  allowFontScaling?: boolean;
  onLabelLayout?: (e: LayoutChangeEvent) => void;
  screenLayout?: Layout;
  titleLayout?: Layout;
}

interface HeaderSearchBarOptions {
  ref?: React.Ref<HeaderSearchBarRef>;
  autoCapitalize?: 'none' | 'words' | 'sentences' | 'characters';
  autoFocus?: boolean;
  cancelButtonText?: string;
  inputType?: 'text' | 'phone' | 'number' | 'email';
  enterKeyHint?: TextInputProps['enterKeyHint'];
  onBlur?: TextInputProps['onBlur'];
  onChangeText?: TextInputProps['onChange'];
  onSubmitEditing?: TextInputProps['onSubmitEditing'];
  onOpen?: () => void;
  onClose?: () => void;
  onFocus?: TextInputProps['onFocus'];
  placeholder?: string;
}

interface HeaderSearchBarRef {
  focus: () => void;
  blur: () => void;
  setText: (text: string) => void;
  clearText: () => void;
  cancelSearch: () => void;
}

interface Layout {
  width: number;
  height: number;
}

// Frame is an alias for Layout used in frame sizing functions
type Frame = Layout;

type PlatformPressableProps = {
  href?: string;
  pressColor?: string;
  pressOpacity?: number;
  hoverEffect?: HoverEffectProps;
  style?: Animated.WithAnimatedValue<StyleProp<ViewStyle>>;
  onPress?: (e: React.MouseEvent | GestureResponderEvent) => void;
  children: React.ReactNode;
} & Omit<PressableProps, 'style' | 'onPress'>;

type ButtonBaseProps = Omit<PlatformPressableProps, 'children'> & {
  variant?: 'plain' | 'tinted' | 'filled';
  color?: string;
  children: string | string[];
};

type ButtonLinkProps<ParamList extends ReactNavigation.RootParamList> = {
  screen: keyof ParamList;
  params?: ParamList[keyof ParamList];
  action?: NavigationAction;
  href?: string;
} & Omit<ButtonBaseProps, 'onPress'>;

interface HoverEffectProps {
  color?: string;
  hoverOpacity?: number;
  activeOpacity?: number;
}

Constants

const Assets: (string | number)[];

The Assets array contains image resources for common navigation icons:

  • backIcon - Navigation back arrow icon
  • backIconMask - Back icon mask for iOS transitions
  • searchIcon - Search magnifying glass icon
  • closeIcon - Close/dismiss X icon
  • clearIcon - Clear/reset icon