Next.js Link Preview

A simple, lightweight Next.js component for displaying beautiful link preview cards.

Quick Start

Option 1: Install as npm package

npm install nextjs-link-preview

import { FaGithub } from "react-icons/fa";
import { LinkPreview } from "nextjs-link-preview";

<LinkPreview
  url="https://github.com/vercel/next.js"
  title="Next.js"
  description="The React Framework for the Web"
  preset={FaGithub}
/>;

Option 2: Copy to your project

npx nextjs-link-preview init

This copies the component source into src/components/LinkPreview.tsx. You own the code and can customize it however you want.

# Custom path
npx nextjs-link-preview init --path src/ui/LinkPreview.tsx

Features

• Pure presentational component - no data fetching
• Preset icon support via react-icons
• Custom icon support (react-icons, lucide, heroicons, any React element)
• Customizable text colors
• Three size variants (small, medium, large)
• Two layouts (vertical, horizontal)
• TypeScript support
• Fully customizable styling
• CLI copy-to-source support
• Peer deps only: React, Next.js, react-icons

Usage

Basic Usage

import { LinkPreview } from "nextjs-link-preview";

export default function Page() {
  return (
    <LinkPreview
      url="https://example.com"
      title="Example Site"
      description="This is an example website"
      image="https://example.com/preview.png"
    />
  );
}

With Preset Icons

import { FaGithub, FaNpm } from "react-icons/fa";

// GitHub
<LinkPreview
  url="https://github.com/user/repo"
  title="My Repository"
  description="A cool open source project"
  preset={FaGithub}
/>

// npm
<LinkPreview
  url="https://npmjs.com/package/my-package"
  title="my-package"
  description="An awesome npm package"
  preset={FaNpm}
/>

With Icons

Pass any React element as an icon. Works with react-icons, lucide, heroicons, or plain SVGs:

import { FaGithub } from "react-icons/fa";

<LinkPreview
  url="https://github.com/user/repo"
  title="My Repository"
  description="A cool open source project"
  icon={<FaGithub size={48} />}
/>;

Priority order: icon > image > preset.

Custom Text Colors

<LinkPreview
  url="https://example.com"
  title="Styled Preview"
  description="With custom colors"
  image="https://example.com/preview.png"
  titleColor="#1a1a2e"
  descriptionColor="#999"
/>

Size Variants

<LinkPreview url="..." title="..." image="..." size="small" />
<LinkPreview url="..." title="..." image="..." size="medium" /> {/* default */}
<LinkPreview url="..." title="..." image="..." size="large" />

Layouts

{/* Vertical (default) - image on top */}
<LinkPreview url="..." title="..." image="..." layout="vertical" />

{/* Horizontal - image on left */}
<LinkPreview url="..." title="..." image="..." layout="horizontal" />

Custom Styling

<LinkPreview
  url="https://example.com"
  title="Example"
  image="..."
  width="400px"
  className="my-custom-class"
/>

Props

| Prop | Type | Default | Description | | ------------------ | ------------------------------------ | ------------ | ------------------------------------------------------ | | url | string | required | Link destination | | title | string | required | Preview card title | | description | string | undefined | Preview card description | | image | string | undefined | Custom image URL | | preset | IconType | undefined | Preset icon component (from react-icons) | | icon | React.ReactNode | undefined | Custom icon element (takes priority over image/preset) | | size | "small" | "medium" | "large" | "medium" | Preview card size | | layout | "vertical" | "horizontal" | "vertical" | Image position | | width | string | number | "100%" | Card width | | height | string | number | "auto" | Card height | | className | string | "" | Additional CSS classes | | titleColor | string | undefined | Custom title text color | | descriptionColor | string | "#666" | Custom description text color |

Preset Icons

Pass any react-icons component as the preset prop. This gives you access to the full react-icons catalog.

Testing

To test the component locally:

npm test

This will:

1. Build the component
2. Start the demo at http://localhost:3000
3. Open your browser to see the interactive demo

License

MIT

Links

• GitHub
• npm