tessl/npm-react-navigation--elements
UI Components for React Navigation providing headers, buttons, and layout components with cross-platform support
—
Pending
layout-components.mddocs/
Layout Components
Core layout components for structuring navigation screens, managing safe areas, and providing themed backgrounds with proper context integration.
Capabilities
Screen
Screen wrapper component that provides navigation context, header integration, and proper layout management for navigation screens.
/**
* Screen wrapper component with navigation context and header integration
* @param props - Screen configuration and content
* @returns React element representing a complete navigation screen
*/
function Screen(props: {
/** Whether screen is currently focused (required) */
focused: boolean;
/** Whether screen is presented as modal */
modal?: boolean;
/** Navigation object from React Navigation (required) */
navigation: NavigationProp<ParamListBase>;
/** Route object from React Navigation (required) */
route: RouteProp<ParamListBase>;
/** Header component to render (required) */
header: React.ReactNode;
/** Whether to show the header */
headerShown?: boolean;
/** Custom status bar height override */
headerStatusBarHeight?: number;
/** Whether header should be transparent */
headerTransparent?: boolean;
/** Custom screen container styling */
style?: Animated.WithAnimatedValue<StyleProp<ViewStyle>>;
/** Screen content (required) */
children: React.ReactNode;
}): React.ReactElement;Usage Examples:
import { Screen, Header } from "@react-navigation/elements";
// Basic screen setup
function MyScreen({ navigation, route }) {
return (
<Screen
focused={true}
navigation={navigation}
route={route}
header={<Header title="My Screen" />}
>
<View style={{ flex: 1, padding: 20 }}>
<Text>Screen content goes here</Text>
</View>
</Screen>
);
}
// Modal screen
function ModalScreen({ navigation, route }) {
return (
<Screen
focused={true}
modal={true}
navigation={navigation}
route={route}
header={
<Header
title="Modal"
headerLeft={() => (
<HeaderButton onPress={() => navigation.goBack()}>
<Text>Cancel</Text>
</HeaderButton>
)}
/>
}
>
<Text>Modal content</Text>
</Screen>
);
}
// Screen without header
function FullScreenView({ navigation, route }) {
return (
<Screen
focused={true}
navigation={navigation}
route={route}
header={<Header title="Hidden" />}
headerShown={false}
>
<Text>Full screen content</Text>
</Screen>
);
}
// Transparent header screen
function TransparentHeaderScreen({ navigation, route }) {
return (
<Screen
focused={true}
navigation={navigation}
route={route}
headerTransparent={true}
header={
<Header
title="Transparent"
headerTransparent={true}
headerBackground={() => (
<View style={{ backgroundColor: 'rgba(255,255,255,0.9)' }} />
)}
/>
}
>
<ScrollView>
<Text>Content scrolls under transparent header</Text>
</ScrollView>
</Screen>
);
}Background
Themed background container component that automatically applies navigation theme colors and provides flexible layout.
/**
* Themed background container with automatic theme color application
* @param props - Background configuration and content
* @returns React element representing a themed background container
*/
function Background(props: {
/** Custom background styling */
style?: Animated.WithAnimatedValue<StyleProp<ViewStyle>>;
/** Background content (required) */
children: React.ReactNode;
} & Omit<ViewProps, 'style'>): React.ReactElement;Usage Examples:
import { Background } from "@react-navigation/elements";
// Basic themed background
<Background>
<Text>Content with automatic theme background</Text>
</Background>
// Custom styled background
<Background
style={{
flex: 1,
padding: 20,
backgroundColor: '#f5f5f5'
}}
>
<ScrollView>
<Text>Scrollable content</Text>
</ScrollView>
</Background>
// Background with additional props
<Background
style={{ flex: 1 }}
accessibilityRole="main"
>
<View>
<Text>Accessible main content area</Text>
</View>
</Background>SafeAreaProviderCompat
Compatibility wrapper for SafeAreaProvider that handles SSR, test environments, and prevents double-wrapping of safe area contexts.
/**
* Safe area provider compatibility wrapper
* @param props - Provider configuration and content
* @returns React element providing safe area context
*/
function SafeAreaProviderCompat(props: {
/** Content to wrap with safe area context (required) */
children: React.ReactNode;
/** Custom container styling */
style?: StyleProp<ViewStyle>;
}): React.ReactElement;
/** Initial metrics for safe area calculations */
SafeAreaProviderCompat.initialMetrics: {
frame: { x: number; y: number; width: number; height: number };
insets: { top: number; left: number; right: number; bottom: number };
} | null;Usage Examples:
import { SafeAreaProviderCompat } from "@react-navigation/elements";
// Basic safe area setup
function App() {
return (
<SafeAreaProviderCompat>
<NavigationContainer>
<Stack.Navigator>
<Stack.Screen name="Home" component={HomeScreen} />
</Stack.Navigator>
</NavigationContainer>
</SafeAreaProviderCompat>
);
}
// With custom styling
<SafeAreaProviderCompat
style={{ backgroundColor: '#ffffff' }}
>
<MyAppContent />
</SafeAreaProviderCompat>
// Accessing initial metrics
function MyComponent() {
const initialMetrics = SafeAreaProviderCompat.initialMetrics;
if (initialMetrics) {
console.log('Safe area insets:', initialMetrics.insets);
}
return <View>...</View>;
}Layout Patterns
Standard Screen Layout
function StandardScreen({ navigation, route }) {
return (
<SafeAreaProviderCompat>
<Screen
focused={true}
navigation={navigation}
route={route}
header={<Header title="Standard Layout" />}
>
<Background style={{ flex: 1 }}>
<ScrollView style={{ flex: 1, padding: 16 }}>
<Text>Your content here</Text>
</ScrollView>
</Background>
</Screen>
</SafeAreaProviderCompat>
);
}Modal Layout
function ModalLayout({ navigation, route }) {
return (
<Screen
focused={true}
modal={true}
navigation={navigation}
route={route}
header={
<Header
title="Modal Title"
headerLeft={() => (
<HeaderButton onPress={() => navigation.goBack()}>
<Text>Cancel</Text>
</HeaderButton>
)}
/>
}
>
<Background>
<View style={{ padding: 20 }}>
<Text>Modal content</Text>
</View>
</Background>
</Screen>
);
}Full Screen Layout
function FullScreenLayout({ navigation, route }) {
return (
<Screen
focused={true}
navigation={navigation}
route={route}
header={<Header title="Hidden" />}
headerShown={false}
>
<View style={{ flex: 1 }}>
<Text>Full screen content without header</Text>
</View>
</Screen>
);
}Context Integration
The Screen component automatically provides several React contexts:
- HeaderHeightContext: Provides the current header height
- HeaderShownContext: Indicates whether header is currently shown
- HeaderBackContext: Provides back button state and navigation info
- Navigation Context: Standard React Navigation context integration
import { useHeaderHeight } from "@react-navigation/elements";
function ContentWithHeaderInfo() {
const headerHeight = useHeaderHeight();
return (
<View style={{ paddingTop: headerHeight }}>
<Text>Content positioned below header</Text>
</View>
);
}Platform Considerations
iOS
- Safe Area: Automatic handling of notch, Dynamic Island, and home indicator
- Status Bar: Proper status bar style coordination with header
- Modal Presentation: Native modal presentation styles
Android
- System Bars: Handles system navigation bar and status bar
- Edge-to-Edge: Support for edge-to-edge display modes
- Material Design: Follows Material Design layout principles
Web
- Responsive: Adapts to browser viewport changes
- Accessibility: Proper semantic structure and ARIA landmarks
- Performance: Optimized for web rendering and layout shifts
Install with Tessl CLI
npx tessl i tessl/npm-react-navigation--elements