v1.0.0

@hwagfu/url-preview

A link preview card — pass a URL and it fetches metadata and renders a card.

A React component that renders a link preview card. Pass in a URL and it fetches metadata (title, description, image, site name, author, date...) via the Microlink API and renders a customizable card. Ships a useLinkPreview hook and a fetchLinkPreview function for building your own UI.

Playground

Tweak the controls on the right to see the component update live.

urllayoutimagePosition

showDescription

showFavicon

showSiteName

showAuthor

showDate

Installation

bash

npm install @hwagfu/url-preview

tsx

import LinkPreviewCard from "@hwagfu/url-preview";

Features

Fetches metadata via the Microlink API — no backend needed.
Three layout presets: large, wide and small.
Toggle description, favicon, site name, author and date.
Themeable: colors, fonts, corner radius and shadow.
Ships a useLinkPreview hook and fetchLinkPreview for custom UIs.
Cached per URL; styles are inlined, no extra CSS required.

Usage

Basic usage

tsx

import LinkPreviewCard from "@hwagfu/url-preview";

export default function App() {
  return <LinkPreviewCard url="https://react.dev" />;
}

Three layouts

tsx

<LinkPreviewCard url="https://react.dev" layout="large" />
<LinkPreviewCard url="https://react.dev" layout="wide" imagePosition="right" />
<LinkPreviewCard url="https://react.dev" layout="small" />

Theming

tsx

<LinkPreviewCard
  url="https://react.dev"
  theme={{
    backgroundColor: '#1a1a1a',
    textColor: '#f5f5f5',
    mutedColor: '#a0a0a0',
    borderColor: '#333333',
    borderRadius: '16px',
    boxShadow: '0 4px 16px rgba(0,0,0,0.4)',
  }}
/>

Using the hook directly

tsx

import { useLinkPreview } from "@hwagfu/url-preview";

function CustomPreview({ url }: { url: string }) {
  const state = useLinkPreview(url);

  if (state.status === "loading") return <p>Loading...</p>;
  if (state.status === "error") return <p>Error: {state.error.message}</p>;

  return <h3>{state.data.title}</h3>;
}

Props

Name	Type	Default	Description
url	string	—	URL to preview (required).
layout	"large" \| "wide" \| "small"	"large"	Card layout preset.
imagePosition	"top" \| "left" \| "right"	suy ra từ layout	Override media position (derived from layout by default).
width	number \| string	tùy layout	Card width (numbers → px).
mediaHeight	number \| string	tùy layout	Media area height (numbers → px).
showDescription	boolean	true	Show the description.
showFavicon	boolean	true	Show the site favicon/logo.
showSiteName	boolean	true	Show the publisher name.
showAuthor	boolean	false	Show the author.
showDate	boolean	false	Show the publish date.
fetchOptions	FetchLinkPreviewOptions	—	Microlink fetch options (Pro API key, timeout).
theme	LinkPreviewCardTheme	—	Override colors, fonts, radius, shadow.

Notes

LinkPreviewCard is the sole default export; useLinkPreview, fetchLinkPreview, invalidateLinkPreview and clearLinkPreviewCache are named exports.
Results are cached per URL. Use invalidateLinkPreview(url) to clear one entry, or clearLinkPreviewCache() to clear everything.
Requires react and react-dom ^19.2.0 (peer dependencies).