feat: add `link` method for terminal hyperlinks (OSC 8)

[privatenumber]

Feature request

What is motivation or use case for adding/changing the behavior?

Terminal hyperlinks (OSC 8) are part of the ANSI escape sequence family. Since this package is ansis, it feels within scope.

Describe the solution you'd like

import ansis, { link } from 'ansis';

link('Click here', 'https://example.com')
ansis.blue.link('Docs', 'https://example.com/docs')

Describe alternatives you've considered

Manually constructing OSC 8 sequences or using terminal-link.

Appreciation for the useful project

• After the feature is implemented, do not forget to give a star ⭐

[privatenumber]

Happy to open a PR for this btw.

[webdiscus]

Hello @privatenumber. Thanks for the feature request!

I've already thought about adding link support too.

The main problem is that not all terminals support clickable links.
We need to know which terminals support it (may be add a list of them in README) and have a safe fallback when link is not supported.

I will add the link() method in the next version.

[webdiscus]

Hello @privatenumber

the beta version 4.3.0-beta.3 contains new link() function.
It’s available on GitHub in the next branch.

Syntax:

• link(text, url) - custom link text + target URL
• link(url) - URL is used as both link text and target URL

import ansis, { blue, link } from 'ansis';

console.log(ansis.link('Click here', 'https://example.com'));
// text and URL are the same
console.log(link('https://example.com'));
// link with styling
console.log(blue.underline.link('Click here', 'https://example.com'));

Important

When combining styles with hyperlinks, call link() last in the chain.

blue.underline.link('Click here', 'https://example.com'); // ✅ correct
blue.link('Click here', 'https://example.com').underline; // ❌ error

Could you please test it in your use cases and share your feedback?

As far as I know, iTerm supports hyperlinks. Which terminals are you using?

P.S. Ansis is focused on keeping the package small. This function bloats the npm package by about 120 bytes, but it's still under 6 kB.

[privatenumber]

Amazing, thanks. I'm using iTerm 2. Will try it out soon.

[privatenumber]

Hey, this is working great — thanks for shipping it!

One small thought: would it make sense to flip the param order to link(url, label?)? That way you could just do link(url) when the URL itself is a fine label.

[webdiscus]

Hi @privatenumber,

Honestly, I like the link(url, label?) arguments order too, because link(url) looks simple and reads cleanly.

But I still think link(label, url?) is better here, because this order is already common in similar JS libraries:

• cli.url('text', 'https://...') - oclif/cli-ux
• terminalLink(text, url) - sindresorhus/terminal-link
• link(text, url) - kolorist

If hyperlinks are not supported, the output will be plain text like label (url). In that case, label is still the first, and the URL is secondary.

So this is not a strict rule, but it is a common pattern.

For me, the main question is: what is more important here - a nicer arguments order, or keeping the order that many developers already expect?

Do you know any other libraries or frameworks that use the link(url, label?) order?

[privatenumber]

I don't, but this could be a chance to break some existing conventions to propose better ones!

[webdiscus]

I don't, but this could be a chance to break some existing conventions to propose better ones!

I agree, we shouldn't follow existing conventions and suggest better ones. I will prepare next beta version with new syntax.