Skip to content
Astro Embed

Link Preview

The <LinkPreview> component embeds the Open Graph media and metadata for a URL in your page.

Usage

---
import { LinkPreview } from 'astro-embed';
---


<LinkPreview id="https://astro.build/blog/welcome-world/" />

The above code produces the following result:

Welcome, World | Astro astro.build
Astro's new look is live! Learn all about our new brand including the design process, our new logo, typeface, color palette, and mascot.
Welcome, World

Video metadata

If a URL’s tags include og:video metadata, <LinkPreview> will render a video player instead of an image.

<LinkPreview id="https://fosstodon.org/@mikeneu/112123823339364565" />

The above code produces the following result:

Mike Neumegen (@mikeneu@fosstodon.org) fosstodon.org
Attached: 1 video "Ship just want the user needs" has become a radical idea that frameworks like @astro@webtoo.ls and @eleventy excel at. @jlengstorf@hachyderm.io sharing a wealth of Jamstack nuggets in our What the Jam interview - https://www.youtube.com/watch?v=0YVCwD_Y7ts https://TheFutureOfJamstack.org #TheFutureOfJamstack

Limitations

The available Open Graph metadata varies from site to site. If a site doesn’t provide og:image metadata, no image will be displayed, only the page title and description.

If no title is detected or the metadata collection step fails, <LinkPreview> will display only the original link URL.

Styling the preview

By default the <LinkPreview> card has some minimal layout styling, which should adapt to your site’s font settings etc.

You can customise it with CSS by targeting the .link-preview class, for example:

.link-preview {
  --link-preview-corners: 0.5em;
  --link-preview-padding-inline: 0.75rem;
  background-color: floralwhite;
  color: darkblue;
  font-family: sans-serif;
  box-shadow: 0 4px 8px rgba(0, 0, 0, 0.3);
}
.link-preview a {
  color: purple;
  font-weight: bold;
  text-decoration: none;
}

The above styles would render <LinkPreview> like this:

Astro Embed astro-embed.netlify.app
High performance, rich media embed components. For your site, from the Astro community.

Custom properties API

The <LinkPreview> component supports the following API for controlling its styles with CSS custom properties.

:root {
  /** Set the maximum width of the link preview. */
  --link-preview-width: 30em;
  /** Set the inline padding of the card text. */
  --link-preview-padding-inline: 1em;
  /** Set the vertical padding around the card text. */
  --link-preview-padding-block: 0.5em;
  /** Round the corners of the link preview card. */
  --link-preview-corners: 0.5em;
}

CSS class names API

  • .link-preview: The root element of the <LinkPreview> card.
  • .link-preview--has-video: Class applied to the card when it includes video instead of an image.
  • .link-preview--no-media: Class applied to the card when it includes no image or video.
  • .link-preview--no-metadata: Class applied when metadata scraping failed, or no valid title was found. In this case the only contents of the card is the original URL link.

Optional props

In addition to the required id prop, the following props are available to customise how the <LinkPreview> component renders:

downloadPoster

Type: boolean

Download the poster image and host it on the same server as your website.

This attribute can only be used if the og:image metadata exists.

<LinkPreview id="https://astro.build/blog/welcome-world/" downloadPoster />

To use the downloadPoster attribute, need to add the address of the image server to astro.config.mjs as follows:

export default defineConfig({
  image: {
    domains: ['astro.build'],
  },
});

Standalone installation

If you only need the <LinkPreview> component, you can install the package directly instead of the main astro-embed package:

Terminal window
npm i @astro-community/astro-embed-link-preview

The <LinkPreview> component can then be imported as:

import { LinkPreview } from '@astro-community/astro-embed-link-preview';