Link preview

Pro

A link with a preview of the page it leads to, shown when the pointer rests on it or it takes keyboard focus: the page's title, a line of description, its site and address, and an image when the app has one. The preview is extra detail only; the link works without it and says where it goes in its own words.

Everything in the preview is another site's text, fetched by the app (an unfurl, the page's Open Graph tags), so it is drawn as plain text, never as HTML, each part in an isolate with bidi controls marked, and the address is shown as text, so a title can't pretend to be somewhere else: its scheme and host are shown as the browser reads them (lower-cased, an international name as punycode, with no user name or password before the host, which is noted when there is one) whole, wrapping if they must, and only the path after them is cut short. site is the page's own claim; the host is where the link goes. The link itself is the app's: pass its text as children, or the app's own link element (a router's Link) with its href.

Markdown

Version 5.2.0· other versions

This page is for 5.2.0, the current release. An earlier release’s page is the Markdown that release published, so the docs match the version you have installed (candor-lock.json records it).

Not in the docs of 1.3.0, 1.4.0, 1.5.0, 1.5.1, 1.6.0, 1.7.0, 1.8.0, 1.8.1, 1.9.0, 1.9.1, 2.0.0, 2.1.0, 2.2.0, 2.3.0, 2.4.0, 2.5.0, 2.5.1, 2.6.0, 2.6.1, 2.6.2, 2.7.0, 2.8.0, 2.9.0, 2.10.0, 3.0.0, 4.0.0, 4.0.1, 4.0.2, 4.1.0, 4.2.0 and 4.3.0: the page came later, or had another name then.

Docs pages weren’t kept for 1.0.0, 1.0.1, 1.1.0, 1.1.1, 1.2.0 and 1.2.1: they are kept from 1.3.0 on, and before that only llms.txt was published.

Preview

Install

With the Candor CLI

First time? Get started sets up the registry and theme. Or with shadcn directly: npx shadcn@latest add @candor/link-preview

Brings in: bidi, hover-card, locale, motion, tokens, utils

Usage

TSX · The example above

"use client"

import { LinkPreview } from "@/components/candor/link-preview"

// The preview's words are the other site's, fetched by the app (an unfurl): drawn as text, with the address shown.
export default function Example() {
  return (
    <p className="max-w-md text-sm">
      The agent used{" "}
      <LinkPreview
        href="https://www.rfc-editor.org/rfc/rfc9110"
        site="RFC Editor"
        title="RFC 9110: HTTP Semantics"
        description="The overall architecture of HTTP, its common terminology, and the parts of the protocol shared by all versions."
      >
        the HTTP semantics standard
      </LinkPreview>{" "}
      to check the retry rules.
    </p>
  )
}

<LinkPreview>

Prop	Type	Default	Description
hrefrequired	`string`	—	Where the link goes. Shown in the preview as text.
titlerequired	`string`	—	The page's title, as the other site gives it.
description	`string \| undefined`	—	A line about the page, as the other site gives it.
image	`string \| undefined`	—	An image of the page (its Open Graph image), drawn as decoration. Fetch it through your own server if its address shouldn't reach the viewer's browser.
site	`string \| undefined`	—	The site's name as the page claims it (its Open Graph `site_name`): "GitHub", "The Guardian". The host shown under it is where the link really goes.
openDelay	`number \| undefined`	—	How long the pointer rests on the link before the preview opens, in milliseconds.
className	`string \| undefined`	—	Classes for the preview card.
childrenrequired	`React.ReactNode`	—	The link's text, or the app's own link element (it keeps its `href`).

Strings

The fixed words, in English by default. Change any of them under linkPreview in <LocaleProvider strings={{ … }}>; the table is exported as linkPreviewStrings.

Key	English
userinfo	This address has a name before its host, which can make it look like another site. It goes to the host shown.

Motion

Moment	Family	What it does
open	overlay, scale	The preview opens from the link on hover or focus and closes when both leave.

Set with --cd-motion-link-preview-<moment>-* in your brand file; the families are in the design reference.