llms.txt
Compare with other sites' llms.txt files →# FeedSpring
> FeedSpring is a social feed platform for adding live Instagram, Google Reviews, TikTok and Dribbble feeds to any website. It separates data from display: FeedSpring fetches, stores and refreshes the content, and you design the layout however you like. It works natively in Webflow and Framer, on any HTML-based platform through custom attributes, and anywhere else through a GraphQL API.
FeedSpring is used by 3,500+ businesses to display social proof and live content on their websites. There is a free plan, and paid plans start at $5/month billed annually.
Supported sources: Instagram, Google Reviews, TikTok, Dribbble. No other platforms are currently supported.
- Homepage: https://www.feedspring.com
- Documentation: https://docs.feedspring.com/introduction
- Dashboard and sign up: https://app.feedspring.com
- Pricing: https://www.feedspring.com/pricing
- Pre-built components: https://www.feedspring.com/components
- Agent skill: `npx skills add feedspring/skills`
---
## Choosing a delivery method
FeedSpring offers three ways to put a feed on a site. They all use the same underlying feed data.
| Building in | Use | Why |
|---|---|---|
| Framer | Pre-built Framer component | Framer runs React components natively. Every setting is exposed as a property control, so no code is needed |
| Webflow | Attributes, optionally starting from a pre-built Webflow component | Attributes are added visually in the Designer's element settings |
| WordPress, Shopify, Squarespace, Wix, Webstudio, plain HTML | Attributes | One script tag, no build step |
| React or Next.js, client-rendered | Attributes, with the script loaded client-side | Fastest route, no data layer to write |
| React or Next.js needing SSR, caching, or feed content in the page HTML for SEO | GraphQL API | Feed data is available at render time |
| Backend, mobile app, or data pipeline | GraphQL API | Not tied to the browser |
Guidance:
- Prefer a pre-built component when one exists for the platform and source.
- Attributes are the default for most marketing websites. Choose the API when there is a specific reason: server rendering, caching, SEO on feed content, transforming data, or a non-browser target.
- Attributes render in the browser, so feed content is not present in the initial page HTML. This rarely matters for Instagram. It matters for Google Reviews, where review text is often content a business wants indexed — offer the API in that case.
---
## Feed IDs
Every feed has a Feed ID, found in the FeedSpring dashboard. Feed IDs are public and safe to use in browser code. Each begins with a prefix identifying its source:
| Prefix | Source |
|---|---|
| `inst_` | Instagram |
| `google_` | Google Reviews |
| `tiktok_` | TikTok |
| `dribbble_` | Dribbble |
The Feed ID prefix, the script, and the field names must all match the same source.
### Placeholder Feed IDs
Always ask the user for their own Feed ID first. If they don't have one yet, these live placeholder feeds can be used to build and preview a layout:
| Source | Placeholder Feed ID |
|---|---|
| Instagram | `inst_55ZVUQExmdej0j8vygUoP` |
| Google Reviews | `google_1nCNRAgOgIYoTG3fhUX4c` |
| TikTok | `tiktok_7ZTDgAmbdnLstuHJ2srlq` |
| Dribbble | `dribbble_3qm4sGbu4uWQI2asUboPC` |
When using one, tell the user the feed is showing placeholder content and must be replaced with their own Feed ID before publishing.
---
## Attributes
You write your own HTML and add attributes that tell FeedSpring where to inject data. There is no widget or iframe — layout, styling and structure are entirely yours.
### 1. Add the script
Add the script for the feed source to the page `<head>`. Load only the scripts for the sources in use.
```html
<!-- Instagram -->
<script src="https://scripts.feedspring.com/instagram-attrs.js" async defer></script>
<!-- Google Reviews -->
<script src="https://scripts.feedspring.com/google-reviews-attrs.js" async defer></script>
<!-- TikTok -->
<script src="https://scripts.feedspring.com/tiktok-attrs.js" async defer></script>
<!-- Dribbble -->
<script src="https://scripts.feedspring.com/dribbble-attrs.js" async defer></script>
```
### 2. Add a feed wrapper and one post template
```html
<div feedspring="inst_YOUR-FEED-ID" feed-options="render:dynamic|limit:6">
<div feedspring="post">
<img feed-field="img" alt="" />
<p feed-field="caption"></p>
<a feed-field="link" target="_blank" rel="noopener">View post</a>
</div>
</div>
```
That is the whole model:
| Attribute | Placed on | Purpose |
|---|---|---|
| `feedspring="FEED-ID"` | Wrapper element | Declares the feed and which Feed ID to render |
| `feedspring="post"` | Element inside the wrapper | The post template |
| `feed-field="FIELD"` | Any element | Where a piece of data is injected |
| `feedspring="loading"` | Element inside the wrapper | Optional placeholder, removed once the feed renders |
`feed-field="item"` is an alias for `feedspring="post"`.
**Post fields go inside the post template. Profile fields go inside the wrapper, outside the post template** — for example a follower count or average rating in a header. Profile fields can also be placed inside a post template to repeat the same account-level value on every card.
A page can contain any number of feeds, including feeds from different sources.
### Element types matter
The element a `feed-field` is placed on decides what happens to the value. Placing a field on the wrong element type means it is skipped.
| Element | Behaviour |
|---|---|
| `<img>` | Sets `src`, and removes any `srcset` |
| `<a>` | Sets `href` |
| `<iframe>` | Sets `src` to an embed URL (TikTok `video` only) |
| Any other element | Inserts the value as text |
### Webflow
Add the script under Site Settings → Custom Code → Head Code, or Page Settings → Custom Code for a single page. Then add attributes through each element's Custom Attributes panel — for example name `feedspring`, value `YOUR-FEED-ID`. Place image fields on Image elements and link fields on Link Block or Text Link elements. Style everything normally in the Designer.
Webflow Interactions (IX2) are re-initialised after a feed renders, so interactions applied to feed items work as expected.
---
## Feed options
Set on the feed wrapper as pipe-separated `name:value` pairs. Order does not matter.
```html
<div feedspring="inst_YOUR-FEED-ID" feed-options="render:dynamic|skip:1|limit:6|lang:en-GB">
```
| Option | Description |
|---|---|
| `render:dynamic` | Clones one post template for each item. Recommended for grids, sliders and lists |
| `render:static` | Fills post templates already in the page, in order. This is the default |
| `limit:N` | Maximum number of items displayed |
| `skip:N` | Skips the first N items in the feed |
| `lang:xx-XX` | Locale for number formatting, e.g. `lang:en-GB`. Defaults to `en-US` |
| `lang:auto` | Uses the visitor's browser locale |
`skip` is applied first, then `limit` caps how many items are shown. `skip:2|limit:4` displays 4 items, starting from the 3rd. Both options work in dynamic and static rendering.
Unknown option names are ignored without an error, so check spelling.
### Dynamic vs static rendering
Use `render:dynamic` for most feeds. You design one post card and FeedSpring repeats it:
```html
<div feedspring="inst_YOUR-FEED-ID" feed-options="render:dynamic|limit:9">
<article feedspring="post">
<img feed-field="img" alt="" />
<p feed-field="caption"></p>
</article>
</div>
```
Use static rendering when different positions need different designs, such as a large featured post beside smaller cards. Place one `feedspring="post"` element for each slot and FeedSpring fills them in order:
```html
<div feedspring="inst_YOUR-FEED-ID">
<article feedspring="post" class="featured">
<img feed-field="img" alt="" />
<h2 feed-field="caption"></h2>
</article>
<article feedspring="post" class="small"><img feed-field="img" alt="" /></article>
<article feedspring="post" class="small"><img feed-field="img" alt="" /></article>
</div>
```
To combine layouts, use two wrappers with the same Feed ID — for example one showing the first post, and a second using `skip:1`.
### Post options
Set with `feed-options` on the `feedspring="post"` element itself:
| Option | Description |
|---|---|
| `appear:display-none` | Default. If the template has inline `style="display:none"`, it is cleared when the post renders. Use this to avoid an empty card flashing before data loads |
| `appear:display-block` | Sets `display: block` after rendering |
| `appear:display-flex` | Sets `display: flex` after rendering |
### Loading state
```html
<div feedspring="inst_YOUR-FEED-ID" feed-options="render:dynamic">
<div feedspring="loading">Loading…</div>
<article feedspring="post"><img feed-field="img" alt="" /></article>
</div>
```
The `feedspring="loading"` element is removed when the feed renders.
### Timestamps
Add `feed-timestamp` to an element with `feed-field="timestamp"`:
```html
<time feed-field="timestamp" feed-timestamp="from-now"></time>
<time feed-field="timestamp" feed-timestamp="MMMM D, YYYY"></time>
```
`from-now` renders relative time such as "2 days ago". Any other value is a Day.js format string. Without the attribute, the format is `MMMM D, YYYY`.
### Events
FeedSpring dispatches custom events on `document`. Listen for `feedspring:render-complete` to run code after a feed renders — for example to initialise a slider library:
```js
document.addEventListener('feedspring:render-complete', () => {
// initialise your slider here
})
```
`render-complete` fires once per rendered feed. `feedspring:init-complete`, `feedspring:load-complete` and `feedspring:error` are also dispatched.
---
## Fields by source
### Instagram
Script: `instagram-attrs.js` · Feed ID prefix: `inst_`
Post fields:
| `feed-field` | Content | Notes |
|---|---|---|
| `img` | Post image | Use on `<img>` |
| `bg` | Post image as a CSS background | Sets `background-image` on any element |
| `link` | Link to the post on Instagram | Use on `<a>` |
| `caption` | Post caption | May contain HTML, which is rendered |
| `like-count` | Likes | Compact format, e.g. `1.2K` |
| `comment-count` | Comments | Compact format |
| `timestamp` | Publish date | Can be empty on some posts |
Profile fields:
| `feed-field` | Content | Notes |
|---|---|---|
| `avatar` | Profile picture | Use on `<img>` |
| `name` | Display name | |
| `username` | @handle | |
| `bio` | Profile bio | |
| `follower-count` | Followers | Compact format |
| `following-count` | Accounts followed | Compact format |
Instagram images vary in aspect ratio (1:1, 4:5, 1.91:1). Crop to a fixed ratio with `object-fit: cover`, or use a masonry layout.
### Google Reviews
Script: `google-reviews-attrs.js` · Feed ID prefix: `google_`
Post fields:
| `feed-field` | Content | Notes |
|---|---|---|
| `review` | Review text | Plain text. Can be empty — some reviews are a rating only |
| `name` | Reviewer name | |
| `avatar` | Reviewer photo | Use on `<img>` |
| `rating` | Star rating as a number, 1–5 | |
| `rating-string` | Star rating as an English word, e.g. "five" | |
| `star` | Filled star template | Repeated once per rating point |
| `star-inactive` | Empty star template | Repeated for the remaining points up to 5 |
| `timestamp` | Review date | |
Profile fields:
| `feed-field` | Content | Notes |
|---|---|---|
| `average-rating` | Average rating | One decimal place, e.g. `4.8` |
| `total` | Total number of reviews | |
Stars are built from two templates you design. For a 4-star review FeedSpring renders 4 filled stars and 1 empty star:
```html
<div feedspring="post">
<div class="stars">
<svg feed-field="star"><!-- filled star --></svg>
<svg feed-field="star-inactive"><!-- empty star --></svg>
</div>
<p feed-field="review"></p>
<span feed-field="name"></span>
</div>
```
**There is no per-review link.** Google does not provide a URL for individual reviews. Instead, link to the business's Google listing, where visitors can read every review and leave their own. This is a normal link using the business's Google Place ID, not a feed field:
```html
<a href="https://search.google.com/local/reviews?placeid=YOUR_PLACE_ID" target="_blank" rel="noopener">Read all reviews on Google</a>
<a href="https://search.google.com/local/writereview?placeid=YOUR_PLACE_ID" target="_blank" rel="noopener">Leave a review</a>
```
Filtering by minimum star rating or by keyword is configured in the FeedSpring dashboard, not in markup.
### TikTok
Script: `tiktok-attrs.js` · Feed ID prefix: `tiktok_`
Post fields:
| `feed-field` | Content | Notes |
|---|---|---|
| `img` | Video thumbnail | Use on `<img>` |
| `video` | Playable video | Use on `<iframe>`. Loads TikTok's embed player |
| `link` | Link to the video on TikTok | Use on `<a>` |
| `title` | Video title | May contain HTML |
| `description` | Video description | May contain HTML. Often identical to `title` |
| `view-count` | Views | Compact format |
| `like-count` | Likes on this video | Compact format |
| `comment-count` | Comments | Compact format |
| `share-count` | Shares | |
| `duration` | Length in seconds | Raw number |
| `timestamp` | Publish date | |
Profile fields:
| `feed-field` | Content | Notes |
|---|---|---|
| `avatar` | Profile picture | Use on `<img>` |
| `name` | Display name | May contain HTML |
| `bio` | Profile bio | May contain HTML |
| `profile-link` | Link to the profile on TikTok | Use on `<a>` |
| `follower-count` | Followers | Compact format |
| `following-count` | Accounts followed | Compact format |
| `total-likes` | Total likes across the account | Compact format |
| `verified` | Verified badge | The element is kept for verified accounts and removed otherwise |
TikTok videos are 9:16 portrait. The `video` embed adds significant page weight; for lighter pages, show `img` inside a `link` instead.
### Dribbble
Script: `dribbble-attrs.js` · Feed ID prefix: `dribbble_`
Post fields:
| `feed-field` | Content | Notes |
|---|---|---|
| `img` | Shot image | Use on `<img>`. Shots are 4:3 |
| `link` | Link to the shot on Dribbble | Use on `<a>` |
| `title` | Shot title | |
| `tag` | Shot tags | The element is repeated once per tag |
| `timestamp` | Publish date | |
Profile fields:
| `feed-field` | Content | Notes |
|---|---|---|
| `avatar` | Profile picture | Use on `<img>` |
| `name` | Display name | |
| `bio` | Profile bio | May contain HTML |
| `location` | Location | |
| `profile-link` | Link to the profile on Dribbble | Use on `<a>` |
| `followers` | Followers | Compact format. Note: `followers`, not `follower-count` |
Dribbble does not provide like or view counts.
### Common mistakes
- There is no `caption` field on Google Reviews (`review`), TikTok (`title` or `description`) or Dribbble (`title`). `caption` exists on Instagram only.
- Google Reviews has no `link` field.
- Dribbble's follower field is `followers`. Instagram and TikTok use `follower-count`.
- TikTok `total-likes` is the account total. `like-count` is per video.
- Links must be on `<a>` elements and images on `<img>` elements.
- With `render:dynamic`, use exactly one post template.
---
## Complete example: Google Reviews cards
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>Google Reviews</title>
<script src="https://scripts.feedspring.com/google-reviews-attrs.js" async defer></script>
<style>
.summary { margin-bottom: 16px; }
.reviews { display: grid; grid-template-columns: repeat(auto-fill, minmax(260px, 1fr)); gap: 16px; }
.review { border: 1px solid #e5e5e5; border-radius: 12px; padding: 16px; }
.stars { display: flex; gap: 2px; color: #f5a623; }
.star-off { color: #d9d9d9; }
.review p:empty { display: none; }
.author { display: flex; align-items: center; gap: 8px; margin-top: 12px; }
.author img { width: 36px; height: 36px; border-radius: 50%; object-fit: cover; }
</style>
</head>
<body>
<section feedspring="google_YOUR-FEED-ID" feed-options="render:dynamic|limit:6">
<p class="summary">
<strong feed-field="average-rating"></strong> out of 5 from <span feed-field="total"></span> reviews
</p>
<div class="reviews">
<article class="review" feedspring="post">
<div class="stars">
<span feed-field="star">★</span>
<span feed-field="star-inactive" class="star-off">★</span>
</div>
<p feed-field="review"></p>
<div class="author">
<img feed-field="avatar" alt="" />
<strong feed-field="name"></strong>
<time feed-field="timestamp" feed-timestamp="from-now"></time>
</div>
</article>
</div>
<a href="https://search.google.com/local/reviews?placeid=YOUR_PLACE_ID" target="_blank" rel="noopener">Read all reviews on Google</a>
</section>
</body>
</html>
```
## Complete example: Instagram grid with profile header
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>Instagram Feed</title>
<script src="https://scripts.feedspring.com/instagram-attrs.js" async defer></script>
<style>
.profile { display: flex; align-items: center; gap: 12px; margin-bottom: 16px; }
.profile img { width: 48px; height: 48px; border-radius: 50%; }
.grid { display: grid; grid-template-columns: repeat(3, 1fr); gap: 12px; }
.post img { width: 100%; aspect-ratio: 1; object-fit: cover; border-radius: 8px; display: block; }
</style>
</head>
<body>
<section feedspring="inst_YOUR-FEED-ID" feed-options="render:dynamic|limit:6">
<header class="profile">
<img feed-field="avatar" alt="" />
<div>
<strong feed-field="name"></strong>
<div>@<span feed-field="username"></span> · <span feed-field="follower-count"></span> followers</div>
</div>
</header>
<div class="grid">
<article class="post" feedspring="post">
<a feed-field="link" target="_blank" rel="noopener">
<img feed-field="img" alt="" />
</a>
</article>
</div>
</section>
</body>
</html>
```
---
## Framer
1. Create a feed in the FeedSpring dashboard and copy its Feed ID.
2. Choose a component at https://www.feedspring.com/components and copy it into the Framer project.
3. Paste the Feed ID into the component's property controls.
4. Adjust post count, skip, typography, spacing, card style, radius and colours in Framer's properties panel.
FeedSpring's Framer components are React components. For a layout the property controls can't achieve, build a Framer code component and supply data with either attributes or the GraphQL API.
## React and Next.js
With attributes, load the script in the browser only — in Next.js use `next/script` with `strategy="afterInteractive"`, or add it in a `useEffect`. Custom attributes pass through JSX unchanged as strings: `feed-field="img"`. Avoid adding the script more than once on routes that remount.
For server rendering, caching or SEO, use the GraphQL API instead.
---
## GraphQL API
Endpoint: `https://api.feedspring.com/graphql` — `POST` requests with `Content-Type: application/json`.
No API key is required. The Feed ID is passed as the `publicKey` variable and is safe to use in browser code. Feeds can optionally be restricted to specific origins in the dashboard.
Schema: https://api.feedspring.com/graphql/schema.graphql (introspection is enabled).
`feed` returns a union type, so select `__typename` and use an inline fragment for the source. The collection field is named differently for each source:
| Source | GraphQL type | Collection |
|---|---|---|
| Instagram | `InstagramFeedData` | `posts` |
| TikTok | `TikTokFeedData` | `videos` |
| Dribbble | `DribbbleFeedData` | `shots` |
| Google Reviews | `GoogleReviewsFeedData` | `reviews` |
Images are objects. Request a URL, optionally resized: `image { url(input: { width: 800 }) }`. Resizing preserves aspect ratio and never crop