0
# Link Components
1

2
Link components provide declarative navigation using path-based routing. They render as anchor tags on web and Text components on native platforms, with proper accessibility and interaction handling.
3

4
## Capabilities
5

6
### Link Component
7

8
Renders a navigational link that integrates with React Navigation's routing system.
9

10
```typescript { .api }
11
/**
12
 * Component to render link to another screen using a path.
13
 * Uses an anchor tag on the web.
14
 */
15
function Link<ParamList extends ReactNavigation.RootParamList>(
16
  props: LinkProps<ParamList> & Omit<TextProps, 'disabled'> & {
17
    /** Target attribute for web links (e.g., '_blank') */
18
    target?: string;
19
    /** Custom press handler called before navigation */
20
    onPress?: (
21
      e: React.MouseEvent<HTMLAnchorElement, MouseEvent> | GestureResponderEvent
22
    ) => void;
23
    /** Whether the link is disabled */
24
    disabled?: boolean | null;
25
    /** Content to render inside the link */
26
    children: React.ReactNode;
27
  }
28
): React.ReactElement;
29

30
type LinkProps<
31
  ParamList extends ReactNavigation.RootParamList,
32
  RouteName extends keyof ParamList = keyof ParamList
33
> =
34
  | ({
35
      /** Optional absolute path to use for href (e.g., '/feeds/hot') */
36
      href?: string;
37
      /** Optional action to use for in-page navigation */
38
      action?: NavigationAction;
39
    } & (RouteName extends unknown
40
      ? undefined extends ParamList[RouteName]
41
        ? { screen: RouteName; params?: ParamList[RouteName] }
42
        : { screen: RouteName; params: ParamList[RouteName] }
43
      : never))
44
  | {
45
      /** Optional absolute path to use for href */
46
      href?: string;
47
      /** Navigation action to dispatch */
48
      action: NavigationAction;
49
      screen?: undefined;
50
      params?: undefined;
51
    };
52
```
53

54
**Usage Examples:**
55

56
```typescript
57
import { Link } from '@react-navigation/native';
58
import { StyleSheet } from 'react-native';
59

60
// Navigate to a screen by name
61
function HomeScreen() {
62
  return (
63
    <Link screen="Profile" params={{ userId: '123' }}>
64
      View Profile
65
    </Link>
66
  );
67
}
68

69
// Navigate using href path
70
function NavMenu() {
71
  return (
72
    <Link href="/profile/123" style={styles.menuLink}>
73
      User Profile
74
    </Link>
75
  );
76
}
77

78
// With custom styling
79
function StyledLink() {
80
  return (
81
    <Link 
82
      screen="Settings"
83
      style={[styles.link, styles.primaryLink]}
84
      disabled={!userLoggedIn}
85
    >
86
      Settings
87
    </Link>
88
  );
89
}
90

91
// With custom press handler
92
function CustomLink() {
93
  const handlePress = (e: any) => {
94
    // Custom logic before navigation
95
    console.log('Link pressed');
96
    // Don't prevent default - navigation will still occur
97
  };
98

99
  return (
100
    <Link 
101
      screen="Details" 
102
      params={{ id: itemId }}
103
      onPress={handlePress}
104
    >
105
      View Details
106
    </Link>
107
  );
108
}
109

110
// Web-specific target attribute
111
function ExternalStyleLink() {
112
  return (
113
    <Link 
114
      href="/external-page"
115
      target="_blank"
116
      style={styles.externalLink}
117
    >
118
      Open in New Tab
119
    </Link>
120
  );
121
}
122

123
const styles = StyleSheet.create({
124
  link: {
125
    color: '#007AFF',
126
    textDecorationLine: 'underline',
127
  },
128
  primaryLink: {
129
    fontWeight: 'bold',
130
  },
131
  menuLink: {
132
    fontSize: 16,
133
    padding: 12,
134
  },
135
  externalLink: {
136
    color: '#34C759',
137
  },
138
});
139
```
140

141
### useLinkProps Hook
142

143
Hook that generates props for anchor tags to work with in-page navigation.
144

145
```typescript { .api }
146
/**
147
 * Hook to get props for an anchor tag so it can work with in page navigation.
148
 * Useful for creating custom link components.
149
 */
150
function useLinkProps<ParamList extends ReactNavigation.RootParamList>(
151
  props: LinkProps<ParamList>
152
): {
153
  /** Generated href for web links */
154
  href?: string;
155
  /** Accessibility role */
156
  role: 'link';
157
  /** Press handler that performs navigation */
158
  onPress: (
159
    e?: React.MouseEvent<HTMLAnchorElement, MouseEvent> | GestureResponderEvent
160
  ) => void;
161
};
162
```
163

164
**Usage Examples:**
165

166
```typescript
167
import { useLinkProps } from '@react-navigation/native';
168
import { Pressable, Text } from 'react-native';
169

170
// Custom link component using useLinkProps
171
function CustomLinkButton({ screen, params, children, ...props }) {
172
  const { href, onPress, ...linkProps } = useLinkProps({ screen, params });
173

174
  return (
175
    <Pressable 
176
      {...linkProps}
177
      {...props}
178
      onPress={onPress}
179
      style={({ pressed }) => [
180
        styles.linkButton,
181
        pressed && styles.pressed,
182
      ]}
183
    >
184
      <Text style={styles.linkText}>{children}</Text>
185
    </Pressable>
186
  );
187
}
188

189
// Custom touchable link
190
function TouchableLink({ screen, params, style, children }) {
191
  const { onPress } = useLinkProps({ screen, params });
192

193
  return (
194
    <TouchableOpacity onPress={onPress} style={style}>
195
      {children}
196
    </TouchableOpacity>
197
  );
198
}
199

200
// Link with icon
201
function IconLink({ screen, params, icon, children }) {
202
  const { onPress } = useLinkProps({ screen, params });
203

204
  return (
205
    <Pressable onPress={onPress} style={styles.iconLink}>
206
      <Image source={icon} style={styles.icon} />
207
      <Text style={styles.linkText}>{children}</Text>
208
    </Pressable>
209
  );
210
}
211
```
212

213
### Link Props Types
214

215
Type definitions for link component properties and navigation targets.
216

217
```typescript { .api }
218
type LinkProps<
219
  ParamList extends ReactNavigation.RootParamList,
220
  RouteName extends keyof ParamList = keyof ParamList
221
> =
222
  // Screen-based navigation with optional href and action
223
  | ({
224
      href?: string;
225
      action?: NavigationAction;
226
    } & (RouteName extends unknown
227
      ? undefined extends ParamList[RouteName]
228
        ? { screen: RouteName; params?: ParamList[RouteName] }
229
        : { screen: RouteName; params: ParamList[RouteName] }
230
      : never))
231
  // Action-based navigation
232
  | {
233
      href?: string;
234
      action: NavigationAction;
235
      screen?: undefined;
236
      params?: undefined;
237
    };
238

239
// Example param list type for type safety
240
type RootParamList = {
241
  Home: undefined;
242
  Profile: { userId: string };
243
  Settings: undefined;
244
  Article: { id: number; slug?: string };
245
};
246
```
247

248
**Usage Examples:**
249

250
```typescript
251
// Type-safe link usage
252
function TypeSafeLinks() {
253
  return (
254
    <>
255
      {/* ✅ Valid - Profile requires userId param */}
256
      <Link screen="Profile" params={{ userId: '123' }}>
257
        Profile
258
      </Link>
259
      
260
      {/* ✅ Valid - Home has no params */}
261
      <Link screen="Home">
262
        Home
263
      </Link>
264
      
265
      {/* ✅ Valid - Article with required id */}
266
      <Link screen="Article" params={{ id: 1, slug: 'my-article' }}>
267
        Article
268
      </Link>
269
      
270
      {/* ❌ TypeScript error - missing required userId */}
271
      <Link screen="Profile">
272
        Profile
273
      </Link>
274
      
275
      {/* ❌ TypeScript error - invalid param */}
276
      <Link screen="Home" params={{ invalid: true }}>
277
        Home
278
      </Link>
279
    </>
280
  );
281
}
282
```
283

284
### Platform-Specific Behavior
285

286
Links behave differently across platforms to provide the best user experience.
287

288
```typescript { .api }
289
// Platform-specific rendering and behavior
290
interface PlatformBehavior {
291
  /** Web: Renders as <a> tag with proper href */
292
  web: {
293
    element: 'anchor';
294
    attributes: ['href', 'target', 'onClick'];
295
    behavior: 'standard web link semantics';
296
  };
297
  
298
  /** Native: Renders as Text component with onPress */
299
  native: {
300
    element: 'Text';
301
    attributes: ['onPress'];
302
    behavior: 'touch-based navigation';
303
  };
304
}
305
```
306

307
**Platform Handling:**
308

309
```typescript
310
// The Link component automatically handles platform differences
311
function PlatformAwareLink() {
312
  return (
313
    <Link screen="Profile" params={{ userId: '123' }}>
314
      {/* On web: <a href="/profile/123">View Profile</a> */}
315
      {/* On native: <Text onPress={...}>View Profile</Text> */}
316
      View Profile
317
    </Link>
318
  );
319
}
320

321
// Manual platform handling if needed
322
import { Platform } from 'react-native';
323

324
function ManualPlatformLink() {
325
  const linkProps = useLinkProps({ screen: 'Profile', params: { userId: '123' } });
326
  
327
  if (Platform.OS === 'web') {
328
    return (
329
      <a {...linkProps} className="custom-link">
330
        View Profile
331
      </a>
332
    );
333
  }
334
  
335
  return (
336
    <Text {...linkProps} style={styles.nativeLink}>
337
      View Profile
338
    </Text>
339
  );
340
}
341
```
342

343
### Accessibility
344

345
Links provide proper accessibility attributes and behavior for screen readers.
346

347
```typescript { .api }
348
// Accessibility attributes are automatically applied
349
interface AccessibilitySupport {
350
  role: 'link';
351
  accessible: true;
352
  accessibilityRole: 'link';
353
}
354
```
355

356
**Accessibility Examples:**
357

358
```typescript
359
// Links automatically get proper accessibility attributes
360
function AccessibleLink() {
361
  return (
362
    <Link 
363
      screen="Help" 
364
      accessibilityLabel="Open help documentation"
365
      accessibilityHint="Navigates to the help screen"
366
    >
367
      Help
368
    </Link>
369
  );
370
}
371

372
// Custom accessibility for complex links
373
function ComplexAccessibleLink() {
374
  return (
375
    <Link 
376
      screen="Product" 
377
      params={{ id: product.id }}
378
      accessibilityLabel={`View ${product.name} details`}
379
      accessibilityRole="link"
380
      accessible={true}
381
    >
382
      <Text style={styles.productName}>{product.name}</Text>
383
      <Text style={styles.productPrice}>${product.price}</Text>
384
    </Link>
385
  );
386
}
387
```