Widget Embed Guide

A drop-in JavaScript library that renders a styled news feed inside any website. It uses Shadow DOM for CSS isolation, preventing style conflicts with your page.

API Base URL: https://wingnews.theinvestinsight.com

---

Quick Start

Add the script tag and initialize with your API key:

<div id="news-feed"></div>

<script src="https://wingnews.theinvestinsight.com/widget/news-widget.iife.js"></script>
<script>
  NewsWidget.init({
    apiKey: 'na_live_abc123...',
    container: '#news-feed',
  });
</script>

That's it — a news feed with the default configuration will render in the #news-feed element.

---

Installation

Three bundle formats are available:

Format	File	Usage
IIFE	news-widget.iife.js	<script> tag, global NewsWidget
ESM	news-widget.esm.js	import { NewsWidget } from '...'
UMD	news-widget.umd.js	CommonJS / AMD / global

ESM Example

import { NewsWidget } from 'https://wingnews.theinvestinsight.com/widget/news-widget.esm.js';

const widget = NewsWidget.init({
  apiKey: 'na_live_abc123...',
  container: '#news-feed',
  theme: 'dark',
  layout: 'grid',
});

---

Configuration

Pass a configuration object to NewsWidget.init(). Only apiKey and container are required.

Option	Type	Default	Description
apiKey	string	(required)	Your API key
container	string | HTMLElement	(required)	CSS selector or DOM element
apiBaseUrl	string	current origin	API base URL (for self-hosted deployments)
theme	'light' | 'dark' | 'auto'	'auto'	Color theme (auto follows system preference)
layout	'list' | 'grid' | 'ticker'	'list'	Display layout (details)
itemCount	number	10	Initial number of items to load (max: 50)
showImages	boolean	true	Show article thumbnail images
showSummary	boolean	true	Show article summary text
showDate	boolean	true	Show publication date
dateFormat	'relative' | 'absolute'	'relative'	Date display ("2 hours ago" vs "Feb 15, 2026")
refreshInterval	number	0	Auto-refresh interval in seconds (0 = off)
clickBehavior	string	'modal'	How item clicks are handled (details)
pagination	string	'none'	Pagination mode (details)
maxHeight	string	'600px'	Maximum widget height (CSS value)
borderRadius	string	'8px'	Container border radius (CSS value)
fontFamily	string	system stack	Font family override (CSS value)

---

Filters

Narrow the articles displayed in the widget:

NewsWidget.init({
  apiKey: 'na_live_abc123...',
  container: '#news-feed',
  filters: {
    languages: ['es', 'pt'],
    topics: ['crypto', 'markets'],
    dateFrom: '2026-02-01T00:00:00Z',
    dateTo: '2026-02-28T23:59:59Z',
  },
});

Filter	Type	Description
languages	string[]	Language codes
topics	string[]	Topic identifiers
query	string	Full-text search query
dateFrom	string	Start date (ISO-8601)
dateTo	string	End date (ISO-8601)

---

Date Filter UI

Enable an interactive date picker for users to filter articles by date:

NewsWidget.init({
  apiKey: 'na_live_abc123...',
  container: '#news-feed',
  dateFilter: {
    enabled: true,
    presets: ['today', 'yesterday', 'week', 'month'],
    defaultPreset: 'week',
    allowCustomRange: true,
  },
});

You can also pass dateFilter: true as a shorthand to enable with defaults.

Available Presets: today, yesterday, week, month, custom

---

Layouts

List — Vertical layout with thumbnails alongside title and summary. Best for sidebar or narrow containers.

{ layout: 'list' }

Grid — Card-based layout. Best for wide containers where you want a magazine-style look.

{ layout: 'grid' }

Ticker — Horizontal scrolling ribbon. Best for a breaking-news banner at the top of a page.

{ layout: 'ticker' }

---

Click Behavior

Control what happens when a user clicks an article:

Value	Behavior
'modal'	Opens article content in a modal overlay (default)
'expand'	Expands the article inline to show full content
'callback'	Fires the onItemClick callback — no default action

---

Pagination

Mode	Behavior
'none'	Shows only the initial itemCount items (default)
'infinite'	Loads more articles as the user scrolls (cursor-based)
'numbered'	Displays page buttons below the feed (offset-based)

---

Callbacks

NewsWidget.init({
  apiKey: 'na_live_abc123...',
  container: '#news-feed',
  onLoad: (items) => {
    console.log(`Loaded ${items.length} articles`);
  },
  onItemClick: (item, event) => {
    console.log('Clicked:', item.title);
  },
  onError: (error) => {
    console.error('Widget error:', error.message);
  },
});

Callback	Arguments	Trigger
onLoad	(items: NewsItem[])	After articles are loaded/refreshed
onItemClick	(item: NewsItem, event: MouseEvent)	When an article is clicked
onError	(error: Error)	On API or rendering error

---

Instance Methods

NewsWidget.init() returns a widget instance with these methods:

const widget = NewsWidget.init({ ... });

widget.refresh();                  // Reload articles from the API
widget.setTheme('dark');           // Switch theme
widget.setLayout('grid');          // Switch layout
widget.setConfig({ itemCount: 20 }); // Update any configuration
widget.getItems();                 // Get currently displayed items
widget.destroy();                  // Remove the widget and clean up

---

Multiple Instances

You can run multiple widgets on the same page, each with independent configuration:

<div id="spanish-news"></div>
<div id="japanese-news"></div>

<script>
  NewsWidget.init({
    apiKey: 'na_live_abc123...',
    container: '#spanish-news',
    filters: { languages: ['es'] },
  });

  NewsWidget.init({
    apiKey: 'na_live_abc123...',
    container: '#japanese-news',
    filters: { languages: ['ja'] },
    theme: 'dark',
  });
</script>

Instance Management

NewsWidget.getInstance('#spanish-news'); // Get instance by selector
NewsWidget.getInstances();               // Get all instances
NewsWidget.destroy('#spanish-news');     // Destroy by selector
NewsWidget.destroyAll();                 // Destroy all instances

---

Language Codes

Supported languages for the languages filter:

Code	Language
ar	Arabic
de	German
es	Spanish
fr	French
hu	Hungarian
id	Indonesian
it	Italian
ja	Japanese
pt	Portuguese
ru	Russian
tr	Turkish
vi	Vietnamese
zh	Chinese