ScreenContainer

ScreenContainer provides a consistent wrapper for screens with pre-calculated safe area padding. It uses initialWindowMetrics for immediate rendering without layout shifts.

Preview

Light Dark OLED

Global

Safe Area Top

Screen Content

Safe Area Bottom

---

Usage

import { ScreenContainer } from '@synchronicity/react-native';

function MyScreen() {
  return (
    <ScreenContainer edges={['top', 'bottom']}>
      <View style={styles.content}>
        {/* Screen content */}
      </View>
    </ScreenContainer>
  );
}

---

Edge Options

Control which edges receive safe area padding:

Light Dark OLED

Global

Top only (default)

All edges

Bottom only

Edges	Usage
['top']	Default, most screens
['top', 'bottom']	Screens with bottom content
['left', 'right']	Landscape modes
['top', 'bottom', 'left', 'right']	Full safe area

---

How It Works

ScreenContainer uses a two-phase approach for safe area handling:

1. Initial Render: Uses initialWindowMetrics for immediate padding
2. Live Update: Switches to useSafeAreaInsets() once measured

This prevents the “jump” that occurs when safe area measurements arrive asynchronously.

// Use initial metrics for immediate rendering
const getInitialTopInset = () => {
  return initialWindowMetrics?.insets.top ?? 0;
};

// Use live insets if available, otherwise fall back to initial metrics
const topInset = insets.top > 0 ? insets.top : getInitialTopInset();

---

API Reference

Props

Prop	Type	Default	Description
children	ReactNode	-	Screen content
style	ViewStyle	-	Additional container styles
edges	('top' | 'bottom' | 'left' | 'right')[]	['top']	Edges to apply safe area padding

Tokens Used

// Background
theme.colors.background  // Screen background color

---

Usage Guidelines

Do

• Use ScreenContainer as the root of every screen
• Specify only necessary edges to avoid wasted space
• Combine with edges={['top']} for most scrollable content

Don’t

• Nest ScreenContainer inside ScreenContainer
• Apply manual padding for safe areas (let the component handle it)
• Use for modal content (modals have their own safe area handling)

Tip

For screens with a TabBar, use edges={['top']} since the TabBar handles bottom safe area padding.

---

Complete Example

import { ScreenContainer } from '@synchronicity/react-native';
import { ScrollView, View } from 'react-native';

function ReadingDetailScreen({ reading }) {
  return (
    <ScreenContainer edges={['top']}>
      <ScrollView contentContainerStyle={styles.scrollContent}>
        <HexagramVisual
          hexagramNumber={reading.hexagramNumber}
          size="large"
        />
        <Text style={styles.title}>{reading.name}</Text>
        <Text style={styles.description}>{reading.judgment}</Text>
      </ScrollView>
    </ScreenContainer>
  );
}