0
# Utility Components
1

2
Text, label, icon, and performance optimization components for common navigation UI patterns with automatic theme integration.
3

4
## Capabilities
5

6
### Text
7

8
Themed text component that automatically applies navigation theme colors and fonts with support for all React Native Text properties.
9

10
```typescript { .api }
11
/**
12
 * Themed text component with automatic theme color application
13
 * @param props - Text properties from React Native
14
 * @returns React element representing themed text
15
 */
16
function Text(props: TextProps): React.ReactElement;
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import { Text } from "@react-navigation/elements";
23

24
// Basic themed text
25
<Text>This text uses the navigation theme colors</Text>
26

27
// Styled text
28
<Text style={{ fontSize: 18, fontWeight: 'bold' }}>
29
  Bold themed text
30
</Text>
31

32
// Text with all React Native Text props
33
<Text 
34
  numberOfLines={2}
35
  ellipsizeMode="tail"
36
  onPress={() => console.log('Text pressed')}
37
  style={{ color: '#666' }}
38
>
39
  This is a long text that will be truncated after two lines and has custom styling
40
</Text>
41

42
// Accessibility text
43
<Text 
44
  accessibilityRole="header"
45
  accessibilityLevel={1}
46
  style={{ fontSize: 24, marginBottom: 16 }}
47
>
48
  Section Header
49
</Text>
50
```
51

52
### Label
53

54
Centered text component with tint color support, designed for consistent labeling across navigation interfaces.
55

56
```typescript { .api }
57
/**
58
 * Centered text component with tint color support for labels
59
 * @param props - Label configuration and styling
60
 * @returns React element representing a centered label
61
 */
62
function Label(props: {
63
  /** Label text color override */
64
  tintColor?: string;
65
  /** Label text content */
66
  children?: string;
67
  /** Custom label styling */
68
  style?: StyleProp<TextStyle>;
69
} & Omit<TextProps, 'style'>): React.ReactElement;
70
```
71

72
**Usage Examples:**
73

74
```typescript
75
import { Label } from "@react-navigation/elements";
76

77
// Basic label
78
<Label>Settings</Label>
79

80
// Colored label
81
<Label tintColor="#007AFF">
82
  Primary Action
83
</Label>
84

85
// Styled label
86
<Label 
87
  tintColor="#FF3B30"
88
  style={{ fontSize: 16, fontWeight: '600' }}
89
>
90
  Delete Item
91
</Label>
92

93
// Label with additional props
94
<Label 
95
  tintColor="#34C759"
96
  numberOfLines={1}
97
  ellipsizeMode="middle"
98
>
99
  Very Long Label That Gets Truncated
100
</Label>
101
```
102

103
### MissingIcon
104

105
Fallback icon component that displays a standardized placeholder when actual icons are missing or unavailable.
106

107
```typescript { .api }
108
/**
109
 * Fallback icon component for when actual icons are missing
110
 * @param props - Icon configuration and styling
111
 * @returns React element representing a fallback icon (⏷)
112
 */
113
function MissingIcon(props: {
114
  /** Icon color */
115
  color?: string;
116
  /** Icon size in points/pixels */
117
  size?: number;
118
  /** Custom icon styling */
119
  style?: StyleProp<TextStyle>;
120
}): React.ReactElement;
121
```
122

123
**Usage Examples:**
124

125
```typescript
126
import { MissingIcon } from "@react-navigation/elements";
127

128
// Basic missing icon placeholder
129
<MissingIcon />
130

131
// Colored and sized missing icon
132
<MissingIcon 
133
  color="#666666"
134
  size={24}
135
/>
136

137
// Styled missing icon
138
<MissingIcon 
139
  color="#FF3B30"
140
  size={20}
141
  style={{ marginRight: 8 }}
142
/>
143

144
// In a conditional icon setup
145
function IconDisplay({ iconName, color, size }) {
146
  return (
147
    <View>
148
      {iconName ? (
149
        <Icon name={iconName} color={color} size={size} />
150
      ) : (
151
        <MissingIcon color={color} size={size} />
152
      )}
153
    </View>
154
  );
155
}
156
```
157

158
### ResourceSavingView
159

160
Performance optimization component that efficiently shows/hides content across platforms to reduce memory usage and improve rendering performance.
161

162
```typescript { .api }
163
/**
164
 * Performance optimization component for efficient content show/hide
165
 * @param props - Visibility configuration and content
166
 * @returns React element that efficiently manages content visibility
167
 */
168
function ResourceSavingView(props: {
169
  /** Whether content should be visible (required) */
170
  visible: boolean;
171
  /** Content to show/hide (required) */
172
  children: React.ReactNode;
173
  /** Custom container styling */
174
  style?: StyleProp<ViewStyle>;
175
}): React.ReactElement;
176
```
177

178
**Usage Examples:**
179

180
```typescript
181
import { ResourceSavingView } from "@react-navigation/elements";
182

183
// Basic conditional rendering
184
<ResourceSavingView visible={showDetails}>
185
  <View style={styles.detailsPanel}>
186
    <Text>Expensive content that should be hidden when not needed</Text>
187
    <ComplexChart data={chartData} />
188
  </View>
189
</ResourceSavingView>
190

191
// In a tab or accordion interface
192
function AccordionItem({ title, isExpanded, onToggle, children }) {
193
  return (
194
    <View>
195
      <TouchableOpacity onPress={onToggle}>
196
        <Text>{title}</Text>
197
      </TouchableOpacity>
198
      <ResourceSavingView visible={isExpanded}>
199
        <View style={styles.accordionContent}>
200
          {children}
201
        </View>
202
      </ResourceSavingView>
203
    </View>
204
  );
205
}
206

207
// For screen content that might be offscreen
208
function TabPanel({ isActive, children }) {
209
  return (
210
    <ResourceSavingView 
211
      visible={isActive}
212
      style={{ flex: 1 }}
213
    >
214
      {children}
215
    </ResourceSavingView>
216
  );
217
}
218

219
// Performance-critical list items
220
function ListItem({ item, isVisible }) {
221
  return (
222
    <View style={styles.listItem}>
223
      <Text>{item.title}</Text>
224
      <ResourceSavingView visible={isVisible}>
225
        <ExpensiveSubComponent data={item.details} />
226
      </ResourceSavingView>
227
    </View>
228
  );
229
}
230
```
231

232
## Platform-Specific Optimizations
233

234
### Web
235
- **CSS Display**: Uses CSS `display: none` for hidden content to remove from layout
236
- **DOM Optimization**: Prevents unnecessary DOM nodes when content is hidden
237
- **Memory Management**: Efficient cleanup of hidden interactive elements
238

239
### iOS  
240
- **View Hierarchy**: Uses view positioning to hide content while maintaining component state
241
- **Memory Pressure**: Helps reduce memory pressure in complex view hierarchies
242
- **Animation Ready**: Hidden content can be quickly shown with animations
243

244
### Android
245
- **Layout Performance**: Optimizes layout passes by removing hidden views from measurement
246
- **Memory Usage**: Reduces memory footprint for complex hidden content
247
- **Rendering**: Prevents unnecessary rendering cycles for hidden components
248

249
## Theme Integration
250

251
All utility components automatically integrate with the React Navigation theme:
252

253
```typescript
254
import { useTheme } from '@react-navigation/native';
255
import { Text, Label } from "@react-navigation/elements";
256

257
function ThemedComponent() {
258
  const theme = useTheme();
259
  
260
  return (
261
    <View>
262
      {/* These components automatically use theme colors */}
263
      <Text>Themed text using navigation theme</Text>
264
      <Label>Themed label using navigation theme</Label>
265
      
266
      {/* Manual theme usage */}
267
      <MissingIcon color={theme.colors.text} size={20} />
268
    </View>
269
  );
270
}
271
```
272

273
## Performance Considerations
274

275
### ResourceSavingView Performance Impact
276

277
The ResourceSavingView component provides significant performance benefits:
278

279
- **Memory Reduction**: Hidden content is removed from the render tree
280
- **Layout Performance**: Eliminates layout calculations for hidden content  
281
- **Rendering Efficiency**: Reduces unnecessary re-renders of complex hidden components
282
- **State Preservation**: Component state is maintained even when hidden
283

284
**Before (without ResourceSavingView):**
285
```typescript
286
// Always renders expensive content, even when hidden
287
<View style={{ opacity: showContent ? 1 : 0 }}>
288
  <ExpensiveComponent /> {/* Always mounted and rendered */}
289
</View>
290
```
291

292
**After (with ResourceSavingView):**
293
```typescript  
294
// Only renders content when visible
295
<ResourceSavingView visible={showContent}>
296
  <ExpensiveComponent /> {/* Only mounted when visible */}
297
</ResourceSavingView>
298
```
299

300
### Best Practices
301

302
1. **Use ResourceSavingView** for expensive content that can be hidden
303
2. **Prefer Text and Label** over raw React Native Text for theme consistency
304
3. **Use MissingIcon** as a fallback to maintain consistent spacing
305
4. **Style utility components** with theme-aware colors when possible
306

307
```typescript
308
// Good: Theme-aware styling
309
<Text style={{ color: theme.colors.text }}>
310
  Themed text
311
</Text>
312

313
// Better: Automatic theme integration
314
<Text>
315
  Automatically themed text
316
</Text>
317
```