Embed Widget

The <flare-feed> widget is a self-contained web component you can drop onto any HTML page — no build step, no framework, no backend code. It fetches your published content from the Feed API and renders a paginated card list inside a Shadow DOM, so its styles never clash with your site.

Use the Widget Builder in your FlareBuilder workspace to configure and preview your widget visually, then copy the generated embed code.

Tip

The widget is the fastest path for Webflow, Wix, Squarespace, and other site builders. For full rendering control, see the JavaScript guide or the framework-specific guides.

---

Quick Start

1. Open Widget Builder in your FlareBuilder workspace (sidebar → Widget Builder).
2. Choose a channel, set your display options, and configure field mappings for each template.
3. Click Copy and paste the code into your page.

Or, start from scratch:

<script type="module" src="https://flarebuilder.com/widget/v1/flare-feed.min.js"></script>

<flare-feed
  src="https://your-org.flarebuilder.com/feed"
  max-items="10"
  show-image
  show-date
  show-tags
></flare-feed>

The widget loads, fetches your feed, and renders — no other setup required.

---

HTML Attributes

Attribute	Type	Default	Description
src	URL	—	Required. Feed URL. Supports all feed query parameters (tags, templates, status, etc.).
token	string	—	Channel access token for unlisted channel feeds.
max-items	number	10	Items per page (passed as ?limit= to the feed).
show-image	boolean	off	Show a feature image at the top of each card (requires an image field mapping).
show-date	boolean	off	Show the publication date.
show-author	boolean	off	Show the author name (only visible when the organization has enabled author attribution).
show-tags	boolean	off	Show tag pills at the bottom of each card.
show-title	boolean	off	Show the feed title (from the feed response) above the list.
date-format	string	short	Date display format: short, long, relative, or iso.
theme	string	light	Color theme: light, dark, or auto (follows system preference).
layout	string	list	Card layout: list (single column) or grid (responsive multi-column).
loading	string	—	Set to lazy to defer the initial fetch until the element scrolls into view.
link-target	string	_blank	Link target for item titles and action buttons: _blank or _self.

Boolean attributes are enabled by their presence — no value needed. show-image enables images; omitting it disables them.

Changing src or token triggers a full reload. Changing other attributes re-renders with the current data.

---

Filtering Content

Pass any Feed API query parameter directly in the src URL:

<!-- Show only "event" and "workshop" templates -->
<flare-feed
  src="https://your-org.flarebuilder.com/feed?templates=event,workshop"
  show-date
  show-tags
></flare-feed>

<!-- Show only items tagged "featured" -->
<flare-feed
  src="https://your-org.flarebuilder.com/feed?tags=featured"
  max-items="5"
  show-image
></flare-feed>

<!-- Upcoming events only -->
<flare-feed
  src="https://your-org.flarebuilder.com/feed?templates=event&event_start=2026-01-01T00:00:00"
  show-date
></flare-feed>

---

Template Field Mapping

By default the widget renders the item’s title, date_published, author, and tags. To display custom fields from your templates — summaries, images, event dates, action links — add a JSON config block inside the element.

The config maps slot names to field paths (sectionId.fieldId) for each template type:

<flare-feed
  src="https://your-org.flarebuilder.com/feed"
  show-image
  show-date
>
  <script type="application/json">
  {
    "templates": {
      "Event": {
        "summary":          "overview.description",
        "image":            "media.featurePhoto",
        "event_start":      "schedule.eventStart",
        "event_end":        "schedule.eventEnd",
        "location":         "schedule.room",
        "action_link":      "registration.registerUrl",
        "action_link_name": "'Register Now'"
      },
      "Blog Post": {
        "summary":      "content.excerpt",
        "image":        "content.headerImage",
        "html_content": "content.body"
      }
    }
  }
  </script>
</flare-feed>

The template name (e.g. "Event", "Blog Post") must match the template_name field returned by your feed exactly.

Mappable Slots

Slot	Description	Compatible field types
summary	Card body text (3-line clamp)	text, multiline
image	Feature image	image, media
event_start	Event start date	datetime, date
event_end	Event end date	datetime, date
location	Venue or location name	text
action_link	CTA button URL (defaults to permalink)	link
action_link_name	CTA button label text	text
html_content	Rich text rendered as HTML	richText

For action_link_name, wrap a static string in single quotes to use a literal label rather than a field value:

"action_link_name": "'Register Now'"

---

Channel Feeds

To embed an unlisted channel feed, pass the channel name in the src URL and its access token in token:

<flare-feed
  src="https://your-org.flarebuilder.com/feed/members-only"
  token="ch_abc123def456"
  show-date
  show-tags
></flare-feed>

Tokens are available in your FlareBuilder workspace under Channels.

---

Styling with CSS Variables

Set CSS custom properties on the <flare-feed> element (via style or an external stylesheet) to match your brand. The Shadow DOM reads these from the host element.

<flare-feed
  src="https://your-org.flarebuilder.com/feed"
  style="
    --ff-primary: #7c3aed;
    --ff-font-family: 'Inter', sans-serif;
    --ff-radius: 12px;
    --ff-spacing: 1.25rem;
  "
  show-image show-date show-tags
></flare-feed>

Or in a stylesheet:

flare-feed {
  --ff-primary: #7c3aed;
  --ff-font-family: 'Inter', sans-serif;
  --ff-radius: 12px;
}

CSS Variable Reference

Variable	Default	Description
--ff-primary	#4f46e5	Accent color — links, CTA button, hover highlights
--ff-text	#111827	Primary text color
--ff-text-muted	#6b7280	Secondary text — date, author, summary
--ff-surface	#ffffff	Card background
--ff-border	#e5e7eb	Card border and image placeholder
--ff-tag-bg	#f3f4f6	Tag pill background
--ff-tag-text	#374151	Tag pill text
--ff-spacing	1rem	Gap between cards and internal padding
--ff-radius	8px	Card and button border radius
--ff-font-family	inherit	Font family (inherits from host page by default)
--ff-font-size	1rem	Base font size
--ff-min-height	0	Minimum widget height
--ff-error	#dc2626	Error state text color
--ff-summary-lines	3	Lines to clamp in summary text
--ff-col-min	280px	Minimum column width in grid layout

Dark Theme

Set theme="dark" for a fixed dark theme, or theme="auto" to follow the visitor’s system preference:

<flare-feed theme="dark" src="..." show-date></flare-feed>
<flare-feed theme="auto" src="..." show-date></flare-feed>

/* Manual dark overrides */
flare-feed {
  --ff-text:      #f9fafb;
  --ff-text-muted:#9ca3af;
  --ff-surface:   #1f2937;
  --ff-border:    #374151;
  --ff-tag-bg:    #374151;
  --ff-tag-text:  #d1d5db;
}

---

Named Slots

Add elements with slot="name" as direct children of <flare-feed> to override default UI for specific states.

Slot	Default content	Triggered when
header	(empty)	Always — injected above the feed title and list
footer	Pagination controls	Always when there’s more than one page
loading	”Loading…”	While the feed request is in flight
empty	”No items to display.”	Feed returns zero items
error	”Failed to load feed.”	Network or HTTP error

<flare-feed src="https://your-org.flarebuilder.com/feed" show-date>
  <div slot="header"><h2>Latest News</h2></div>
  <div slot="loading">Fetching content…</div>
  <div slot="empty">Nothing here yet — check back soon.</div>
  <div slot="error">Could not load content. Please refresh.</div>
</flare-feed>

Note

The footer slot replaces the entire pagination UI. If you provide a footer slot, the built-in Previous/Next buttons are hidden.

---

Custom Item Template

For full control over each item’s HTML, add a <template data-template="item"> as a direct child. The widget clones this template for every item, binding data to elements that have data-bind attributes.

<flare-feed src="https://your-org.flarebuilder.com/feed" show-date>
  <script type="application/json">
  { "templates": { "Event": { "summary": "overview.description", "event_start": "schedule.start" } } }
  </script>

  <template data-template="item">
    <article class="my-card">
      <img data-bind="image" alt="">
      <div class="my-card-body">
        <h3><a data-bind="permalink"><span data-bind="title"></span></a></h3>
        <time data-bind="event_start"></time>
        <p data-bind="summary"></p>
        <a data-bind="action_link" class="my-btn">
          <span data-bind="action_link_name">View</span>
        </a>
      </div>
    </article>
  </template>
</flare-feed>

Elements with no matching data are hidden automatically (display: none). The custom template does not inherit the widget’s built-in styles — add your own CSS to the host page.

data-bind Values

Value	Behavior
title	Sets element text content
date	Sets text content to formatted publication date; sets datetime attribute on <time> elements
author	Sets element text content
permalink	Sets href on <a> elements
image	Sets src on <img>; sets background-image on other elements
summary	Sets element text content (from field mapping)
event_start	Formatted event start date
event_end	Formatted event end date
location	Sets element text content (from field mapping)
action_link	Sets href on <a> elements
action_link_name	Sets element text content
html_content	Sets element innerHTML (raw HTML — only use on trusted content)
tags	Renders each tag as a <span> inside the element

---

CSS Parts

Target internal widget elements from your external stylesheet using ::part():

/* Make titles larger */
flare-feed::part(item-title) {
  font-size: 1.2rem;
}

/* Remove card borders */
flare-feed::part(item) {
  border: none;
  box-shadow: 0 2px 8px rgba(0,0,0,0.08);
}

/* Style the CTA button */
flare-feed::part(item-action) {
  background: #7c3aed;
  color: white;
  border-color: #7c3aed;
}

CSS Part Reference

Part	Element
list	The <ul> containing all item cards
item	Individual item <li> card
item-image	Feature image <img>
item-body	Item body container
item-title	Title heading
item-meta	Meta row containing date and author
item-date	Publication date element
item-author	Author name span
item-summary	Summary paragraph
item-html-content	Rendered HTML content block
item-location	Location text
item-event	Event date range
item-action	CTA / action link button
item-tags	Tags container
header	Feed title heading (when show-title is set)
pagination	Pagination controls container
btn-prev	Previous page button
btn-next	Next page button

---

Events

The widget dispatches custom events on the <flare-feed> element. All events bubble and are composed (crossing the Shadow DOM boundary), so you can listen on a parent element too.

Event	Fired when	detail
flarefeed:fetching	A page request begins	{ page }
flarefeed:load	A page loads successfully	{ count, hasMore, page, items, pagination }
flarefeed:empty	A successful load returns zero items	(none)
flarefeed:error	A fetch fails	{ message }
flarefeed:page	The user navigates to a different page	{ page }

const feed = document.querySelector('flare-feed');

feed.addEventListener('flarefeed:load', (e) => {
  console.log(`Page ${e.detail.page} — ${e.detail.count} items`);
  console.log(e.detail.items);        // full item array
  console.log(e.detail.pagination);   // { next, has_more }
});

feed.addEventListener('flarefeed:empty', () => {
  document.querySelector('#feed-section').hidden = true;
});

feed.addEventListener('flarefeed:error', (e) => {
  console.error('Feed failed:', e.detail.message);
});

---

Complete Example

A fully configured event feed with custom styling, field mappings, and slot overrides:

<script type="module" src="https://flarebuilder.com/widget/v1/flare-feed.min.js"></script>

<style>
  flare-feed {
    --ff-primary: #7c3aed;
    --ff-font-family: 'Inter', sans-serif;
    --ff-radius: 10px;
    --ff-spacing: 1.25rem;
  }
  flare-feed::part(item-action) {
    background: #7c3aed;
    color: white;
    border-color: #7c3aed;
  }
</style>

<flare-feed
  src="https://your-org.flarebuilder.com/feed?templates=event&event_start=2026-01-01T00:00:00"
  max-items="6"
  show-image
  show-date
  show-tags
  theme="light"
>
  <script type="application/json">
  {
    "templates": {
      "Event": {
        "summary":          "overview.description",
        "image":            "media.featurePhoto",
        "event_start":      "schedule.eventStart",
        "event_end":        "schedule.eventEnd",
        "location":         "schedule.room",
        "action_link":      "registration.registerUrl",
        "action_link_name": "'Register'"
      }
    }
  }
  </script>

  <div slot="header"><h2 style="margin:0 0 1rem">Upcoming Events</h2></div>
  <div slot="empty">No upcoming events. Check back soon!</div>
</flare-feed>

---

JavaScript API

The widget is an ES module. Advanced users can import named exports directly for programmatic control or headless data fetching — no DOM rendering required.

Importing

<script type="module">
  import { createFlareClient, FlareFeed } from 'https://flarebuilder.com/widget/v1/flare-feed.min.js';
</script>

Importing the module also registers the <flare-feed> custom element automatically.

---

Headless Client

createFlareClient(src, options) returns a fetch client with no DOM involvement. Use it when you want the feed data but handle rendering yourself — in a framework component, a custom template, or alongside other UI.

import { createFlareClient } from 'https://flarebuilder.com/widget/v1/flare-feed.min.js';

const client = createFlareClient('https://your-org.flarebuilder.com/feed', {
  limit: 20,
  token: 'ch_abc123', // optional, for channel feeds
});

// First page
const page1 = await client.fetch();
console.log(page1.items);

// Next page — pass the URL from the previous response
if (page1.pagination.has_more) {
  const page2 = await client.fetchNext(page1.pagination.next);
}

// Jump to a specific cursor directly
const page = await client.fetch('cursor-string-here');

Options:

Option	Type	Default	Description
limit	number	20	Items per page
token	string	—	Channel access token for unlisted channel feeds

Methods:

Method	Returns	Description
fetch(cursor?)	Promise<FeedResponse>	Fetch the first page, or a specific page by cursor
fetchNext(nextUrl)	Promise<FeedResponse>	Fetch the next page using the pagination.next URL from a previous response

---

Imperative Methods

Call these directly on a mounted <flare-feed> element to drive it from JavaScript:

const feed = document.querySelector('flare-feed');

feed.refresh();            // Reset to page 1 and reload from the feed URL
feed.reset();              // Clear the widget and cancel any in-flight request
feed.goTo('cursor-here');  // Jump to a specific page by cursor string

Method	Description
refresh()	Resets pagination to page 1 and re-fetches
reset()	Cancels any in-flight request and clears the rendered output
goTo(cursor)	Navigates directly to the page at the given cursor

Tip

Cursors are opaque tokens — read them from e.detail.pagination.next in a flarefeed:load event or from the pagination.next URL returned by createFlareClient.