Docs
Media

Link Preview

A rich card for any URL that holds its size while it loads, then settles the page's image and title under a glass host chip.

$npx swiftpieces add LinkPreview
See it in a Pro app On a real screen in one of the Pro apps: open it with Pro, take it apart, remix it, and copy the SwiftUI.
Free · MIT + Commons ClauseiOS 17.0+Liquid Glasslinkurlpreviewunfurlmetadatalinkpresentationcachechat
Type
LinkPreview
Files
LinkPreview.swift
Depends on
Nothing (Apple frameworks only)
Version
1.2.0

A rich preview card for a URL: the page's image, title and host, fetched once and cached. The card is content; its one piece of chrome, the host, sits on a small liquid glass chip. It shows from the first frame (the host is known before the page is) and rides over the picture on the large card. Tapping opens url through the environment's openURL, so an app that shows links in its own browser routes it with .environment(\.openURL, OpenURLAction { url in … }) like any other link.

Notes

  • LinkPreview(url:) fetches the page with LinkPresentation and shows its image, title and host. Pass metadata: to show your own (previews, tests, links your server already unfurled) with no request.
  • The card is content; its one piece of chrome, the host, sits on a small liquid glass chip: over the top leading corner of the picture on the large card, above the title on the compact one. The host is known before the page is, so the chip is there from the first frame, through the skeleton. A redirect blurs the final host in over the old one as the glass reshapes around it.
  • Three states, one footprint. While loading, the card is a skeleton built from the real layout, so the large card keeps its exact size when the content arrives. The picture develops first, under its chip, fading in from just above full size and settling flat on the placeholder; the title starts on the same beat (nothing you read is held back) and rises a few points into the place its skeleton held, on a slightly softer spring with no bounce, so it settles just after and text never wobbles. A card that starts from the cache appears at once, with no animation. A page that cannot be read (offline, timeout, unknown host, a page with nothing in it) becomes the quiet address card: a link glyph, the host on its chip and the address, still tappable.
  • .compact is a row with a square thumbnail, for chats and lists. .large puts a 1.91 : 1 image on top, capped at 280pt tall so a wide card crops instead of growing. Both take the width they are offered. A failed large card closes to the compact address card with no overshoot, so the feed below reflows once without bobbing.
  • No image falls back to the site icon on a quiet tile, then to the host's first letter on a solid block picked from the host, so a site keeps its color. A tiny "image" is treated as an icon rather than stretched.
  • Links that are not http or https never make a request: email, phone and message links show the address card with their own glyph and a chip such as "Email".
  • Redirects show the final host. Titles are trimmed with runs of whitespace collapsed, at most two lines (three at accessibility sizes). Long addresses truncate in the middle.
  • One cache for the whole app: at most 150 pages and about 48 MB of decoded images in an NSCache, emptied by the system under memory pressure. Cards showing the same URL share one fetch, a card that scrolls back into view starts from the cache with no skeleton, and a failure is remembered for 30 seconds so a failing link does not refetch on every scroll.
  • A card that disappears or changes its URL stops waiting at once; the fetch itself is cancelled when no card is waiting for it. A late result can never land on a card whose URL has changed. timeout (15 seconds) is enforced even while a connection is still being attempted.
  • Each fetch uses its own LPMetadataProvider, created, started and cancelled on the main actor. Images are decoded and downsampled with ImageIO off the main actor and never kept at full size.
  • Pressing sinks the card by a couple of points at each edge, from its center so it never fights a scroll, and it springs back on release. It stays opaque.
  • Tap opens the link through the environment's openURL, so an app with its own browser routes it with .environment(\.openURL, OpenURLAction { … }). Long press shows Open Link, Copy Link and Share (with the title and image in the share sheet); copying plays a success haptic.
  • VoiceOver: one element read as "Title, host" with the link trait, a Copy Link action, and "Loading preview" as its value while loading. Copying is announced.
  • Dynamic Type: text scales, the thumbnail grows to 96pt, and at accessibility sizes the compact card stacks the text under the thumbnail at full width.
  • Reduce Motion: the skeleton stops sweeping and breathes in place instead (a slow opacity pulse partway toward the highlight and back, on the same shared clock), so a loading card still shows it is working and its bones never fade into the card. The press darkens the card slightly (lightens it in dark mode) instead of sinking, and the picture and text fade in without scale or rise.
  • All text is one weight, semibold; size sets the hierarchy. The chip is Liquid Glass on iOS 26, a frosted material before that, and a solid fill under Reduce Transparency.
  • Style sets the card, skeleton, highlight, title, secondary (the chip's text) and tile colors, the letter ink and the corner radius. .disabled(true) dims the card.

Usage

LinkPreviewExample()

Parameters

ParameterDescription
urlThe link to preview and open. http and https links are fetched; any other scheme (email, phone, app links) shows the quiet link card at once, without a request.
layout.compact is a row with a square thumbnail on the leading side, for chat bubbles and lists. .large puts a wide image on top, for feeds and composers. Both take the width they are offered.
metadataMetadata to show as is, with no request: for previews, tests, or links your server has already unfurled. nil fetches.
timeoutSeconds before a fetch gives up and the card falls back to the address.
styleColors and corner radius. Defaults to the SwiftPieces house palette, adapting to light and dark.

Install

Pick one. Run it from the folder that contains your .xcodeproj and the files land inside your app.

Terminal

$npx swiftpieces add LinkPreview

Or ask your coding agent · Claude Code, Cursor or Xcode, once the MCP server is connected

>Add the SwiftPieces "Link Preview" piece to my app

Or copy the source above into your app.

New to SwiftUI?If you know React, CSS or Tailwind, SwiftUI is easier to pick up than it looks.Try real app patterns first

Building a whole app? See SwiftPieces Pro →

All media →

Build it yourself: SwiftUI animations guide

On this page

SwiftPiecesPro

Build the whole app with one library.

Production-ready screens, whole flows, complete app templates, a Build Kit your agent follows and Pro remixing.

Explore Pro