Vanilla

Installation

It is available as an npm package:
npm install microlinkjs --save
Optionally you can link it directly from the CDN as well:
<!-- Microlink SDK Vanilla/UMD bundle -->
<script src="//cdn.jsdelivr.net/npm/@microlink/[email protected]/umd/microlink.min.js"></script>
<!-- Microlink SDK AMD bundle -->
<script src="//cdn.jsdelivr.net/npm/@microlink/[email protected]/amd/microlink.min.js"></script>
<!-- Microlink SDK CJS bundle -->
<script type="text/javascript" src="//cdn.jsdelivr.net/npm/@microlink/[email protected]/cjs/microlink.min.js"></script>

Basic Usage

Microlink SDK provides the microlink method which takes a CSS selector (similar to jQuery/Zepto) to target elements you want to convert into beautiful preview cards.
Here are some usage examples:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<script>
  // Example 1
  // Replace all `a` tags for microlink cards
  microlink('a')

  // Example 2
  // Replace all elements with `link-preview` class
  // for microlink cards
  microlink('.link-previews')

  // Example 3
  // Replace all elements with `link-preview` class
  // for microlink cards, passing API specific options
  microlink('.link-previews')
</script>

Don't run it too late!

You need to add microlink to the page early in the page load.
We recommend calling the microlink method before the DOM finishes loading:
1
2
3
4
5
6
7
8
<!-- Add microlink before the closing body tag. -->
<script type="text/javascript" src="//cdn.jsdelivr.net/npm/[email protected]/umd/microlink.min.js"></script>

<!-- Call microlink to replace links with cards previews -->
<script>
  microlink('.link-preview')
</script>
</body>
...or on DOMContentLoaded:
1
2
3
4
5
6
7
<script>
  // Replace all elements with `link-preview` class
  // after DOM loaded
  document.addEventListener('DOMContentLoaded', function (event) {
    microlink('.link-previews')
  })
</script>

Customization

You can pass specific API Parameters to microlink as a second argument:
1
2
3
4
5
6
7
<script>
// Replace all elements with `link-preview` class
// for microlink large cards
microlink('.link-previews', {
  size: 'large'
})
</script>
You can also pass parameters as a data-attribute in the HTML markup of each element:
<a class="link" data-size="large" href="http://microlink.js.org">microlink.js.org</a>
Check the API parameters reference in order to know which options you can use.

Styling

We don't inject any CSS into your application. The card previsualization is shipped with a default minimal inline style.
If you need to adapt the look and feel, each component of the card has been assigned a BEM class name:

microlink_card

The root div of the card.

microlink_card__media

The media element, regardless of whether it's video or image.

microlink_card__media_image

The div holding the background-image of the image preview of the link.

microlink_card__media_video_wrapper

The wrapper div around the video preview of the link.

microlink_card__media_video

The video element for the video preview of the link.

microlink_card__content

The wrapper div around the content preview of the link.

microlink_card__content_title

The p tag of the card title.

microlink_card__content_description

The p tag of the card description.

microlink_card__content_url

The span tag of the card url link.
In order to apply your specific style, just declare your custom CSS rules using the properly class name.
For example, lets modify the font family used in the preview cards:
<style>
  .microlink-card {
    font-family: 'Nitti, "Microsoft YaHei", 微软雅黑, monospace';
    max-width: 100%;
  }
</style>
and voilá!

Recipes

Specifying a selector

You need to pass a selector to microlink in order to replace them with beautiful link previews.
Probably if you do that for all a present in the site, the result will not be as you expected: The selector's too generic.
A better strategy could be use a class and associate the class with the elements that you want to convert into links previews.
For example, you can use .link-preview for this purpose in your HTML markup:
<p>
  <a class="link-preview" href="https://github.com/zeit/next.js/"></a>
</p>
and then initialize microlink for these links:
<script>
microlink('.link-preview')
</script>
Also, you can associate a minimal CSS style for these links.
The following CSS adds some basic style resets to your link previews, also center aligning them horizontally:
1
2
3
4
5
6
7
8
9
<style>
  .link-preview {
    margin: auto;
    display: block;
    font-weight: normal;
    text-decoration: none;
    max-width: 500px;
  }
</style>