Embed Mastodon Hashtag Feeds on Your Website – FediTag.js

FediTag is a JavaScript library that embeds Mastodon posts from a specific account filtered by hashtag directly into your website.

It’s built as a custom web component that fetches posts through the Mastodon API and renders them with full support for media attachments, polls, and custom emojis.

Features:

• Mastodon API Integration:
  Fetches and displays up to 40 (the Mastodon API limit) of the most recent posts for a given user and hashtag combination.
• On-Demand Loading: Loads an initial batch of 5 posts and fetches more as the user scrolls.
• Rich Media Support: Correctly renders images, GIFs, videos, audio attachments, and polls directly in the feed.
• Content Formatting: Automatically renders custom emojis from the source instance and strips trailing hashtags from posts for a cleaner presentation.

How to use it:

1. Download and load the FediTag’s JavaScript & CSS files in the document.

<link rel="stylesheet" href="feditag.css">
<script src="feditag.js"></script>

2. Add the custom fedi-tag element wherever you want the feed to appear. The required attributes:

• host: The Mastodon instance domain without https:// protocol. Examples include mastodon.social, fosstodon.org, or your self-hosted instance domain.
• account: The numeric account ID for the Mastodon user. This is not the username. Look it up through the Mastodon API at https://your-instance/api/v1/accounts/lookup?acct=username. For example, if your username is photographer, visit https://mastodon.social/api/v1/accounts/lookup?acct=photographer to find the ID in the returned JSON.
• tag: The hashtag to filter posts by, without the # symbol. Case does not matter since Mastodon treats hashtags as case-insensitive.

<fedi-tag host="mastodon.social" account="1" tag="FilmPhotography">
</fedi-tag>

3. Override these classes to create your own styles:

• .feditag-post: Individual post container with padding and borders.
• .feditag-date: Timestamp and external link icon styling.
• .feditag-emoji: Custom emoji image sizing and positioning.
• .feditag-gallery: Media attachment container with flexbox layout.
• .feditag-gallery-item: Individual image thumbnail wrapper.
• .feditag-gallery-video: Video player container.
• .feditag-poll: Poll option container with bar graph styling.
• .feditag-poll-bar: The visual percentage bar for poll options.

FAQs

Q: Can I display posts from multiple hashtags?
A: Not with FediTag directly. The library filters by a single hashtag through the Mastodon API’s tagged parameter. You could run multiple fedi-tag elements on the same page with different hashtags, but they would display as separate feeds.

Q: What happens if the Mastodon instance is slow or down?
A: The feed shows “Loading posts…” indefinitely until the fetch completes or fails. FediTag does not implement timeout handling or error messages for failed API calls. The promise rejection goes uncaught, so you would see errors in the browser console but no user-facing message. You can wrap the fetch in the loadPosts method with a catch block to handle failures.

Q: Why does the library remove trailing hashtags?
A: Mastodon users commonly add hashtags at the end of posts for discovery. When displaying these posts outside Mastodon in a feed already filtered by that hashtag, showing the repeated hashtags becomes redundant and clutters the layout.

Q: How do I handle posts with sensitive content warnings?
A: FediTag does not process the spoiler_text field from the API response. Posts with content warnings display their full content immediately without the expandable warning that Mastodon shows. If you need content warning support, you would modify the renderPost method to check post.spoiler_text and conditionally hide post.content behind a button.

The post Embed Mastodon Hashtag Feeds on Your Website – FediTag.js appeared first on CSS Script.