@hwagfu/url-preview

Tiếng Việt · English

Tiếng Việt

Thư viện React hiển thị thẻ xem trước liên kết (link preview card) — 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 một card đẹp, có thể tùy biến layout và theme.

Được xây dựng với React Compiler — không cần useMemo/useCallback thủ công.

Cài đặt

npm install @hwagfu/url-preview

Yêu cầu react và react-dom phiên bản ^19.2.0 (peer dependencies).

Sử dụng nhanh

LinkPreviewCard là export default duy nhất của package:

import LinkPreviewCard from '@hwagfu/url-preview'

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

Component tự lấy dữ liệu, tự xử lý trạng thái loading/lỗi, không cần thêm CSS bên ngoài (style inline sẵn).

Props

| Prop | Kiểu | Mặc định | Mô tả | |---|---|---|---| | url | string | (bắt buộc) | URL cần xem trước | | layout | 'large' \| 'wide' \| 'small' | 'large' | Kiểu bố cục card | | imagePosition | 'top' \| 'left' \| 'right' | suy ra từ layout | Ghi đè vị trí ảnh | | 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 |

Ba kiểu layout

// Ảnh nằm trên, dùng cho card lớn kiểu chia sẻ mạng xã hội
<LinkPreviewCard url="https://react.dev" layout="large" />

// Ảnh nằm cạnh (trái/phải), phù hợp danh sách/feed
<LinkPreviewCard url="https://react.dev" layout="wide" imagePosition="right" />

// Card gọn, chỉ có ảnh thumbnail nhỏ + tiêu đề
<LinkPreviewCard url="https://react.dev" layout="small" />

Theme

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

Tất cả field của theme đều optional — chỉ cần ghi đè phần bạn muốn.

Microlink Pro API key

<LinkPreviewCard
  url="https://react.dev"
  fetchOptions={{ apiKey: process.env.MICROLINK_API_KEY, timeoutMs: 8000 }}
/>

Dùng hook riêng: useLinkPreview

Muốn tự dựng UI thay vì dùng LinkPreviewCard có sẵn:

import { useLinkPreview } from '@hwagfu/url-preview'

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

  if (state.status === 'loading') return <p>Đang tải...</p>
  if (state.status === 'error') return <p>Lỗi: {state.error.message}</p>

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

Gọi thẳng API: fetchLinkPreview

import { fetchLinkPreview } from '@hwagfu/url-preview'

const data = await fetchLinkPreview('https://react.dev')

Kết quả được cache theo URL. Dùng invalidateLinkPreview(url) để xóa cache một URL, hoặc clearLinkPreviewCache() để xóa toàn bộ.

Phát triển thư viện

npm install                        # cài dependency
npm run play                       # chạy playground
npx playwright install chromium    # chỉ cần chạy lần đầu, để test được
npm run test                       # chạy unit test
npm run typecheck                  # kiểm tra type
npm run build                      # build ra dist/

English

A React library 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.

Built with React Compiler — no manual useMemo/useCallback needed.

Install

npm install @hwagfu/url-preview

Requires react and react-dom ^19.2.0 (peer dependencies).

Quick start

LinkPreviewCard is the package's sole default export:

import LinkPreviewCard from '@hwagfu/url-preview'

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

The component fetches its own data and handles loading/error states — no external CSS needed (styles are inlined).

Props

| Prop | Type | Default | Description | |---|---|---|---| | url | string | (required) | URL to preview | | layout | 'large' \| 'wide' \| 'small' | 'large' | Card layout preset | | imagePosition | 'top' \| 'left' \| 'right' | derived from layout | Override media position | | width | number \| string | depends on layout | Card width (numbers → px) | | mediaHeight | number \| string | depends on 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 |

Three layouts

// Image on top — social-share style, large card
<LinkPreviewCard url="https://react.dev" layout="large" />

// Image beside the text (left/right) — good for lists/feeds
<LinkPreviewCard url="https://react.dev" layout="wide" imagePosition="right" />

// Compact card — small thumbnail + title only
<LinkPreviewCard url="https://react.dev" layout="small" />

Theming

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

Every theme field is optional — override only what you need.

Microlink Pro API key

<LinkPreviewCard
  url="https://react.dev"
  fetchOptions={{ apiKey: process.env.MICROLINK_API_KEY, timeoutMs: 8000 }}
/>

Using the hook directly: useLinkPreview

For building your own UI instead of LinkPreviewCard:

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

Calling the API directly: fetchLinkPreview

import { fetchLinkPreview } from '@hwagfu/url-preview'

const data = await fetchLinkPreview('https://react.dev')

Results are cached per URL. Use invalidateLinkPreview(url) to clear one entry, or clearLinkPreviewCache() to clear everything.

Local development

npm install                        # install dependencies
npm run play                       # run the playground
npx playwright install chromium    # first time only, required for tests
npm run test                       # run unit tests
npm run typecheck                  # type-check
npm run build                      # build to dist/