Xzero UI
Pro library
Special componentsLink unfurl

Link unfurlPro

A composer where pasting a URL shows a loading shimmer on the link, then unfurls it into a rich preview card with title, image and favicon in one morph, which can be collapsed back to the inline link or removed.

$ pnpm dlx shadcn@4.23.0 add @xzero-ui-pro/link-unfurl
Live · keyboard ready

When to use

When not to use

Installation

Register both Xzero UI namespaces in your project's components.json:

{
  "registries": {
    "@xzero-ui": "https://mcp.xzero.co.uk/r/{name}.json",
    "@xzero-ui-pro": "https://mcp.xzero.co.uk/r/pro/{name}.json"
  }
}

npx shadcn@4.23.0 add @xzero-ui-pro/link-unfurl

Install xzero-foundation once, and import @/components/xzero/foundation.css in your app root. No Xzero token is used by this snapshot. For sample portraits, photos, fonts, or logos, download https://mcp.xzero.co.uk/install-assets.mjs and run node xzero-install-assets.mjs <receiving-project>.

Usage

import { LinkUnfurl, type LinkUnfurlPreview } from "@/components/xzero/link-unfurl/link-unfurl";

export function ChannelComposer({ channel, post }: { channel: string; post: (text: string) => Promise<void> }) {
  return <LinkUnfurl
    label={`Message #${channel}`}
    placeholder={`Message #${channel}`}
    defaultValue=""
    samples={[]}
    autoPlay={false}
    resolve={async (url, signal) => {
      const res = await fetch(`/api/unfurl?url=${encodeURIComponent(url)}`, { signal });
      return res.ok ? (await res.json()) as LinkUnfurlPreview : null;
    }}
    onSend={message => post(message.text)}
  />;
}

API reference

LinkUnfurl

A message composer that unfurls links. Paste an address and it becomes an inline link with a soft loading sweep; once the preview resolves, the favicon and title roll in and the link unrolls into a rich card with site, title, description, and image in one continuous morph. The card's corner grows out of the link itself, width first and height after, lifting on a shadow while it travels. Click the link, press the collapse button, or drag the card up to fold it back into the text; remove it to take the link out of the message.

PropTypeDefaultDescription
labelstring"Message #lisbon-offsite"Accessible name of the message field.
placeholderstring"Message #lisbon-offsite"Shown while the message is empty.
defaultValuestring"Found a place for the offsite, take a look"Starting text of the message.
samplesLinkUnfurlPreview[]–Sample links offered as buttons under the field; the built in resolver answers with their previews. Once a sample is in the message its button shows or collapses its card. Pass an empty array to hide them.
resolve(url: string, signal: AbortSignal) => Promise<LinkUnfurlPreview | null>–Fetches the preview for a pasted address, usually from your own unfurl endpoint. Return null when there is none; the link then stays in the text without a card and can be clicked to try again. Without it, samples resolve by address and other links get a plain preview built from the address after a 1.15s simulated fetch.
autoExpandbooleantrueUnfurls a card as soon as its preview resolves. When false the link only gains its favicon and title, and opens on click.
autoPlaybooleantruePastes the first sample the first time the composer scrolls into view, unless someone has already interacted.
speednumber1Multiplier for the morph and the simulated fetch.
pausedbooleanfalseOpens and folds cards instantly without the morph and turns autoplay off.
accentstring–Color of an unfurled link and its tie to its card. Defaults to the accent.
sendLabelstring"Send message"Accessible name of the send button.
onSend(message: LinkUnfurlMessage) => void | Promise<unknown>–Called on Enter or the send button with the text (links written out as addresses) and the resolved previews. Return a promise to hold the composer while it is pending; a rejection shows its message under the composer. On success the composer clears and the button confirms with a check.
classNamestring–Extra class on the root element.
styleCSSProperties–Inline styles on the root element.

Accessibility

Motion

Responsive behavior

Performance

Notes for AI

Also in surfaces

Guidance for AI tools

Link unfurl: A composer where pasting a URL shows a loading shimmer on the link, then unfurls it into a rich preview card with title, image and favicon in one morph, which can be collapsed back to the inline link or removed. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://ui.xzero.co.uk/llms.txt

Browse all components