π¨ A comprehensive TypeScript utility library for building powerful User-Generated Content (UGC) widgets
@stackla/widget-utils
is a feature-rich library that provides everything you need to build, customize, and deploy UGC widgets. Whether you're creating a simple content gallery or a complex interactive widget with carousels, infinite scrolling, and dynamic templates, this library has you covered.
- π― TypeScript First - Fully typed API for excellent IDE support and type safety
- π¨ Flexible Templating - Support for Handlebars templates with custom helpers
- βοΈ JSX Support - Build widgets using JSX syntax without React
- πͺ Widget Loading - Automated widget initialization and lifecycle management
- π Infinite Scrolling - Built-in hooks for seamless content loading
- π¦ Modular Architecture - Import only what you need with tree-shakeable exports
- π Extension Support - Includes Swiper carousel integration out of the box
- π¨ CSS Variables - Dynamic theming and styling support
- π‘ Event System - Comprehensive event handling for widget interactions
- π Embed Utilities - Easy widget embedding for both v2 and v3 widgets
npm install @stackla/widget-utils
yarn add @stackla/widget-utils
pnpm add @stackla/widget-utils
import { loadWidget } from "@stackla/widget-utils"
// Initialize a widget with default settings
const sdk = await loadWidget({
features: {
showTitle: true,
preloadImages: true,
addNewTilesAutomatically: true
}
})
import { jsx } from '@stackla/widget-utils/jsx';
const TileComponent = ({ title, image }) => (
<div className="tile">
<img src={image} alt={title} />
<h3>{title}</h3>
</div>
);
The primary entry point providing widget loading, core types, events, and library utilities.
Key Exports:
loadWidget()
- Initialize and configure widgetsISdk
- TypeScript interface for widget SDK- Widget lifecycle hooks and event handlers
Comprehensive TypeScript type definitions for widgets, tiles, components, and services.
Includes:
Widget
,Tile
,Placement
- Core data typesWidgetOptions
,WidgetSettings
- Configuration types- Service interfaces for tiles, events, and widgets
- Component types for static content, products, and UGC
JSX-to-HTML runtime that lets you write components using JSX syntax without React.
Features:
- Lightweight JSX transformation
- Event handler support
- Ref support for DOM access
- Type-safe JSX elements
Handlebars template engine with custom helpers designed for widget rendering.
Custom Helpers:
{{tile}}
- Render tile components{{ifEquals}}
- Conditional rendering{{lazy}}
- Lazy loading support{{join}}
- Array joining{{ifAutoPlayVideo}}
- Video autoplay detection{{ifHasProductTags}}
- Product tag checking{{ifHasPublicTags}}
- Public tag checking{{tagFallbackUsername}}
- Username fallback logic
Core library utilities for widget features and functionality.
Includes:
- CSS variable management
- Widget feature toggles
- Layout utilities
- Tile manipulation helpers
Pre-built component utilities for common widget patterns.
Available Components:
- Static content components
- Product display components
- Share menu components
- Add-to-cart components
- UGC tile components
Widget extensions for enhanced functionality.
Current Extensions:
- Swiper - Carousel/slider integration
Full Swiper carousel integration for creating image/content sliders.
Features:
- Automatic initialization
- Responsive configuration
- Touch/swipe support
- Navigation and pagination
Event system for widget lifecycle and user interactions.
Event Types:
- Widget initialization events
- Tile interaction events
- Load more events
- User action events
Utilities for embedding widgets into web pages.
Features:
- Support for v2 and v3 widgets
- Environment configuration (staging/production)
- Auto-detection of widget version
- Shadow DOM support
Template utilities and pre-built templates.
Bundled distribution for direct browser usage.
interface WidgetSettings {
features?: {
showTitle?: boolean // Display widget title
preloadImages?: boolean // Preload images for performance
disableWidgetIfNotEnabled?: boolean // Auto-disable on config
addNewTilesAutomatically?: boolean // Auto-add new tiles
handleLoadMore?: boolean // Enable load more functionality
hideBrokenImages?: boolean // Hide broken image tiles
loadTileContent?: boolean // Load tile content dynamically
loadTimephrase?: boolean // Load time phrases
}
callbacks?: {
// Custom callback functions
}
templates?: {
// Custom templates
}
config?: {
// Additional configuration
}
}
import { loadWidget } from "@stackla/widget-utils"
import { renderTilesWithTemplate } from "@stackla/widget-utils/handlebars"
const sdk = await loadWidget({
features: {
preloadImages: true,
hideBrokenImages: true
}
})
const tiles = await sdk.getTiles()
const html = await renderTilesWithTemplate(tileTemplate, tiles, {
wid: "your-widget-id"
})
import { initSwiper } from "@stackla/widget-utils/extensions/swiper"
const swiper = initSwiper(".swiper-container", {
slidesPerView: 3,
spaceBetween: 30,
navigation: true,
pagination: {
clickable: true
}
})
import { embed } from "@stackla/widget-utils/embed"
await embed({
widgetId: "your-widget-id",
root: document.getElementById("widget-container"),
environment: "production",
dataProperties: {
// Custom data attributes
}
})
src/
βββ constants.ts # Global constants
βββ embed/ # Widget embedding utilities
βββ events/ # Event system
βββ fonts.ts # Font loading utilities
βββ handlebars/ # Handlebars templates and helpers
βββ hooks/ # React hooks
βββ index.ts # Main entry point
βββ libs/ # Core library utilities
β βββ components/ # Component utilities
β βββ css-variables.ts # CSS variable management
β βββ extensions/ # Widget extensions
β βββ jsx-html.ts # JSX runtime
β βββ tile.lib.ts # Tile utilities
β βββ widget.features.ts # Widget features
β βββ widget.layout.ts # Layout utilities
β βββ widget.utils.ts # Widget utilities
βββ styles/ # Style utilities
βββ types/ # TypeScript type definitions
β βββ components/ # Component types
β βββ core/ # Core types
β βββ services/ # Service types
β βββ loader.ts # Loader types
βββ widget-loader.ts # Widget loader implementation
npm test
npm run build
npm run lint
npm run typecheck
Contributions are welcome! Please ensure your code:
- Passes all tests (
npm test
) - Follows the linting rules (
npm run lint
) - Includes proper TypeScript types
- Is documented with JSDoc comments where appropriate
- Social Media Galleries - Display Instagram, Twitter, and other social feeds
- Product Showcases - Feature user-generated product reviews and photos
- Event Coverage - Aggregate and display event content from multiple sources
- Community Walls - Create interactive community content displays
- Marketing Campaigns - Build engaging campaign landing pages with UGC
Built with β€οΈ by Nosto