v1.0.0

@hwagfu/url-preview

Thẻ xem trước liên kết — đưa vào một URL, tự lấy metadata và render card đẹp.

Component React hiển thị thẻ xem trước liên kết. Chỉ cần đưa vào một URL, thư viện sẽ tự lấy metadata (tiêu đề, mô tả, ảnh, tên trang, tác giả, ngày đăng...) qua Microlink API và render thành card có thể tùy biến layout và theme. Kèm hook useLinkPreview và hàm fetchLinkPreview để tự dựng UI.

Playground

Chỉnh các thông số bên phải để xem component thay đổi trực tiếp.

urllayoutimagePosition

showDescription

showFavicon

showSiteName

showAuthor

showDate

Cài đặt

bash

npm install @hwagfu/url-preview

tsx

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

Tính năng

Tự lấy metadata qua Microlink API — không cần backend riêng.
Ba kiểu layout: large, wide và small.
Bật/tắt mô tả, favicon, tên trang, tác giả và ngày đăng.
Tùy biến theme: màu sắc, font, bo góc, đổ bóng.
Kèm hook useLinkPreview và fetchLinkPreview để tự dựng UI.
Cache theo URL; style inline sẵn, không cần thêm CSS.

Cách dùng

Dùng cơ bản

tsx

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

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

Ba kiểu layout

tsx

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

Theme

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)',
  }}
/>

Dùng hook riêng

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>;
}

Thuộc tính (Props)

Tên	Kiểu	Mặc định	Mô tả
url	string	—	URL cần xem trước (bắt buộc).
layout	"large" \| "wide" \| "small"	"large"	Kiểu bố cục card.
imagePosition	"top" \| "left" \| "right"	suy ra từ layout	Ghi đè vị trí ảnh (mặc định suy ra từ layout).
width	number \| string	tùy layout	Bề rộng card (số → px).
mediaHeight	number \| string	tùy layout	Chiều cao vùng ảnh (số → px).
showDescription	boolean	true	Hiện đoạn mô tả.
showFavicon	boolean	true	Hiện favicon/logo trang.
showSiteName	boolean	true	Hiện tên trang (publisher).
showAuthor	boolean	false	Hiện tác giả.
showDate	boolean	false	Hiện ngày đăng.
fetchOptions	FetchLinkPreviewOptions	—	Tùy chọn gọi Microlink (API key Pro, timeout).
theme	LinkPreviewCardTheme	—	Ghi đè màu sắc, font, bo góc, đổ bóng.

Lưu ý

LinkPreviewCard là export default duy nhất; useLinkPreview, fetchLinkPreview, invalidateLinkPreview và clearLinkPreviewCache là các named export.
Kết quả được cache theo URL. Dùng invalidateLinkPreview(url) để xóa một URL, hoặc clearLinkPreviewCache() để xóa toàn bộ.
Yêu cầu react và react-dom ^19.2.0 (peer dependencies).