Link Preview

kai-link-preview

Turns a bare URL into an image, a title, and a description without fetching anything itself.

• Shadow DOM
• Pure by default — never fetches
• Optional backend fetcher
• Graceful image fallback
• Card Contract events

Preview

When to use

When an agent surfaces a URL and you want a rich tile instead of a plain hyperlink. With only the URL at render time, wire configureLinkPreview to your own OG-scraping backend.

Usage

Set data in JavaScript (it’s an object, not an attribute):

<kai-link-preview id="lp"></kai-link-preview>

<script type="module">
  import '@kitn.ai/ui/web-components';

  await customElements.whenDefined('kai-link-preview');

  const lp = document.getElementById('lp');
  lp.cardId = 'card-link-1';
  lp.data = {
    url: 'https://example.com/blog/generative-ui',
    title: 'Generative UI, explained',
    description: 'How agents render typed, themed cards in the chat.',
    image: 'https://example.com/og.png',
    favicon: 'https://example.com/favicon.ico',
    siteName: 'Example Blog',
    domain: 'example.com',
  };
</script>

• data — every key except url is optional.
• cardId — set as card-id attribute or cardId property; correlates emitted events when multiple cards are in a <kai-cards> host.
• Pure by default — the element never makes network calls. For bare { url }, call configureLinkPreview({ fetchMetadata }) once at startup to point at your backend.
• Click dispatches a bubbling kai-card CustomEvent with { kind: 'open', url, target: 'tab' }. A missing or broken image hides the image region silently; an invalid url renders a non-clickable “Invalid link” chip.

Examples

Full Preview

Code

No Image

With no image, the card falls back to the text-and-domain layout.

Code

Bare URL with Fetcher

With only { url }, the card shows a skeleton until configureLinkPreview resolves metadata from your backend:

import { configureLinkPreview } from '@kitn.ai/ui';

configureLinkPreview({
  fetchMetadata: (url) =>
    fetch('/api/og?url=' + encodeURIComponent(url)).then((r) => r.json()),
});

Code

Invalid Link

An invalid url renders a non-clickable “Invalid link” chip and emits one error event through the kai-card envelope.

Code

Props

Property	Type	Default	Notes
theme	"light" | "dark" | "auto"	'auto'	Color mode (`auto` follows prefers-color-scheme).
cardId	string	—	Stable card id correlating every emitted event. Set as an attribute or property.
data	LinkPreviewData	—	The link payload (OG metadata). Set as a JS **property** (object).

Composed from

This element wraps these SolidJS components — reach for them directly when you need finer control than the props expose.

LinkPreview

---

Need a hand? Report a bug Ask for help