Link Preview
Paste a URL and get a preview card: loading skeleton, editable title, large or compact layout, and remove the preview.
$
View as Markdownnpx shadcn@latest add https://sundaeui.dev/r/link-preview.json'use client'
import { useEffect, useState } from 'react'
import './link-preview.css'
export interface LinkMeta { title: string; description?: string; site: string; image?: boolean }
export interface LinkPreviewProps {
resolve: (url: string) => Promise<LinkMeta>
url?: string
size?: 'large' | 'compact'
fill?: 'dark' | 'light'
className?: string
}
const Art = () => (
<svg viewBox="0 0 190 100" preserveAspectRatio="xMidYMid slice" aria-hidden>
<rect width="190" height="100" fill="currentColor" opacity="0.08" />
{[0, 1, 2, 3, 4].map((i) => <rect key={i} x={14 + i * 34} y={60 - i * 8} width="26" height={26 + i * 8} rx="4" fill="currentColor" opacity={0.2 + i * 0.15} />)}
<circle cx="160" cy="24" r="10" fill="currentColor" opacity="0.6" />
</svg>
)
/** URL unfurl card with edit and layout toggle. */
export function LinkPreview({ resolve, url: u0 = '', size: s0 = 'large', fill = 'dark', className }: LinkPreviewProps) {
const [url, setUrl] = useState(u0)
const [meta, setMeta] = useState<LinkMeta | null>(null)
const [busy, setBusy] = useState(false)
const [err, setErr] = useState('')
const [size, setSize] = useState(s0)
const [edit, setEdit] = useState(false)
const go = async (u = url) => {
if (!/^https?:\/\/\S+\.\S+/.test(u.trim())) { setErr('That does not look like a link.'); setMeta(null); return }
setErr(''); setBusy(true); setMeta(null)
try { setMeta(await resolve(u.trim())) } catch { setErr('Could not load a preview for that link.') }
setBusy(false)
}
useEffect(() => { if (u0) go(u0) }, []) // eslint-disable-line react-hooks/exhaustive-deps
return (
<div className={['sd-lnk', className].filter(Boolean).join(' ')} data-fill={fill}>
<form onSubmit={(e) => { e.preventDefault(); go() }}><input aria-label="Link" placeholder="Paste a link" value={url} onChange={(e) => setUrl(e.target.value)} onPaste={(e) => { const t = e.clipboardData.getData('text'); setTimeout(() => go(t), 0) }} /><button type="submit">Preview</button></form>
<div aria-live="polite" aria-busy={busy}>
{busy && <div className="sd-lnk__sk" aria-label="Loading preview"><i /><i style={{ width: '40%' }} /><i /><i style={{ width: '70%' }} /></div>}
{err && <div className="sd-lnk__err" role="alert">{err}</div>}
{meta && (
<article className="sd-lnk__c" data-size={size}>
{meta.image && <div className="sd-lnk__img"><Art /></div>}
<div className="sd-lnk__b"><small>{meta.site}</small><a href={url} onClick={(e) => e.preventDefault()}>{meta.title}</a>{meta.description && <p>{meta.description}</p>}</div>
<button type="button" className="sd-lnk__x" aria-label="Remove preview" onClick={() => setMeta(null)}>×</button>
</article>
)}
</div>
{meta && edit && <div className="sd-lnk__ed"><input aria-label="Preview title" value={meta.title} onChange={(e) => setMeta({ ...meta, title: e.target.value })} /><input aria-label="Preview description" value={meta.description ?? ''} onChange={(e) => setMeta({ ...meta, description: e.target.value })} /></div>}
{meta && <div className="sd-lnk__bar"><button type="button" onClick={() => setEdit((x) => !x)}>{edit ? 'Done editing' : 'Edit text'}</button><button type="button" onClick={() => setSize(size === 'large' ? 'compact' : 'large')}>{size === 'large' ? 'Compact' : 'Large'} layout</button></div>}
</div>
)
}.sd-lnk { --bg: #1c1c1c; --fg: #f6f6f6; --mute: #8e8e8e; --line: rgb(255 255 255 / 0.1); --soft: rgb(255 255 255 / 0.07); --strong: #fafafa; --on: #111;
color: var(--fg); font-size: 14px; line-height: 1.4; -webkit-tap-highlight-color: transparent; }
.sd-lnk[data-fill='light'] { --bg: #fff; --fg: #121212; --mute: #6f6f6f; --line: rgb(0 0 0 / 0.09); --soft: rgb(0 0 0 / 0.05); --strong: #111; --on: #fff; }
.sd-lnk :where(button) { font: inherit; color: inherit; background: none; border: 0; padding: 0; cursor: pointer; }
.sd-lnk :focus-visible { outline: 2px solid var(--fg); outline-offset: 2px; }
.sd-lnk .sr { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; }
.sd-lnk { width: min(100%, 340px); padding: 14px; grid-template-columns: minmax(0, 1fr); border-radius: 18px; background: var(--bg); box-shadow: inset 0 0 0 1px var(--line); display: grid; gap: 10px; }
.sd-lnk form { display: flex; gap: 6px; }
.sd-lnk form input { flex: 1; min-width: 0; height: 38px; padding: 0 12px; border: 0; border-radius: 10px; background: var(--soft); color: var(--fg); font: 12.5px ui-monospace, monospace; outline: 0; }
.sd-lnk form input:focus { box-shadow: inset 0 0 0 1.5px var(--fg); }
.sd-lnk form button { padding: 0 14px; border-radius: 10px; font-size: 13px; font-weight: 600; background: var(--strong) !important; color: var(--on) !important; }
.sd-lnk__c { position: relative; border-radius: 14px; overflow: hidden; box-shadow: inset 0 0 0 1px var(--line); animation: sd-lnk-in 220ms ease-out; }
@keyframes sd-lnk-in { from { opacity: 0; transform: translateY(4px); } }
.sd-lnk__c[data-size='compact'] { display: grid; grid-template-columns: 84px 1fr; }
.sd-lnk__img { aspect-ratio: 1.9; background: var(--soft); display: grid; place-items: center; overflow: hidden; }
.sd-lnk__c[data-size='compact'] .sd-lnk__img { aspect-ratio: auto; height: 100%; }
.sd-lnk__img svg { width: 100%; height: 100%; }
.sd-lnk__b { padding: 10px 12px; display: grid; gap: 3px; min-width: 0; }
.sd-lnk__b small { font-size: 11px; color: var(--mute); text-transform: lowercase; }
.sd-lnk__b a { color: var(--fg); font-size: 13.5px; font-weight: 700; text-decoration: none; overflow: hidden; text-overflow: ellipsis; display: -webkit-box; -webkit-line-clamp: 2; -webkit-box-orient: vertical; }
.sd-lnk__b a:hover { text-decoration: underline; }
.sd-lnk__b p { margin: 0; font-size: 12px; color: var(--mute); overflow: hidden; display: -webkit-box; -webkit-line-clamp: 2; -webkit-box-orient: vertical; }
.sd-lnk__x { position: absolute; top: 6px; right: 6px; width: 26px; height: 26px; border-radius: 50%; background: var(--bg) !important; box-shadow: inset 0 0 0 1px var(--line); display: grid; place-items: center; font-size: 13px; }
.sd-lnk__sk { display: grid; gap: 8px; padding: 12px; border-radius: 14px; box-shadow: inset 0 0 0 1px var(--line); }
.sd-lnk__sk i { display: block; height: 10px; border-radius: 4px; background: var(--soft); animation: sd-lnk-p 1s ease-in-out infinite alternate; }
.sd-lnk__sk i:first-child { height: 90px; }
@keyframes sd-lnk-p { to { opacity: 0.45; } }
.sd-lnk__ed { display: grid; gap: 6px; }
.sd-lnk__ed input { height: 32px; padding: 0 10px; border: 0; border-radius: 8px; background: var(--soft); color: var(--fg); font: inherit; font-size: 12.5px; outline: 0; }
.sd-lnk__bar { display: flex; justify-content: space-between; align-items: center; font-size: 12px; color: var(--mute); }
.sd-lnk__bar button { font-size: 12px; font-weight: 600; color: var(--fg) !important; text-decoration: underline; text-underline-offset: 2px; }
.sd-lnk__err { padding: 12px; border-radius: 12px; box-shadow: inset 0 0 0 1.5px var(--fg); font-size: 12.5px; }
@media (prefers-reduced-motion: reduce) { .sd-lnk *, .sd-lnk *::before, .sd-lnk *::after { animation: none !important; transition: none !important; } }Overview
The resolver you pass returns title, description, site and an optional image. While it runs, a skeleton holds the space so the composer does not jump.
Title and description can be edited before sharing; the layout toggles between a large card and a compact row.
When to use
- Message and post composers, CMS link fields.
When not to use
- Untrusted URLs without server-side fetching.
Installation
$
pnpm dlx shadcn@latest add https://sundaeui.dev/r/link-preview.json$
npx shadcn@latest add https://sundaeui.dev/r/link-preview.json$
yarn dlx shadcn@latest add https://sundaeui.dev/r/link-preview.json$
bunx --bun shadcn@latest add https://sundaeui.dev/r/link-preview.jsonWorks in any React project. Files are written to components/sundae/. Read the source in the stage’s Code view.
- No dependencies beyond React 18 or later.
- Copy link-preview.tsx and link-preview.css into components/sundae/.
- The CSS file is imported by the component, so no extra configuration is needed.
- Import the component and use it as shown below.
Usage
import { LinkPreview } from '@/components/sundae/link-preview'
<LinkPreview />Props
| Prop | Type | Default |
|---|---|---|
resolve*Fetches metadata. | (url: string) => Promise<{ title: string; description?: string; site: string; image?: boolean }> | — |
urlStarting URL. | string | — |
fillSurface: dark or light. | 'dark' | 'light' | 'dark' |
Accessibility
- The preview is an article with its title as a link; edits use labelled inputs.
- Loading state uses aria-busy.
- Reduced motion removes the movement and keeps every state change.
Customization
- Colours are CSS custom properties on .sd-lnk; override them in your own stylesheet.
- fill="light" switches the built-in light palette.
FAQ
- Is Link Preview free?
- Yes. Link Preview is free for personal and commercial projects, with full source on this page.
- How do I install Link Preview?
- Run npx shadcn@latest add https://sundaeui.dev/r/link-preview.json. The files are written to components/sundae/. It has no dependencies beyond React 18 or later.
- Does Link Preview support keyboard and screen readers?
- The preview is an article with its title as a link; edits use labelled inputs. Loading state uses aria-busy.
- Does Link Preview respect reduced motion?
- Reduced motion removes the movement and keeps every state change.
More like this
All components →Message Thread
Components · RefinedContact Card
Components · RefinedToast Stack
Components · Refined- Pro
Sheet Drawer
Components · Refined Avatar Stack
Components · Refined- Pro
Notification Center
Components · Refined