or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-terminal-link

Create clickable links in the terminal

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/terminal-link@4.0.x

To install, run

npx @tessl/cli install tessl/npm-terminal-link@4.0.0

index.mddocs/

Terminal Link

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.

Package Information

  • Package Name: terminal-link
  • Package Type: npm
  • Language: JavaScript (with TypeScript definitions)
  • Installation: npm install terminal-link

Core Imports

import terminalLink from "terminal-link";
import type { Options } from "terminal-link";

For CommonJS:

const terminalLink = require("terminal-link");

Basic Usage

import terminalLink from "terminal-link";

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

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

// Check if terminal supports hyperlinks
if (terminalLink.isSupported) {
  console.log('Your terminal supports clickable links!');
}

Capabilities

Default Link Creation

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

/**
 * Create a clickable link in the terminal's stdout
 * @param text - Text to display for the link
 * @param url - URL to link to  
 * @param options - Optional configuration for fallback behavior and target stream
 * @returns Formatted string with hyperlink or fallback
 */
declare function terminalLink(
  text: string, 
  url: string, 
  options?: Options
): string;

Usage Examples:

import terminalLink from "terminal-link";

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

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

// Disable fallback entirely  
const noFallbackLink = terminalLink('Link text', 'https://example.com', {
  fallback: false
});

Terminal Link Function Properties

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

declare const terminalLink: {
  /**
   * Create a clickable link in the terminal's stdout
   */
  (text: string, url: string, options?: Options): string;

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

  /**
   * Create a clickable link in the terminal's stderr
   */
  readonly stderr: {
    (text: string, url: string, options?: Options): string;
    /**
     * Check whether the terminal's stderr supports links
     * Prefer using default fallback or fallback option when possible
     */
    readonly isSupported: boolean;
  };
};

Types

/**
 * Configuration options for terminalLink functions
 * Also available as a named export
 */
export type Options = {
  /**
   * Override the default fallback behavior
   * - Function: Custom fallback formatter receiving text and url
   * - false: Disable fallback entirely (return original text)
   * - true/undefined: Use default fallback format "text (url)"
   * @default `${text} (${url})`
   */
  readonly fallback?: ((text: string, url: string) => string) | boolean;
};

Implementation Details

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