Tutorials

Build your first link preview

Add the LinkMetadata component to a page and fetch metadata from the API.

LinkMetadata gives you two ways to work with URLs:

  • Use the preview component when you want a ready-made link card.
  • Use the metadata API when you want JSON for your own UI.

The API is free to use and does not require signup or API keys. Requests are limited to 20 per 10 seconds per IP address; when the limit is reached, that IP is blocked for 10 seconds.

Add the component

Load the component once on the page:

<script type="module" src="https://api.linkmetadata.com/component.js" async></script>

Then add a preview wherever you want the card to appear:

<link-metadata-preview data-url="https://linkmetadata.com"></link-metadata-preview>

Multiple previews can appear on the same page. The component fetches metadata, renders a link card, and falls back to a plain link if metadata cannot be loaded.

Fetch metadata directly

Use the API when you want to render your own UI:

const params = new URLSearchParams({ url: "https://linkmetadata.com" });
const response = await fetch(`https://api.linkmetadata.com/v1/metadata?${params}`);
const metadata = await response.json();

The API is CORS-enabled, so browser apps can call it directly.

Understand safety tags

Responses include safety_tags, an array of readable labels. Possible values are adult, security_threat, and suspicious_domain. The array is empty when no tag applies or lookup fails.

For guidance on how to use these labels in your product, see Safety tags.

Next steps