0
# Terminal Link
1

2
Terminal Link provides a lightweight utility for creating clickable hyperlinks in terminal output using ANSI escape sequences. It automatically detects terminal hyperlink support and provides graceful fallbacks for unsupported terminals by displaying URLs in parentheses after the link text.
3

4
## Package Information
5

6
- **Package Name**: terminal-link
7
- **Package Type**: npm
8
- **Language**: JavaScript (with TypeScript definitions)
9
- **Installation**: `npm install terminal-link`
10

11
## Core Imports
12

13
```typescript
14
import terminalLink from "terminal-link";
15
import type { Options } from "terminal-link";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const terminalLink = require("terminal-link");
22
```
23

24
## Basic Usage
25

26
```typescript
27
import terminalLink from "terminal-link";
28

29
// Create a clickable link for stdout
30
const link = terminalLink('My Website', 'https://sindresorhus.com');
31
console.log(link);
32

33
// Create a clickable link for stderr  
34
const errorLink = terminalLink.stderr('Documentation', 'https://docs.example.com');
35
console.error(errorLink);
36

37
// Check if terminal supports hyperlinks
38
if (terminalLink.isSupported) {
39
  console.log('Your terminal supports clickable links!');
40
}
41
```
42

43
## Capabilities
44

45
### Default Link Creation
46

47
Creates clickable hyperlinks for terminal stdout output with automatic fallback support for unsupported terminals.
48

49
```typescript { .api }
50
/**
51
 * Create a clickable link in the terminal's stdout
52
 * @param text - Text to display for the link
53
 * @param url - URL to link to  
54
 * @param options - Optional configuration for fallback behavior and target stream
55
 * @returns Formatted string with hyperlink or fallback
56
 */
57
declare function terminalLink(
58
  text: string, 
59
  url: string, 
60
  options?: Options
61
): string;
62
```
63

64
**Usage Examples:**
65

66
```typescript
67
import terminalLink from "terminal-link";
68

69
// Basic hyperlink
70
const link = terminalLink('Click here', 'https://example.com');
71
console.log(link);
72

73
// With custom fallback function
74
const customLink = terminalLink('Visit site', 'https://example.com', {
75
  fallback: (text, url) => `${text}: ${url}`
76
});
77

78
// Disable fallback entirely  
79
const noFallbackLink = terminalLink('Link text', 'https://example.com', {
80
  fallback: false
81
});
82
```
83

84
### Terminal Link Function Properties
85

86
The main terminalLink function includes static properties and methods for stderr support and capability detection.
87

88
```typescript { .api }
89
declare const terminalLink: {
90
  /**
91
   * Create a clickable link in the terminal's stdout
92
   */
93
  (text: string, url: string, options?: Options): string;
94

95
  /**
96
   * Check whether the terminal's stdout supports links
97
   * Prefer using default fallback or fallback option when possible
98
   */
99
  readonly isSupported: boolean;
100

101
  /**
102
   * Create a clickable link in the terminal's stderr
103
   */
104
  readonly stderr: {
105
    (text: string, url: string, options?: Options): string;
106
    /**
107
     * Check whether the terminal's stderr supports links
108
     * Prefer using default fallback or fallback option when possible
109
     */
110
    readonly isSupported: boolean;
111
  };
112
};
113
```
114

115
## Types
116

117
```typescript { .api }
118
/**
119
 * Configuration options for terminalLink functions
120
 * Also available as a named export
121
 */
122
export type Options = {
123
  /**
124
   * Override the default fallback behavior
125
   * - Function: Custom fallback formatter receiving text and url
126
   * - false: Disable fallback entirely (return original text)
127
   * - true/undefined: Use default fallback format "text (url)"
128
   * @default `${text} (${url})`
129
   */
130
  readonly fallback?: ((text: string, url: string) => string) | boolean;
131
};
132
```
133

134
## Implementation Details
135

136
- **ANSI Escape Sequence**: Uses `\u001B]8;;{url}\u0007{text}\u001B]8;;\u0007` format for hyperlinks
137
- **Dependencies**: Built on `ansi-escapes` for ANSI sequences and `supports-hyperlinks` for terminal detection
138
- **Zero Width Characters**: Default fallback uses zero-width spaces (`\u200B`) around URLs to prevent terminal word-wrapping issues
139
- **Stream Targeting**: Supports separate targeting of stdout and stderr streams with independent support detection
140
- **Graceful Degradation**: Automatically falls back to readable text format when hyperlinks are not supported